logo

Struct rug::complex::SmallComplex

source · [−]
pub struct SmallComplex { /* private fields */ }
Expand description

A small complex number that does not require any memory allocation.

This can be useful when you have real and imaginary numbers that are primitive integers or floats and you need a reference to a Complex.

The SmallComplex will have a precision according to the types of the primitives used to set its real and imaginary parts. Note that if different types are used to set the parts, the parts can have different precisions.

  • i8, u8: the part will have eight bits of precision.
  • i16, u16: the part will have 16 bits of precision.
  • i32, u32: the part will have 32 bits of precision.
  • i64, u64: the part will have 64 bits of precision.
  • i128, u128: the part will have 128 bits of precision.
  • isize, usize: the part will have 32 or 64 bits of precision, depending on the platform.
  • f32: the part will have 24 bits of precision.
  • f64: the part will have 53 bits of precision.
  • Special: the part will have the minimum possible precision.

The SmallComplex type can be coerced to a Complex, as it implements Deref<Target = Complex>.

Examples

use rug::{complex::SmallComplex, Complex};
// `a` requires a heap allocation
let mut a = Complex::with_val(53, (1, 2));
// `b` can reside on the stack
let b = SmallComplex::from((-10f64, -20.5f64));
a += &*b;
assert_eq!(*a.real(), -9);
assert_eq!(*a.imag(), -18.5);

Implementations

Creates a SmallComplex with value 0 and the minimum possible precision.

Examples
use rug::complex::SmallComplex;
let c = SmallComplex::new();
// Borrow c as if it were Complex.
assert_eq!(*c, 0);

Returns a mutable reference to a Complex number for simple operations that do not need to change the precision of the real or imaginary part.

Safety

It is undefined behavior to modify the precision of the referenced Complex number or to swap it with another number.

Examples
use rug::complex::SmallComplex;
let mut c = SmallComplex::from((1.0f32, 3.0f32));
// rotation does not change the precision
unsafe {
    c.as_nonreallocating_complex().mul_i_mut(false);
}
assert_eq!(*c, (-3.0, 1.0));

Methods from Deref<Target = Complex>

Returns the precision of the real and imaginary parts.

Examples
use rug::Complex;
let r = Complex::new((24, 53));
assert_eq!(r.prec(), (24, 53));

Returns a pointer to the inner MPC complex number.

The returned pointer will be valid for as long as self is valid.

Examples
use gmp_mpfr_sys::{
    mpc,
    mpfr::{self, rnd_t},
};
use rug::Complex;
let c = Complex::with_val(53, (-14.5, 3.25));
let m_ptr = c.as_raw();
unsafe {
    let re_ptr = mpc::realref_const(m_ptr);
    let re = mpfr::get_d(re_ptr, rnd_t::RNDN);
    assert_eq!(re, -14.5);
    let im_ptr = mpc::imagref_const(m_ptr);
    let im = mpfr::get_d(im_ptr, rnd_t::RNDN);
    assert_eq!(im, 3.25);
}
// c is still valid
assert_eq!(c, (-14.5, 3.25));

Returns a string representation of the value for the specified radix rounding to the nearest.

The exponent is encoded in decimal. If the number of digits is not specified, the output string will have enough precision such that reading it again will give the exact same number.

Panics

Panics if radix is less than 2 or greater than 36.

Examples
use rug::Complex;
let c1 = Complex::with_val(53, 0);
assert_eq!(c1.to_string_radix(10, None), "(0 0)");
let c2 = Complex::with_val(12, (15, 5));
assert_eq!(c2.to_string_radix(16, None), "(f.000 5.000)");
let c3 = Complex::with_val(53, (10, -4));
assert_eq!(c3.to_string_radix(10, Some(3)), "(10.0 -4.00)");
assert_eq!(c3.to_string_radix(5, Some(3)), "(20.0 -4.00)");
// 2 raised to the power of 80 in hex is 1 followed by 20 zeros
let c4 = Complex::with_val(53, (80f64.exp2(), 0.25));
assert_eq!(c4.to_string_radix(10, Some(3)), "(1.21e24 2.50e-1)");
assert_eq!(c4.to_string_radix(16, Some(3)), "(1.00@20 4.00@-1)");

Returns a string representation of the value for the specified radix applying the specified rounding method.

The exponent is encoded in decimal. If the number of digits is not specified, the output string will have enough precision such that reading it again will give the exact same number.

Panics

Panics if radix is less than 2 or greater than 36.

Examples
use rug::{float::Round, Complex};
let c = Complex::with_val(10, 10.4);
let down = (Round::Down, Round::Down);
let nearest = (Round::Nearest, Round::Nearest);
let up = (Round::Up, Round::Up);
let nd = c.to_string_radix_round(10, None, down);
assert_eq!(nd, "(10.406 0)");
let nu = c.to_string_radix_round(10, None, up);
assert_eq!(nu, "(10.407 0)");
let sd = c.to_string_radix_round(10, Some(2), down);
assert_eq!(sd, "(10 0)");
let sn = c.to_string_radix_round(10, Some(2), nearest);
assert_eq!(sn, "(10 0)");
let su = c.to_string_radix_round(10, Some(2), up);
assert_eq!(su, "(11 0)");

Borrows the real part as a Float.

Examples
use rug::Complex;
let c = Complex::with_val(53, (12.5, -20.75));
assert_eq!(*c.real(), 12.5)

Borrows the imaginary part as a Float.

Examples
use rug::Complex;
let c = Complex::with_val(53, (12.5, -20.75));
assert_eq!(*c.imag(), -20.75)

Borrows a negated copy of the Complex number.

The returned object implements Deref<Target = Complex>.

This method performs a shallow copy and negates it, and negation does not change the allocated data.

Examples
use rug::Complex;
let c = Complex::with_val(53, (4.2, -2.3));
let neg_c = c.as_neg();
assert_eq!(*neg_c, (-4.2, 2.3));
// methods taking &self can be used on the returned object
let reneg_c = neg_c.as_neg();
assert_eq!(*reneg_c, (4.2, -2.3));
assert_eq!(*reneg_c, c);

Borrows a conjugate copy of the Complex number.

The returned object implements Deref<Target = Complex>.

This method performs a shallow copy and negates its imaginary part, and negation does not change the allocated data.

Examples
use rug::Complex;
let c = Complex::with_val(53, (4.2, -2.3));
let conj_c = c.as_conj();
assert_eq!(*conj_c, (4.2, 2.3));
// methods taking &self can be used on the returned object
let reconj_c = conj_c.as_conj();
assert_eq!(*reconj_c, (4.2, -2.3));
assert_eq!(*reconj_c, c);

Borrows a rotated copy of the Complex number.

The returned object implements Deref<Target = Complex>.

This method operates by performing some shallow copying; unlike the mul_i method and friends, this method swaps the precision of the real and imaginary parts if they have unequal precisions.

Examples
use rug::Complex;
let c = Complex::with_val(53, (4.2, -2.3));
let mul_i_c = c.as_mul_i(false);
assert_eq!(*mul_i_c, (2.3, 4.2));
// methods taking &self can be used on the returned object
let mul_ii_c = mul_i_c.as_mul_i(false);
assert_eq!(*mul_ii_c, (-4.2, 2.3));
let mul_1_c = mul_i_c.as_mul_i(true);
assert_eq!(*mul_1_c, (4.2, -2.3));
assert_eq!(*mul_1_c, c);

Borrows the Complex number as an ordered complex number of type OrdComplex.

The same result can be obtained using the implementation of AsRef<OrdComplex> which is provided for Complex.

Examples
use core::cmp::Ordering;
use rug::{float::Special, Complex};

let nan_c = Complex::with_val(53, (Special::Nan, Special::Nan));
let nan = nan_c.as_ord();
assert_eq!(nan.cmp(nan), Ordering::Equal);

let one_neg0_c = Complex::with_val(53, (1, Special::NegZero));
let one_neg0 = one_neg0_c.as_ord();
let one_pos0_c = Complex::with_val(53, (1, Special::Zero));
let one_pos0 = one_pos0_c.as_ord();
assert_eq!(one_neg0.cmp(one_pos0), Ordering::Less);

let zero_inf_s = (Special::Zero, Special::Infinity);
let zero_inf_c = Complex::with_val(53, zero_inf_s);
let zero_inf = zero_inf_c.as_ord();
assert_eq!(one_pos0.cmp(zero_inf), Ordering::Greater);

Returns the same result as self.eq(&0), but is faster.

Examples
use rug::{float::Special, Assign, Complex};
let mut c = Complex::with_val(53, (Special::NegZero, Special::Zero));
assert!(c.eq0());
c += 5.2;
assert!(!c.eq0());
c.mut_real().assign(Special::Nan);
assert!(!c.eq0());

Compares the absolute values of self and other.

Examples
use core::cmp::Ordering;
use rug::Complex;
let five = Complex::with_val(53, (5, 0));
let five_rotated = Complex::with_val(53, (3, -4));
let greater_than_five = Complex::with_val(53, (-4, -4));
let has_nan = Complex::with_val(53, (5, 0.0 / 0.0));
assert_eq!(five.cmp_abs(&five_rotated), Some(Ordering::Equal));
assert_eq!(five.cmp_abs(&greater_than_five), Some(Ordering::Less));
assert_eq!(five.cmp_abs(&has_nan), None);

Returns the total ordering between self and other.

For ordering, the real part has precedence over the imaginary part. Negative zero is ordered as less than positive zero. Negative NaN is ordered as less than negative infinity, while positive NaN is ordered as greater than positive infinity. Comparing two negative NaNs or two positive NaNs produces equality.

Examples
use rug::{float::Special, Complex};
let mut values = vec![
    Complex::with_val(53, (Special::Zero, Special::Zero)),
    Complex::with_val(53, (Special::Zero, Special::NegZero)),
    Complex::with_val(53, (Special::NegZero, Special::Infinity)),
];

values.sort_by(Complex::total_cmp);

// (-0, +∞)
assert!(values[0].real().is_zero() && values[0].real().is_sign_negative());
assert!(values[0].imag().is_infinite() && values[0].imag().is_sign_positive());
// (+0, -0)
assert!(values[1].real().is_zero() && values[1].real().is_sign_positive());
assert!(values[1].imag().is_zero() && values[1].imag().is_sign_negative());
// (+0, +0)
assert!(values[2].real().is_zero() && values[2].real().is_sign_positive());
assert!(values[2].imag().is_zero() && values[2].imag().is_sign_positive());

Multiplies and adds in one fused operation.

The following are implemented with the returned incomplete-computation value as Src:

a.mul_add_ref(&b, &c) produces the exact same result as &a * &b + &c.

Examples
use rug::Complex;
let a = Complex::with_val(53, (10, 0));
let b = Complex::with_val(53, (1, -1));
let c = Complex::with_val(53, (1000, 1000));
// (10 + 0i) × (1 - i) + (1000 + 1000i) = (1010 + 990i)
let ans = Complex::with_val(53, a.mul_add_ref(&b, &c));
assert_eq!(ans, (1010, 990));

Multiplies and subtracts in one fused operation.

The following are implemented with the returned incomplete-computation value as Src:

a.mul_sub_ref(&b, &c) produces the exact same result as &a * &b - &c.

Examples
use rug::Complex;
let a = Complex::with_val(53, (10, 0));
let b = Complex::with_val(53, (1, -1));
let c = Complex::with_val(53, (1000, 1000));
// (10 + 0i) × (1 - i) - (1000 + 1000i) = (-990 - 1010i)
let ans = Complex::with_val(53, a.mul_sub_ref(&b, &c));
assert_eq!(ans, (-990, -1010));

Computes the projection onto the Riemann sphere.

If no parts of the number are infinite, the result is unchanged. If any part is infinite, the real part of the result is set to +∞ and the imaginary part of the result is set to 0 with the same sign as the imaginary part of the input.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use core::f64;
use rug::Complex;
let c1 = Complex::with_val(53, (f64::INFINITY, 50));
let proj1 = Complex::with_val(53, c1.proj_ref());
assert_eq!(proj1, (f64::INFINITY, 0.0));
let c2 = Complex::with_val(53, (f64::NAN, f64::NEG_INFINITY));
let proj2 = Complex::with_val(53, c2.proj_ref());
assert_eq!(proj2, (f64::INFINITY, 0.0));
// imaginary was negative, so now it is minus zero
assert!(proj2.imag().is_sign_negative());

Computes the square.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use core::cmp::Ordering;
use rug::{float::Round, Complex};
let c = Complex::with_val(53, (1.25, 1.25));
// (1.25 + 1.25i) squared is (0 + 3.125i).
let r = c.square_ref();
// With 4 bits of precision, 3.125 is rounded down to 3.
let round = (Round::Down, Round::Down);
let (square, dir) = Complex::with_val_round(4, r, round);
assert_eq!(square, (0, 3));
assert_eq!(dir, (Ordering::Equal, Ordering::Less));

Computes the square root.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use core::cmp::Ordering;
use rug::{float::Round, Complex};
let c = Complex::with_val(53, (2, 2.25));
// Square root of (2 + 2.25i) is (1.5828 + 0.7108i).
let r = c.sqrt_ref();
// Nearest with 4 bits of precision: (1.625 + 0.6875i)
let nearest = (Round::Nearest, Round::Nearest);
let (sqrt, dir) = Complex::with_val_round(4, r, nearest);
assert_eq!(sqrt, (1.625, 0.6875));
assert_eq!(dir, (Ordering::Greater, Ordering::Less));

Computes the complex conjugate.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (1.5, 2.5));
let conj = Complex::with_val(53, c.conj_ref());
assert_eq!(conj, (1.5, -2.5));

Computes the absolute value.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{Complex, Float};
let c = Complex::with_val(53, (30, 40));
let f = Float::with_val(53, c.abs_ref());
assert_eq!(f, 50);

Computes the argument.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use core::f64;
use rug::{Assign, Complex, Float};
// f has precision 53, just like f64, so PI constants match.
let mut arg = Float::new(53);
let c_pos = Complex::with_val(53, 1);
arg.assign(c_pos.arg_ref());
assert!(arg.is_zero());
let c_neg = Complex::with_val(53, -1.3);
arg.assign(c_neg.arg_ref());
assert_eq!(arg, f64::consts::PI);
let c_pi_4 = Complex::with_val(53, (1.333, 1.333));
arg.assign(c_pi_4.arg_ref());
assert_eq!(arg, f64::consts::FRAC_PI_4);

Multiplies the complex number by ±i.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (13, 24));
let rotated = Complex::with_val(53, c.mul_i_ref(false));
assert_eq!(rotated, (-24, 13));

Computes the reciprocal.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (1, 1));
// 1/(1 + i) = (0.5 - 0.5i)
let recip = Complex::with_val(53, c.recip_ref());
assert_eq!(recip, (0.5, -0.5));

Computes the norm, that is the square of the absolute value.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{Complex, Float};
let c = Complex::with_val(53, (3, 4));
let f = Float::with_val(53, c.norm_ref());
assert_eq!(f, 25);

Computes the natural logarithm.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (1.5, -0.5));
let ln = Complex::with_val(53, c.ln_ref());
let expected = Complex::with_val(53, (0.4581, -0.3218));
assert!(*(ln - expected).abs().real() < 0.0001);

Computes the logarithm to base 10.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (1.5, -0.5));
let log10 = Complex::with_val(53, c.log10_ref());
let expected = Complex::with_val(53, (0.1990, -0.1397));
assert!(*(log10 - expected).abs().real() < 0.0001);

Computes the exponential.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (0.5, -0.75));
let exp = Complex::with_val(53, c.exp_ref());
let expected = Complex::with_val(53, (1.2064, -1.1238));
assert!(*(exp - expected).abs().real() < 0.0001);

Computes the sine.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (1, 1));
let sin = Complex::with_val(53, c.sin_ref());
let expected = Complex::with_val(53, (1.2985, 0.6350));
assert!(*(sin - expected).abs().real() < 0.0001);

Computes the cosine.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (1, 1));
let cos = Complex::with_val(53, c.cos_ref());
let expected = Complex::with_val(53, (0.8337, -0.9889));
assert!(*(cos - expected).abs().real() < 0.0001);

Computes the sine and cosine.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use core::cmp::Ordering;
use rug::{float::Round, ops::AssignRound, Assign, Complex};
let phase = Complex::with_val(53, (1, 1));

let (mut sin, mut cos) = (Complex::new(53), Complex::new(53));
let sin_cos = phase.sin_cos_ref();
(&mut sin, &mut cos).assign(sin_cos);
let expected_sin = Complex::with_val(53, (1.2985, 0.6350));
let expected_cos = Complex::with_val(53, (0.8337, -0.9889));
assert!(*(sin - expected_sin).abs().real() < 0.0001);
assert!(*(cos - expected_cos).abs().real() < 0.0001);

// using 4 significant bits: sin = (1.25 + 0.625i)
// using 4 significant bits: cos = (0.8125 - i)
let (mut sin_4, mut cos_4) = (Complex::new(4), Complex::new(4));
let sin_cos = phase.sin_cos_ref();
let (dir_sin, dir_cos) = (&mut sin_4, &mut cos_4)
    .assign_round(sin_cos, (Round::Nearest, Round::Nearest));
assert_eq!(sin_4, (1.25, 0.625));
assert_eq!(dir_sin, (Ordering::Less, Ordering::Less));
assert_eq!(cos_4, (0.8125, -1));
assert_eq!(dir_cos, (Ordering::Less, Ordering::Less));

Computes the tangent.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (1, 1));
let tan = Complex::with_val(53, c.tan_ref());
let expected = Complex::with_val(53, (0.2718, 1.0839));
assert!(*(tan - expected).abs().real() < 0.0001);

Computes the hyperbolic sine.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (1, 1));
let sinh = Complex::with_val(53, c.sinh_ref());
let expected = Complex::with_val(53, (0.6350, 1.2985));
assert!(*(sinh - expected).abs().real() < 0.0001);

Computes the hyperbolic cosine.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (1, 1));
let cosh = Complex::with_val(53, c.cosh_ref());
let expected = Complex::with_val(53, (0.8337, 0.9889));
assert!(*(cosh - expected).abs().real() < 0.0001);

Computes the hyperbolic tangent.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (1, 1));
let tanh = Complex::with_val(53, c.tanh_ref());
let expected = Complex::with_val(53, (1.0839, 0.2718));
assert!(*(tanh - expected).abs().real() < 0.0001);

Computes the inverse sine.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (1, 1));
let asin = Complex::with_val(53, c.asin_ref());
let expected = Complex::with_val(53, (0.6662, 1.0613));
assert!(*(asin - expected).abs().real() < 0.0001);

Computes the inverse cosine.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (1, 1));
let acos = Complex::with_val(53, c.acos_ref());
let expected = Complex::with_val(53, (0.9046, -1.0613));
assert!(*(acos - expected).abs().real() < 0.0001);

Computes the inverse tangent.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (1, 1));
let atan = Complex::with_val(53, c.atan_ref());
let expected = Complex::with_val(53, (1.0172, 0.4024));
assert!(*(atan - expected).abs().real() < 0.0001);

Computes the inverse hyperboic sine.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (1, 1));
let asinh = Complex::with_val(53, c.asinh_ref());
let expected = Complex::with_val(53, (1.0613, 0.6662));
assert!(*(asinh - expected).abs().real() < 0.0001);

Computes the inverse hyperbolic cosine.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (1, 1));
let acosh = Complex::with_val(53, c.acosh_ref());
let expected = Complex::with_val(53, (1.0613, 0.9046));
assert!(*(acosh - expected).abs().real() < 0.0001);

Computes the inverse hyperbolic tangent.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Complex;
let c = Complex::with_val(53, (1, 1));
let atanh = Complex::with_val(53, c.atanh_ref());
let expected = Complex::with_val(53, (0.4024, 1.0172));
assert!(*(atanh - expected).abs().real() < 0.0001);

Trait Implementations

Peforms the assignement.

Peforms the assignement.

Peforms the assignement.

Peforms the assignement.

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Returns the “default value” for a type. Read more

The resulting type after dereferencing.

Dereferences the value.

Converts to this type from the input type.

Converts to this type from the input type.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Casts the value.

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Casts the value.

Casts the value.

Casts the value.

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Casts the value.

OverflowingCasts the value.

Casts the value.

Casts the value.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Casts the value.

UnwrappedCasts the value.

Casts the value.

WrappingCasts the value.