Struct CBig 

pub struct CBig { /* private fields */ }

Arbitrary-precision complex number re + im·i, with each component a decimal DBig.

See the crate-level documentation for the rationale behind the absence of Hash, Eq, and Ord.

Implementations

impl CBig

pub fn to_f64_parts(&self) -> (f64, f64)

Project both components down to f64, returning (re, im).

Precision

This conversion is lossy: each arbitrary-precision DBig component is rounded to the nearest f64. Values whose magnitude exceeds f64::MAX saturate to ±∞, and digits beyond the 53-bit mantissa are discarded. Use it only when an ordinary floating-point approximation is acceptable.

Examples

use oxinum_complex::CBig;
let z = CBig::from_f64(3.5, -1.25).expect("finite parts");
assert_eq!(z.to_f64_parts(), (3.5, -1.25));

impl CBig

pub fn asin(&self, precision: usize) -> OxiNumResult<CBig>

The principal value of arcsin z at precision significant digits.

Uses the identity asin z = −i · ln(i·z + √(1 − z²)).

Errors

Propagates errors from CBig::sqrt / CBig::ln.

pub fn acos(&self, precision: usize) -> OxiNumResult<CBig>

The principal value of arccos z at precision significant digits.

Uses the identity acos z = −i · ln(z + i·√(1 − z²)).

Errors

Propagates errors from CBig::sqrt / CBig::ln.

pub fn atan(&self, precision: usize) -> OxiNumResult<CBig>

The principal value of arctan z at precision significant digits.

Uses the identity atan z = (i/2)·[ln(1 − i·z) − ln(1 + i·z)].

Errors

Propagates errors from CBig::ln.

pub fn asinh(&self, precision: usize) -> OxiNumResult<CBig>

The principal value of arcsinh z at precision significant digits.

Uses the identity asinh z = ln(z + √(z² + 1)).

Errors

Propagates errors from CBig::sqrt / CBig::ln.

pub fn acosh(&self, precision: usize) -> OxiNumResult<CBig>

The principal value of arccosh z at precision significant digits.

Uses acosh z = ln(z + √(z−1)·√(z+1)) (factored, not √(z²−1)) to place the branch cut on (−∞, 1], consistent with C99 / num-complex.

Errors

Propagates errors from CBig::sqrt / CBig::ln.

pub fn atanh(&self, precision: usize) -> OxiNumResult<CBig>

The principal value of arctanh z at precision significant digits.

Uses the identity atanh z = ½·[ln(1 + z) − ln(1 − z)].

Errors

Propagates errors from CBig::ln.

impl CBig

pub fn checked_div(&self, rhs: &CBig) -> OxiNumResult<CBig>

Divides self by rhs without panicking.

Returns OxiNumError::DivByZero when rhs is zero; otherwise yields self / rhs computed as (self · conj(rhs)) / |rhs|².

This is the panic-free counterpart of the Div operator (which panics on a zero divisor, matching the rest of the workspace) and is the entry point sibling routines such as complex tan/tanh use.

Examples

use oxinum_complex::CBig;

let a = CBig::from_f64(1.0, 1.0).expect("finite parts");
let q = a.checked_div(&a).expect("non-zero divisor");
assert_eq!(q.re().to_string(), "1");
assert_eq!(q.im().to_string(), "0");

assert!(a.checked_div(&CBig::zero()).is_err());

impl CBig

pub fn abs(&self, precision: usize) -> OxiNumResult<DBig>

The magnitude |z| = sqrt(a² + b²) as a real DBig at precision significant digits.

Returns an exact decimal zero for a zero input (avoiding a sqrt(0) round trip). The squared magnitude is taken from CBig::norm_sqr.

Errors

Propagates any error from oxinum_float::sqrt (none expected for the non-negative norm_sqr; an OxiNumError::Precision is returned if precision == 0).

pub fn arg(&self, precision: usize) -> OxiNumResult<DBig>

The argument arg(z) = atan2(b, a) as a real DBig at precision significant digits, the principal value in (−π, π].

Errors

Propagates any error from oxinum_float::atan2.

pub fn exp(&self, precision: usize) -> OxiNumResult<CBig>

The complex exponential exp(z) = eᵃ·(cos b + i·sin b) at precision significant digits.

Errors

Propagates errors from oxinum_float::exp, oxinum_float::cos, and oxinum_float::sin.

pub fn ln(&self, precision: usize) -> OxiNumResult<CBig>

The principal complex logarithm ln(z) = ½·ln(a² + b²) + i·atan2(b, a) at precision significant digits.

Using ½·ln(norm_sqr) for the real part avoids an extra sqrt.

Errors

• OxiNumError::Domain if z is zero (ln(0) is undefined).
• Propagates errors from oxinum_float::ln / oxinum_float::atan2.

pub fn sqrt(&self, precision: usize) -> OxiNumResult<CBig>

The principal square root sqrt(z) at precision significant digits.

Uses re = sqrt((|z| + a)/2), im = sign(b)·sqrt((|z| − a)/2), with the purely-real input handled by an exact axis split and the radicands clamped up to zero before the real sqrt to absorb rounding noise. The branch chosen has re ≥ 0 and matches the IEEE-754 / num-complex principal value (so sqrt(-1) = +i).

Errors

Propagates errors from oxinum_float::sqrt (none expected: radicands are clamped non-negative).

pub fn pow(&self, w: &CBig, precision: usize) -> OxiNumResult<CBig>

The complex power z^w = exp(w · ln z) at precision significant digits.

The zero base is handled by convention: 0^0 = 1 and 0^w = 0 for any other w (avoiding ln(0)).

Errors

Propagates errors from CBig::ln / CBig::exp.

pub fn from_polar( r: &DBig, theta: &DBig, precision: usize, ) -> OxiNumResult<CBig>

Construct re + im·i from polar form (r, θ): r·cos θ + i·r·sin θ.

Errors

Propagates errors from oxinum_float::cos / oxinum_float::sin.

pub fn to_polar(&self, precision: usize) -> OxiNumResult<(DBig, DBig)>

Return (|z|, arg z) as a (DBig, DBig) pair at precision digits.

Errors

Propagates errors from CBig::abs / CBig::arg.

pub fn powi(&self, n: i32, _precision: usize) -> OxiNumResult<CBig>

Integer power z^n via binary exponentiation (O(log |n|) multiplications).

n == 0 returns one(). n < 0 computes (z^|n|)⁻¹ via CBig::checked_div, returning OxiNumError::DivByZero when z is zero.

Errors

OxiNumError::DivByZero when n < 0 and self is zero.

pub fn powf(&self, exp: &DBig, precision: usize) -> OxiNumResult<CBig>

Real-exponent power z^x = r^x · (cos(x·θ) + i·sin(x·θ)) via polar form.

Avoids the full exp(w·ln z) round trip. For z == 0: 0^0 = 1, 0^x = 0 for any other x.

Errors

Propagates errors from CBig::abs, CBig::arg, oxinum_float::pow, oxinum_float::cos, and oxinum_float::sin.

impl CBig

pub fn sin(&self, precision: usize) -> OxiNumResult<CBig>

The complex sine sin z = sin a · cosh b + i · cos a · sinh b at precision digits.

Errors

Propagates errors from the real sin/cos/sinh/cosh routines.

pub fn cos(&self, precision: usize) -> OxiNumResult<CBig>

The complex cosine cos z = cos a · cosh b − i · sin a · sinh b at precision digits.

Errors

Propagates errors from the real sin/cos/sinh/cosh routines.

pub fn sinh(&self, precision: usize) -> OxiNumResult<CBig>

The complex hyperbolic sine sinh z = sinh a · cos b + i · cosh a · sin b at precision digits.

Errors

Propagates errors from the real sin/cos/sinh/cosh routines.

pub fn cosh(&self, precision: usize) -> OxiNumResult<CBig>

The complex hyperbolic cosine cosh z = cosh a · cos b + i · sinh a · sin b at precision digits.

Errors

Propagates errors from the real sin/cos/sinh/cosh routines.

pub fn tan(&self, precision: usize) -> OxiNumResult<CBig>

The complex tangent tan z = sin z / cos z at precision digits.

Errors

• OxiNumError::DivByZero at the poles where cos z = 0.
• Propagates errors from the real sin/cos/sinh/cosh routines.

pub fn tanh(&self, precision: usize) -> OxiNumResult<CBig>

The complex hyperbolic tangent tanh z = sinh z / cosh z at precision digits.

Errors

• OxiNumError::DivByZero at the poles where cosh z = 0.
• Propagates errors from the real sin/cos/sinh/cosh routines.

impl CBig

pub fn new(re: DBig, im: DBig) -> Self

Construct a complex number from its real and imaginary parts.

Alias of CBig::from_parts.

pub fn from_parts(re: DBig, im: DBig) -> Self

Construct a complex number from its real and imaginary parts.

pub fn from_real(re: DBig) -> Self

Construct a purely real complex number (im = 0).

pub fn from_imag(im: DBig) -> Self

Construct a purely imaginary complex number (re = 0).

pub fn zero() -> Self

The additive identity 0 + 0·i.

pub fn one() -> Self

The multiplicative identity 1 + 0·i.

pub fn i() -> Self

The imaginary unit 0 + 1·i.

pub fn from_f64(re: f64, im: f64) -> OxiNumResult<Self>

Construct a complex number from a pair of f64 values.

Each component is converted to DBig by formatting it with 17 significant digits (enough to round-trip any finite f64) and parsing the resulting string.

Errors

Returns OxiNumError::Parse if either input is NaN or infinite (DBig models neither) or if the formatted decimal string fails to parse.

Examples

use oxinum_complex::CBig;
let z = CBig::from_f64(1.5, -2.25).expect("finite parts");
assert_eq!(z.re().to_string(), "1.5");
assert_eq!(z.im().to_string(), "-2.25");

pub fn re(&self) -> &DBig

A shared reference to the real part.

pub fn im(&self) -> &DBig

A shared reference to the imaginary part.

pub fn real(&self) -> DBig

A clone of the real part.

pub fn imag(&self) -> DBig

A clone of the imaginary part.

pub fn into_parts(self) -> (DBig, DBig)

Decompose into the owned (re, im) pair.

pub fn conj(&self) -> Self

The complex conjugate re − im·i.

Examples

use oxinum_complex::CBig;
let z = CBig::from_f64(2.0, 3.0).expect("finite parts");
let c = z.conj();
assert_eq!(c.re().to_string(), "2");
assert_eq!(c.im().to_string(), "-3");

pub fn norm_sqr(&self) -> DBig

The squared magnitude re² + im² (always real, non-negative).

Examples

use oxinum_complex::CBig;
let z = CBig::from_f64(3.0, 4.0).expect("finite parts");
assert_eq!(z.norm_sqr().to_string(), "25");

pub fn is_zero(&self) -> bool

Returns true if both components are zero.

pub fn is_real(&self) -> bool

Returns true if the imaginary part is zero (the value is real).

pub fn is_imaginary(&self) -> bool

Returns true if the real part is zero (the value is purely imaginary).

Trait Implementations

impl Add for CBig

type Output = CBig

The resulting type after applying the + operator.

fn add(self, rhs: CBig) -> CBig

Performs the + operation.

impl Add<&CBig> for &CBig

type Output = CBig

The resulting type after applying the + operator.

fn add(self, rhs: &CBig) -> CBig

Performs the + operation.

impl Add<&CBig> for CBig

type Output = CBig

The resulting type after applying the + operator.

fn add(self, rhs: &CBig) -> CBig

Performs the + operation.

impl Add<&FBig<HalfAway, 10>> for CBig

type Output = CBig

The resulting type after applying the + operator.

fn add(self, rhs: &DBig) -> CBig

Performs the + operation.

impl Add<&FBig<HalfAway, 10>> for &CBig

type Output = CBig

The resulting type after applying the + operator.

fn add(self, rhs: &DBig) -> CBig

Performs the + operation.

impl Add<CBig> for &CBig

type Output = CBig

The resulting type after applying the + operator.

fn add(self, rhs: CBig) -> CBig

Performs the + operation.

impl Add<FBig<HalfAway, 10>> for CBig

type Output = CBig

The resulting type after applying the + operator.

fn add(self, rhs: DBig) -> CBig

Performs the + operation.

impl Add<FBig<HalfAway, 10>> for &CBig

type Output = CBig

The resulting type after applying the + operator.

fn add(self, rhs: DBig) -> CBig

Performs the + operation.

impl Add<i64> for CBig

type Output = CBig

The resulting type after applying the + operator.

fn add(self, rhs: i64) -> CBig

Performs the + operation.

impl Add<i64> for &CBig

type Output = CBig

The resulting type after applying the + operator.

fn add(self, rhs: i64) -> CBig

Performs the + operation.

impl AddAssign for CBig

fn add_assign(&mut self, rhs: CBig)

Performs the += operation.

impl AddAssign<&CBig> for CBig

fn add_assign(&mut self, rhs: &CBig)

Performs the += operation.

impl AddAssign<&FBig<HalfAway, 10>> for CBig

fn add_assign(&mut self, rhs: &DBig)

Performs the += operation.

impl AddAssign<FBig<HalfAway, 10>> for CBig

fn add_assign(&mut self, rhs: DBig)

Performs the += operation.

impl AddAssign<i64> for CBig

fn add_assign(&mut self, rhs: i64)

Performs the += operation.

impl Clone for CBig

fn clone(&self) -> CBig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CBig

Developer-facing representation that names both components explicitly.

Examples

use oxinum_complex::CBig;
let z = CBig::from_f64(2.0, -3.0).expect("finite parts");
assert_eq!(format!("{z:?}"), "CBig { re: 2, im: -3 }");

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CBig

fn default() -> Self

Returns the “default value” for a type.

impl Display for CBig

Render as "<re> + <im>i" when the imaginary part is non-negative, and "<re> - <|im|>i" when it is negative.

Examples

use oxinum_complex::CBig;
let z = CBig::from_f64(2.0, 3.0).expect("finite parts");
assert_eq!(z.to_string(), "2 + 3i");
let w = CBig::from_f64(2.0, -3.0).expect("finite parts");
assert_eq!(w.to_string(), "2 - 3i");

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Div for CBig

type Output = CBig

The resulting type after applying the / operator.

fn div(self, rhs: CBig) -> CBig

Performs the / operation.

impl Div<&CBig> for &CBig

type Output = CBig

The resulting type after applying the / operator.

fn div(self, rhs: &CBig) -> CBig

Performs the / operation.

impl Div<&CBig> for CBig

type Output = CBig

The resulting type after applying the / operator.

fn div(self, rhs: &CBig) -> CBig

Performs the / operation.

impl Div<&FBig<HalfAway, 10>> for CBig

type Output = CBig

The resulting type after applying the / operator.

fn div(self, rhs: &DBig) -> CBig

Performs the / operation.

impl Div<&FBig<HalfAway, 10>> for &CBig

type Output = CBig

The resulting type after applying the / operator.

fn div(self, rhs: &DBig) -> CBig

Performs the / operation.

impl Div<CBig> for &CBig

type Output = CBig

The resulting type after applying the / operator.

fn div(self, rhs: CBig) -> CBig

Performs the / operation.

impl Div<FBig<HalfAway, 10>> for CBig

type Output = CBig

The resulting type after applying the / operator.

fn div(self, rhs: DBig) -> CBig

Performs the / operation.

impl Div<FBig<HalfAway, 10>> for &CBig

type Output = CBig

The resulting type after applying the / operator.

fn div(self, rhs: DBig) -> CBig

Performs the / operation.

impl Div<i64> for CBig

type Output = CBig

The resulting type after applying the / operator.

fn div(self, rhs: i64) -> CBig

Performs the / operation.

impl Div<i64> for &CBig

type Output = CBig

The resulting type after applying the / operator.

fn div(self, rhs: i64) -> CBig

Performs the / operation.

impl DivAssign for CBig

fn div_assign(&mut self, rhs: CBig)

Performs the /= operation.

impl DivAssign<&CBig> for CBig

fn div_assign(&mut self, rhs: &CBig)

Performs the /= operation.

impl DivAssign<&FBig<HalfAway, 10>> for CBig

fn div_assign(&mut self, rhs: &DBig)

Performs the /= operation.

impl DivAssign<FBig<HalfAway, 10>> for CBig

fn div_assign(&mut self, rhs: DBig)

Performs the /= operation.

impl DivAssign<i64> for CBig

fn div_assign(&mut self, rhs: i64)

Performs the /= operation.

impl From<&FBig<HalfAway, 10>> for CBig

Embed a borrowed real DBig on the real axis (im = 0).

fn from(re: &DBig) -> Self

Converts to this type from the input type.

impl From<(FBig<HalfAway, 10>, FBig<HalfAway, 10>)> for CBig

Build a complex number from an explicit (re, im) pair of DBig values.

fn from((re, im): (DBig, DBig)) -> Self

Converts to this type from the input type.

impl From<(i64, i64)> for CBig

Build a complex number from an integer (re, im) pair (convenience).

Both parts are represented exactly (at unlimited DBig precision), so the result keeps full precision through later arithmetic — e.g. CBig::from((3, 4)).norm_sqr() is the exact 25. See the module-level “Integer conversions are exact” note for the rationale.

fn from((re, im): (i64, i64)) -> Self

Converts to this type from the input type.

impl From<FBig<HalfAway, 10>> for CBig

Embed a real DBig on the real axis (im = 0).

fn from(re: DBig) -> Self

Converts to this type from the input type.

impl From<i64> for CBig

Embed an integer on the real axis (im = 0).

The real part is represented exactly (at unlimited DBig precision), so the value keeps full precision through later arithmetic. See the module-level “Integer conversions are exact” note for the rationale.

fn from(re: i64) -> Self

Converts to this type from the input type.

impl Mul for CBig

type Output = CBig

The resulting type after applying the * operator.

fn mul(self, rhs: CBig) -> CBig

Performs the * operation.

impl Mul<&CBig> for &CBig

type Output = CBig

The resulting type after applying the * operator.

fn mul(self, rhs: &CBig) -> CBig

Performs the * operation.

impl Mul<&CBig> for CBig

type Output = CBig

The resulting type after applying the * operator.

fn mul(self, rhs: &CBig) -> CBig

Performs the * operation.

impl Mul<&FBig<HalfAway, 10>> for CBig

type Output = CBig

The resulting type after applying the * operator.

fn mul(self, rhs: &DBig) -> CBig

Performs the * operation.

impl Mul<&FBig<HalfAway, 10>> for &CBig

type Output = CBig

The resulting type after applying the * operator.

fn mul(self, rhs: &DBig) -> CBig

Performs the * operation.

impl Mul<CBig> for &CBig

type Output = CBig

The resulting type after applying the * operator.

fn mul(self, rhs: CBig) -> CBig

Performs the * operation.

impl Mul<FBig<HalfAway, 10>> for CBig

type Output = CBig

The resulting type after applying the * operator.

fn mul(self, rhs: DBig) -> CBig

Performs the * operation.

impl Mul<FBig<HalfAway, 10>> for &CBig

type Output = CBig

The resulting type after applying the * operator.

fn mul(self, rhs: DBig) -> CBig

Performs the * operation.

impl Mul<i64> for CBig

type Output = CBig

The resulting type after applying the * operator.

fn mul(self, rhs: i64) -> CBig

Performs the * operation.

impl Mul<i64> for &CBig

type Output = CBig

The resulting type after applying the * operator.

fn mul(self, rhs: i64) -> CBig

Performs the * operation.

impl MulAssign for CBig

fn mul_assign(&mut self, rhs: CBig)

Performs the *= operation.

impl MulAssign<&CBig> for CBig

fn mul_assign(&mut self, rhs: &CBig)

Performs the *= operation.

impl MulAssign<&FBig<HalfAway, 10>> for CBig

fn mul_assign(&mut self, rhs: &DBig)

Performs the *= operation.

impl MulAssign<FBig<HalfAway, 10>> for CBig

fn mul_assign(&mut self, rhs: DBig)

Performs the *= operation.

impl MulAssign<i64> for CBig

fn mul_assign(&mut self, rhs: i64)

Performs the *= operation.

impl Neg for CBig

type Output = CBig

The resulting type after applying the - operator.

fn neg(self) -> CBig

Performs the unary - operation.

impl Neg for &CBig

type Output = CBig

The resulting type after applying the - operator.

fn neg(self) -> CBig

Performs the unary - operation.

impl PartialEq for CBig

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Sub for CBig

type Output = CBig

The resulting type after applying the - operator.

fn sub(self, rhs: CBig) -> CBig

Performs the - operation.

impl Sub<&CBig> for DBig

type Output = CBig

The resulting type after applying the - operator.

fn sub(self, rhs: &CBig) -> CBig

Performs the - operation.

impl Sub<&CBig> for &DBig

type Output = CBig

The resulting type after applying the - operator.

fn sub(self, rhs: &CBig) -> CBig

Performs the - operation.

impl Sub<&CBig> for i64

type Output = CBig

The resulting type after applying the - operator.

fn sub(self, rhs: &CBig) -> CBig

Performs the - operation.

impl Sub<&CBig> for &CBig

type Output = CBig

The resulting type after applying the - operator.

fn sub(self, rhs: &CBig) -> CBig

Performs the - operation.

impl Sub<&CBig> for CBig

type Output = CBig

The resulting type after applying the - operator.

fn sub(self, rhs: &CBig) -> CBig

Performs the - operation.

impl Sub<&FBig<HalfAway, 10>> for CBig

type Output = CBig

The resulting type after applying the - operator.

fn sub(self, rhs: &DBig) -> CBig

Performs the - operation.

impl Sub<&FBig<HalfAway, 10>> for &CBig

type Output = CBig

The resulting type after applying the - operator.

fn sub(self, rhs: &DBig) -> CBig

Performs the - operation.

impl Sub<CBig> for DBig

type Output = CBig

The resulting type after applying the - operator.

fn sub(self, rhs: CBig) -> CBig

Performs the - operation.

impl Sub<CBig> for &DBig

type Output = CBig

The resulting type after applying the - operator.

fn sub(self, rhs: CBig) -> CBig

Performs the - operation.

impl Sub<CBig> for i64

type Output = CBig

The resulting type after applying the - operator.

fn sub(self, rhs: CBig) -> CBig

Performs the - operation.

impl Sub<CBig> for &CBig

type Output = CBig

The resulting type after applying the - operator.

fn sub(self, rhs: CBig) -> CBig

Performs the - operation.

impl Sub<FBig<HalfAway, 10>> for CBig

type Output = CBig

The resulting type after applying the - operator.

fn sub(self, rhs: DBig) -> CBig

Performs the - operation.

impl Sub<FBig<HalfAway, 10>> for &CBig

type Output = CBig

The resulting type after applying the - operator.

fn sub(self, rhs: DBig) -> CBig

Performs the - operation.

impl Sub<i64> for CBig

type Output = CBig

The resulting type after applying the - operator.

fn sub(self, rhs: i64) -> CBig

Performs the - operation.

impl Sub<i64> for &CBig

type Output = CBig

The resulting type after applying the - operator.

fn sub(self, rhs: i64) -> CBig

Performs the - operation.

impl SubAssign for CBig

fn sub_assign(&mut self, rhs: CBig)

Performs the -= operation.

impl SubAssign<&CBig> for CBig

fn sub_assign(&mut self, rhs: &CBig)

Performs the -= operation.

impl SubAssign<&FBig<HalfAway, 10>> for CBig

fn sub_assign(&mut self, rhs: &DBig)

Performs the -= operation.

impl SubAssign<FBig<HalfAway, 10>> for CBig

fn sub_assign(&mut self, rhs: DBig)

Performs the -= operation.

impl SubAssign<i64> for CBig

fn sub_assign(&mut self, rhs: i64)

Performs the -= operation.

impl TryFrom<&CBig> for (f64, f64)

Try to project both components to f64, returning an error if either component is non-finite (infinite or NaN) after the conversion.

Errors

Returns OxiNumError::Overflow when either the real or imaginary part exceeds f64::MAX in magnitude (i.e. the result would be ±∞ or NaN).

type Error = OxiNumError

The type returned in the event of a conversion error.

fn try_from(z: &CBig) -> OxiNumResult<(f64, f64)>

Performs the conversion.