Report a bug
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

# std.complex

This module contains the Complex type, which is used to represent complex numbers, along with related mathematical operations and functions.
Complex will eventually replace the built-in types cfloat, cdouble, creal, ifloat, idouble, and ireal.
Authors:
pure nothrow @nogc @safe auto `complex`(R)(const R `re`)
if (is(R : double));

pure nothrow @nogc @safe auto `complex`(R, I)(const R `re`, const I `im`)
if (is(R : double) && is(I : double));
Helper function that returns a complex number with the specified real and imaginary parts.
Parameters:
 R (template parameter) type of real part of complex number I (template parameter) type of imaginary part of complex number R `re` real part of complex number to be constructed I `im` (optional) imaginary part of complex number, 0 if omitted.
Returns:
Complex instance with real and imaginary parts set to the values provided as input. If neither `re` nor `im` are floating-point numbers, the return type will be Complex!double. Otherwise, the return type is deduced using std.traits.CommonType!(R, I).
Examples:
```auto a = complex(1.0);
static assert(is(typeof(a) == Complex!double));
writeln(a.re); // 1.0
writeln(a.im); // 0.0

auto b = complex(2.0L);
static assert(is(typeof(b) == Complex!real));
writeln(b.re); // 2.0L
writeln(b.im); // 0.0L

auto c = complex(1.0, 2.0);
static assert(is(typeof(c) == Complex!double));
writeln(c.re); // 1.0
writeln(c.im); // 2.0

auto d = complex(3.0, 4.0L);
static assert(is(typeof(d) == Complex!real));
writeln(d.re); // 3.0
writeln(d.im); // 4.0L

auto e = complex(1);
static assert(is(typeof(e) == Complex!double));
writeln(e.re); // 1
writeln(e.im); // 0

auto f = complex(1L, 2);
static assert(is(typeof(f) == Complex!double));
writeln(f.re); // 1L
writeln(f.im); // 2

auto g = complex(3, 4.0L);
static assert(is(typeof(g) == Complex!real));
writeln(g.re); // 3
writeln(g.im); // 4.0L
```
struct `Complex`(T) if (isFloatingPoint!T);
A complex number parametrised by a type T, which must be either float, double or real.
T `re`;
The real part of the number.
T `im`;
The imaginary part of the number.
const @safe string `toString`();

const void `toString`(Writer, Char)(scope Writer `w`, ref scope const FormatSpec!Char `formatSpec`)
if (isOutputRange!(Writer, const(Char)[]));
Converts the complex number to a string representation.
The second form of this function is usually not called directly; instead, it is used via std.string.format, as shown in the examples below. Supported format characters are 'e', 'f', 'g', 'a', and 's'.
Examples:
```auto c = complex(1.2, 3.4);

// Vanilla toString formatting:
writeln(c.toString()); // "1.2+3.4i"

// Formatting with std.string.format specs: the precision and width
// specifiers apply to both the real and imaginary parts of the
// complex number.
import std.format : format;
writeln(format("%.2f", c)); // "1.20+3.40i"
writeln(format("%4.1f", c)); // " 1.2+ 3.4i"
```
this(R : T)(Complex!R `z`);

this(Rx : T, Ry : T)(const Rx `x`, const Ry `y`);

this(R : T)(const R `r`);
Construct a complex number with the specified real and imaginary parts. In the case where a single argument is passed that is not complex, the imaginary part of the result will be zero.
pure nothrow @nogc @safe T `abs`(T)(Complex!T `z`);
Parameters:
 Complex!T `z` A complex number.
Returns:
The absolute value (or modulus) of `z`.
Examples:
```static import std.math;
writeln(abs(complex(1.0))); // 1.0
writeln(abs(complex(0.0, 1.0))); // 1.0
writeln(abs(complex(1.0L, -2.0L))); // std.math.sqrt(5.0L)
```
pure nothrow @nogc @safe T `sqAbs`(T)(Complex!T `z`);

pure nothrow @nogc @safe T `sqAbs`(T)(const T `x`)
if (isFloatingPoint!T);
Parameters:
 Complex!T `z` A complex number. T `x` A real number.
Returns:
The squared modulus of `z`. For genericity, if called on a real number, returns its square.
Examples:
```import std.math;
writeln(sqAbs(complex(0.0))); // 0.0
writeln(sqAbs(complex(1.0))); // 1.0
writeln(sqAbs(complex(0.0, 1.0))); // 1.0
assert(approxEqual(sqAbs(complex(1.0L, -2.0L)), 5.0L));
assert(approxEqual(sqAbs(complex(-3.0L, 1.0L)), 10.0L));
assert(approxEqual(sqAbs(complex(1.0f,-1.0f)), 2.0f));
```
pure nothrow @nogc @safe T `arg`(T)(Complex!T `z`);
Parameters:
 Complex!T `z` A complex number.
Returns:
The argument (or phase) of `z`.
Examples:
```import std.math;
writeln(arg(complex(1.0))); // 0.0
writeln(arg(complex(0.0L, 1.0L))); // PI_2
writeln(arg(complex(1.0L, 1.0L))); // PI_4
```
pure nothrow @nogc @safe Complex!T `conj`(T)(Complex!T `z`);
Parameters:
 Complex!T `z` A complex number.
Returns:
The complex conjugate of `z`.
Examples:
```writeln(conj(complex(1.0))); // complex(1.0)
writeln(conj(complex(1.0, 2.0))); // complex(1.0, -2.0)
```
pure nothrow @nogc @safe Complex!(CommonType!(T, U)) `fromPolar`(T, U)(const T `modulus`, const U `argument`);
Constructs a complex number given its absolute value and argument.
Parameters:
 T `modulus` The modulus U `argument` The argument
Returns:
The complex number with the given modulus and argument.
Examples:
```import std.math;
auto z = fromPolar(std.math.sqrt(2.0), PI_4);
assert(approxEqual(z.re, 1.0L, real.epsilon));
assert(approxEqual(z.im, 1.0L, real.epsilon));
```
pure nothrow @nogc @safe Complex!T `sin`(T)(Complex!T `z`);

pure nothrow @nogc @safe Complex!T `cos`(T)(Complex!T `z`);
Trigonometric functions on complex numbers.
Parameters:
 Complex!T `z` A complex number.
Returns:
The sine and cosine of `z`, respectively.
Examples:
```static import std.math;
writeln(sin(complex(0.0))); // 0.0
writeln(sin(complex(2.0L, 0))); // std.math.sin(2.0L)
```
Examples:
```import std.complex;
writeln(cos(complex(0.0))); // 1.0
```
pure nothrow @nogc @trusted Complex!real `expi`(real `y`);
Parameters:
 real `y` A real number.
Returns:
The value of cos(y) + i sin(y).

Note `expi` is included here for convenience and for easy migration of code.

Examples:
```import std.math : cos, sin;
writeln(expi(0.0L)); // 1.0L
writeln(expi(1.3e5L)); // complex(cos(1.3e5L), sin(1.3e5L))
```
pure nothrow @nogc @safe Complex!real `coshisinh`(real `y`);
Parameters:
 real `y` A real number.
Returns:
The value of cosh(y) + i sinh(y)

Note `coshisinh` is included here for convenience and for easy migration of code.

Examples:
```import std.math : cosh, sinh;
writeln(coshisinh(3.0L)); // complex(cosh(3.0L), sinh(3.0L))
```
pure nothrow @nogc @safe Complex!T `sqrt`(T)(Complex!T `z`);
Parameters:
 Complex!T `z` A complex number.
Returns:
The square root of `z`.
Examples:
```static import std.math;
writeln(sqrt(complex(0.0))); // 0.0
writeln(sqrt(complex(1.0L, 0))); // std.math.sqrt(1.0L)
writeln(sqrt(complex(-1.0L, 0))); // complex(0, 1.0L)
writeln(sqrt(complex(-8.0, -6.0))); // complex(1.0, -3.0)
```