Home

easy-complex wiki

easy-complex is a Rust crate with no dependencies that aims to give the developer the ability to operate with complex numbers easily in a comprehensive way that is explicit and simple, with as little verbosity as possible.

This wiki gives an advanced explanation of the usage and capabilities as well as documentation for the methods and traits it implements. I will try to keep it as up to date as possible.

1. How to install

The installation is automatically done with cargo by adding to the project's Cargo.toml:

[dependencies]
...
easy_complex = "0.3.0"
...

If you are not using cargo, here's the link to the crate: https://crates.io/crates/easy_complex

2. Including it in your files and using it

To include the crate use

extern crate easy_complex;

for cargo to include it automatically.

The complex numbers in the crate are contained in two structs: EComplex and Complex, the exponential and coordinate representations of complex numbers respectively.

To include them do

use easy_complex::{EComplex, Complex};

This allows you to use them and operate with them.

The crate also allows you to convert explicitly the numeric types (integer, unsigned integer and float) into complex numbers.

To include the explicit cast of the standard numeric types do

use easy_complex::ContainedInComplex;

3. Usage

Okay now to the juicy part. With everything already imported from the crate, we can start messing around.

The complex numbers

There are two representations of complex numbers

• Exponential complex It is based on the exponential form of the complex numbers. It is a struct with two values: module and arg. Both fields are f64.
• Numeric complex It is based on the coordinate representation of the complex numbers. It is a struct with two values: real and imag. Both fields are f64.

The usage of f64 is due to the huge divergence between values that may result from inaccuracies, so to reduce this, f64 is used.

Creating complex numbers

Apart from the explicit creation of struct by giving each field a value, complex numbers include two static methods to be created: new() and new_from()

• The new() method takes no arguments and creates a complex number with a value of 0.0.

• The new_from() method takes a complex number of the other type (exponential if we want a coordinate one) and transforms it into a complex of the desire type.

• Since v0.3.3 the casting functionality is expanded. The From trait is implemented for both Complex and EComplex and for the num_traits crate Complex64.

Example

let test_complex = EComplex {module: 1.0, arg: 1.0}
let exp_complex = EComplex::new();
let num_complex = Complex::new();
//These two are equal to 0
let num_complex_2 = Complex::new_from(exp_complex);
//Would have whatever value has exp_complex

Casting standard numbers to complex

Casting numbers to integers transforms them into a complex with no imaginary part. This can be done with the complex() method included to the implemented types. This outputs an EComplex by default (had to choose one ¯\ _(ツ)_/¯). An implicit conversion between the two complex types is on its way.

Example

let complex_from_cast = 1.complex();
let complex_from_cast = 1.0f64.complex();
let my_int = 1u32;
let complex_from_cast = my_int.complex();

let num_complex_from_cast: Complex = 1.complex().into();

Operating with complex numbers

The main focus of this crate is to make operations between complex numbers easy and automatic, without need to cast them just to operate and with the ability to use them in the format you prefer. This is done all in the implementation of the operators. The only thing to take into account is that the output type of the operation will always be the same as the leftmost complex number. If it is a one operand operation the output will be of the same type of the caller.

Example

//These two represent the same number (1)
let complex_1 = EComplex {module: 1.0, arg: 0.0};
let complex_2 = Complex {real: 1.0, imag: 0.0};
//Leftmost operator is EComplex so output will be an EComplex
println!("{}", complex_1 + complex_2);
//Leftmost operator is again EComplex
println!("{}", 1.complex() + complex_2);

!!!Warning: when operating with zero, the values in the argument for EComplex type can diverge and not be accurate. Some methods default this value to either zero or PI/2 (1.5707...).

And that is the general use. For all the methods and implementations visit the other wiki sections.