28 Numerics library [numerics]

28.4 Complex numbers [complex.numbers]

28.4.1 General [complex.numbers.general]

1
#
The header <complex> defines a class template, and numerous functions for representing and manipulating complex numbers.
2
#
The effect of instantiating the template complex for any type that is not a cv-unqualified floating-point type ([basic.fundamental]) is unspecified.
Specializations of complex for cv-unqualified floating-point types are trivially-copyable literal types ([basic.types.general]).
3
#
If the result of a function is not mathematically defined or not in the range of representable values for its type, the behavior is undefined.
4
#
If z is an lvalue of type cv complex<T> then:
  • (4.1)
    the expression reinterpret_cast<cv T(&)[2]>(z) is well-formed,
  • (4.2)
    reinterpret_cast<cv T(&)[2]>(z)[0] designates the real part of z, and
  • (4.3)
    reinterpret_cast<cv T(&)[2]>(z)[1] designates the imaginary part of z.
Moreover, if a is an expression of type cv complex<T>* and the expression a[i] is well-defined for an integer expression i, then:
  • (4.4)
    reinterpret_cast<cv T*>(a)[2*i] designates the real part of a[i], and
  • (4.5)
    reinterpret_cast<cv T*>(a)[2*i + 1] designates the imaginary part of a[i].

28.4.2 Header <complex> synopsis [complex.syn]

🔗
namespace std { // [complex], class template complex template<class T> class complex; // [complex.ops], operators template<class T> constexpr complex<T> operator+(const complex<T>&, const complex<T>&); template<class T> constexpr complex<T> operator+(const complex<T>&, const T&); template<class T> constexpr complex<T> operator+(const T&, const complex<T>&); template<class T> constexpr complex<T> operator-(const complex<T>&, const complex<T>&); template<class T> constexpr complex<T> operator-(const complex<T>&, const T&); template<class T> constexpr complex<T> operator-(const T&, const complex<T>&); template<class T> constexpr complex<T> operator*(const complex<T>&, const complex<T>&); template<class T> constexpr complex<T> operator*(const complex<T>&, const T&); template<class T> constexpr complex<T> operator*(const T&, const complex<T>&); template<class T> constexpr complex<T> operator/(const complex<T>&, const complex<T>&); template<class T> constexpr complex<T> operator/(const complex<T>&, const T&); template<class T> constexpr complex<T> operator/(const T&, const complex<T>&); template<class T> constexpr complex<T> operator+(const complex<T>&); template<class T> constexpr complex<T> operator-(const complex<T>&); template<class T> constexpr bool operator==(const complex<T>&, const complex<T>&); template<class T> constexpr bool operator==(const complex<T>&, const T&); template<class T, class charT, class traits> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&, complex<T>&); template<class T, class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const complex<T>&); // [complex.value.ops], values template<class T> constexpr T real(const complex<T>&); template<class T> constexpr T imag(const complex<T>&); template<class T> T abs(const complex<T>&); template<class T> T arg(const complex<T>&); template<class T> constexpr T norm(const complex<T>&); template<class T> constexpr complex<T> conj(const complex<T>&); template<class T> complex<T> proj(const complex<T>&); template<class T> complex<T> polar(const T&, const T& = T()); // [complex.transcendentals], transcendentals template<class T> complex<T> acos(const complex<T>&); template<class T> complex<T> asin(const complex<T>&); template<class T> complex<T> atan(const complex<T>&); template<class T> complex<T> acosh(const complex<T>&); template<class T> complex<T> asinh(const complex<T>&); template<class T> complex<T> atanh(const complex<T>&); template<class T> complex<T> cos (const complex<T>&); template<class T> complex<T> cosh (const complex<T>&); template<class T> complex<T> exp (const complex<T>&); template<class T> complex<T> log (const complex<T>&); template<class T> complex<T> log10(const complex<T>&); template<class T> complex<T> pow (const complex<T>&, const T&); template<class T> complex<T> pow (const complex<T>&, const complex<T>&); template<class T> complex<T> pow (const T&, const complex<T>&); template<class T> complex<T> sin (const complex<T>&); template<class T> complex<T> sinh (const complex<T>&); template<class T> complex<T> sqrt (const complex<T>&); template<class T> complex<T> tan (const complex<T>&); template<class T> complex<T> tanh (const complex<T>&); // [complex.literals], complex literals inline namespace literals { inline namespace complex_literals { constexpr complex<long double> operator""il(long double); constexpr complex<long double> operator""il(unsigned long long); constexpr complex<double> operator""i(long double); constexpr complex<double> operator""i(unsigned long long); constexpr complex<float> operator""if(long double); constexpr complex<float> operator""if(unsigned long long); } } }

28.4.3 Class template complex [complex]

🔗
namespace std { template<class T> class complex { public: using value_type = T; constexpr complex(const T& re = T(), const T& im = T()); constexpr complex(const complex&) = default; template<class X> constexpr explicit(see below) complex(const complex<X>&); constexpr T real() const; constexpr void real(T); constexpr T imag() const; constexpr void imag(T); constexpr complex& operator= (const T&); constexpr complex& operator+=(const T&); constexpr complex& operator-=(const T&); constexpr complex& operator*=(const T&); constexpr complex& operator/=(const T&); constexpr complex& operator=(const complex&); template<class X> constexpr complex& operator= (const complex<X>&); template<class X> constexpr complex& operator+=(const complex<X>&); template<class X> constexpr complex& operator-=(const complex<X>&); template<class X> constexpr complex& operator*=(const complex<X>&); template<class X> constexpr complex& operator/=(const complex<X>&); }; }
1
#
The class complex describes an object that can store the Cartesian components, real() and imag(), of a complex number.

28.4.4 Member functions [complex.members]

🔗
constexpr complex(const T& re = T(), const T& im = T());
1
#
Postconditions: real() == re && imag() == im is true.
🔗
template<class X> constexpr explicit(see below) complex(const complex<X>& other);
2
#
Effects: Initializes the real part with other.real() and the imaginary part with other.imag().
3
#
Remarks: The expression inside explicit evaluates to false if and only if the floating-point conversion rank of T is greater than or equal to the floating-point conversion rank of X.
🔗
constexpr T real() const;
4
#
Returns: The value of the real component.
🔗
constexpr void real(T val);
5
#
Effects: Assigns val to the real component.
🔗
constexpr T imag() const;
6
#
Returns: The value of the imaginary component.
🔗
constexpr void imag(T val);
7
#
Effects: Assigns val to the imaginary component.

28.4.5 Member operators [complex.member.ops]

🔗
constexpr complex& operator+=(const T& rhs);
1
#
Effects: Adds the scalar value rhs to the real part of the complex value *this and stores the result in the real part of *this, leaving the imaginary part unchanged.
2
#
Returns: *this.
🔗
constexpr complex& operator-=(const T& rhs);
3
#
Effects: Subtracts the scalar value rhs from the real part of the complex value *this and stores the result in the real part of *this, leaving the imaginary part unchanged.
4
#
Returns: *this.
🔗
constexpr complex& operator*=(const T& rhs);
5
#
Effects: Multiplies the scalar value rhs by the complex value *this and stores the result in *this.
6
#
Returns: *this.
🔗
constexpr complex& operator/=(const T& rhs);
7
#
Effects: Divides the scalar value rhs into the complex value *this and stores the result in *this.
8
#
Returns: *this.
🔗
template<class X> constexpr complex& operator+=(const complex<X>& rhs);
9
#
Effects: Adds the complex value rhs to the complex value *this and stores the sum in *this.
10
#
Returns: *this.
🔗
template<class X> constexpr complex& operator-=(const complex<X>& rhs);
11
#
Effects: Subtracts the complex value rhs from the complex value *this and stores the difference in *this.
12
#
Returns: *this.
🔗
template<class X> constexpr complex& operator*=(const complex<X>& rhs);
13
#
Effects: Multiplies the complex value rhs by the complex value *this and stores the product in *this.
14
#
Returns: *this.
🔗
template<class X> constexpr complex& operator/=(const complex<X>& rhs);
15
#
Effects: Divides the complex value rhs into the complex value *this and stores the quotient in *this.
16
#
Returns: *this.

28.4.6 Non-member operations [complex.ops]

🔗
template<class T> constexpr complex<T> operator+(const complex<T>& lhs);
1
#
Returns: complex<T>(lhs).
🔗
template<class T> constexpr complex<T> operator+(const complex<T>& lhs, const complex<T>& rhs); template<class T> constexpr complex<T> operator+(const complex<T>& lhs, const T& rhs); template<class T> constexpr complex<T> operator+(const T& lhs, const complex<T>& rhs);
2
#
Returns: complex<T>(lhs) += rhs.
🔗
template<class T> constexpr complex<T> operator-(const complex<T>& lhs);
3
#
Returns: complex<T>(-lhs.real(),-lhs.imag()).
🔗
template<class T> constexpr complex<T> operator-(const complex<T>& lhs, const complex<T>& rhs); template<class T> constexpr complex<T> operator-(const complex<T>& lhs, const T& rhs); template<class T> constexpr complex<T> operator-(const T& lhs, const complex<T>& rhs);
4
#
Returns: complex<T>(lhs) -= rhs.
🔗
template<class T> constexpr complex<T> operator*(const complex<T>& lhs, const complex<T>& rhs); template<class T> constexpr complex<T> operator*(const complex<T>& lhs, const T& rhs); template<class T> constexpr complex<T> operator*(const T& lhs, const complex<T>& rhs);
5
#
Returns: complex<T>(lhs) *= rhs.
🔗
template<class T> constexpr complex<T> operator/(const complex<T>& lhs, const complex<T>& rhs); template<class T> constexpr complex<T> operator/(const complex<T>& lhs, const T& rhs); template<class T> constexpr complex<T> operator/(const T& lhs, const complex<T>& rhs);
6
#
Returns: complex<T>(lhs) /= rhs.
🔗
template<class T> constexpr bool operator==(const complex<T>& lhs, const complex<T>& rhs); template<class T> constexpr bool operator==(const complex<T>& lhs, const T& rhs);
7
#
Returns: lhs.real() == rhs.real() && lhs.imag() == rhs.imag().
8
#
Remarks: The imaginary part is assumed to be T(), or 0.0, for the T arguments.
🔗
template<class T, class charT, class traits> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, complex<T>& x);
9
#
Preconditions: The input values are convertible to T.
10
#
Effects: Extracts a complex number x of the form: u, (u), or (u,v), where u is the real part and v is the imaginary part ([istream.formatted]).
11
#
If bad input is encountered, calls is.setstate(ios_base​::​failbit) (which may throw ios_base​::​​failure ([iostate.flags])).
12
#
Returns: is.
13
#
Remarks: This extraction is performed as a series of simpler extractions.
Therefore, the skipping of whitespace is specified to be the same for each of the simpler extractions.
🔗
template<class T, class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& o, const complex<T>& x);
14
#
Effects: Inserts the complex number x onto the stream o as if it were implemented as follows: basic_ostringstream<charT, traits> s; s.flags(o.flags()); s.imbue(o.getloc()); s.precision(o.precision()); s << '(' << x.real() << ',' << x.imag() << ')'; return o << s.str();
15
#
[Note 1: 
In a locale in which comma is used as a decimal point character, the use of comma as a field separator can be ambiguous.
Inserting showpoint into the output stream forces all outputs to show an explicit decimal point character; as a result, all inserted sequences of complex numbers can be extracted unambiguously.
— end note]

28.4.7 Value operations [complex.value.ops]

🔗
template<class T> constexpr T real(const complex<T>& x);
1
#
Returns: x.real().
🔗
template<class T> constexpr T imag(const complex<T>& x);
2
#
Returns: x.imag().
🔗
template<class T> T abs(const complex<T>& x);
3
#
Returns: The magnitude of x.
🔗
template<class T> T arg(const complex<T>& x);
4
#
Returns: The phase angle of x, or atan2(imag(x), real(x)).
🔗
template<class T> constexpr T norm(const complex<T>& x);
5
#
Returns: The squared magnitude of x.
🔗
template<class T> constexpr complex<T> conj(const complex<T>& x);
6
#
Returns: The complex conjugate of x.
🔗
template<class T> complex<T> proj(const complex<T>& x);
7
#
Returns: The projection of x onto the Riemann sphere.
8
#
Remarks: Behaves the same as the C function cproj.
See also: ISO/IEC 9899:2018, 7.3.9.5
🔗
template<class T> complex<T> polar(const T& rho, const T& theta = T());
9
#
Preconditions: rho is non-negative and non-NaN.
theta is finite.
10
#
Returns: The complex value corresponding to a complex number whose magnitude is rho and whose phase angle is theta.

28.4.8 Transcendentals [complex.transcendentals]

🔗
template<class T> complex<T> acos(const complex<T>& x);
1
#
Returns: The complex arc cosine of x.
2
#
Remarks: Behaves the same as the C function cacos.
See also: ISO/IEC 9899:2018, 7.3.5.1
🔗
template<class T> complex<T> asin(const complex<T>& x);
3
#
Returns: The complex arc sine of x.
4
#
Remarks: Behaves the same as the C function casin.
See also: ISO/IEC 9899:2018, 7.3.5.2
🔗
template<class T> complex<T> atan(const complex<T>& x);
5
#
Returns: The complex arc tangent of x.
6
#
Remarks: Behaves the same as the C function catan.
See also: ISO/IEC 9899:2018, 7.3.5.3
🔗
template<class T> complex<T> acosh(const complex<T>& x);
7
#
Returns: The complex arc hyperbolic cosine of x.
8
#
Remarks: Behaves the same as the C function cacosh.
See also: ISO/IEC 9899:2018, 7.3.6.1
🔗
template<class T> complex<T> asinh(const complex<T>& x);
9
#
Returns: The complex arc hyperbolic sine of x.
10
#
Remarks: Behaves the same as the C function casinh.
See also: ISO/IEC 9899:2018, 7.3.6.2
🔗
template<class T> complex<T> atanh(const complex<T>& x);
11
#
Returns: The complex arc hyperbolic tangent of x.
12
#
Remarks: Behaves the same as the C function catanh.
See also: ISO/IEC 9899:2018, 7.3.6.3
🔗
template<class T> complex<T> cos(const complex<T>& x);
13
#
Returns: The complex cosine of x.
🔗
template<class T> complex<T> cosh(const complex<T>& x);
14
#
Returns: The complex hyperbolic cosine of x.
🔗
template<class T> complex<T> exp(const complex<T>& x);
15
#
Returns: The complex base-e exponential of x.
🔗
template<class T> complex<T> log(const complex<T>& x);
16
#
Returns: The complex natural (base-e) logarithm of x.
For all x, imag(log(x)) lies in the interval [, π].
[Note 1: 
The semantics of this function are intended to be the same in C++ as they are for clog in C.
— end note]
17
#
Remarks: The branch cuts are along the negative real axis.
🔗
template<class T> complex<T> log10(const complex<T>& x);
18
#
Returns: The complex common (base-10) logarithm of x, defined as log(x) / log(10).
19
#
Remarks: The branch cuts are along the negative real axis.
🔗
template<class T> complex<T> pow(const complex<T>& x, const complex<T>& y); template<class T> complex<T> pow(const complex<T>& x, const T& y); template<class T> complex<T> pow(const T& x, const complex<T>& y);
20
#
Returns: The complex power of base x raised to the power, defined as exp(y * log(x)).
The value returned for pow(0, 0) is implementation-defined.
21
#
Remarks: The branch cuts are along the negative real axis.
🔗
template<class T> complex<T> sin(const complex<T>& x);
22
#
Returns: The complex sine of x.
🔗
template<class T> complex<T> sinh(const complex<T>& x);
23
#
Returns: The complex hyperbolic sine of x.
🔗
template<class T> complex<T> sqrt(const complex<T>& x);
24
#
Returns: The complex square root of x, in the range of the right half-plane.
[Note 2: 
The semantics of this function are intended to be the same in C++ as they are for csqrt in C.
— end note]
25
#
Remarks: The branch cuts are along the negative real axis.
🔗
template<class T> complex<T> tan(const complex<T>& x);
26
#
Returns: The complex tangent of x.
🔗
template<class T> complex<T> tanh(const complex<T>& x);
27
#
Returns: The complex hyperbolic tangent of x.

28.4.9 Additional overloads [cmplx.over]

1
#
The following function templates shall have additional overloads: arg norm conj proj imag real where norm, conj, imag, and real are constexpr overloads.
2
#
The additional overloads shall be sufficient to ensure:
  • (2.1)
    If the argument has a floating-point type T, then it is effectively cast to complex<T>.
  • (2.2)
    Otherwise, if the argument has integer type, then it is effectively cast to complex<double>.
3
#
Function template pow has additional overloads sufficient to ensure, for a call with one argument of type complex<T1> and the other argument of type T2 or complex<T2>, both arguments are effectively cast to complex<common_type_t<T1, T2>>.
If common_type_t<T1, T2> is not well-formed, then the program is ill-formed.

28.4.10 Suffixes for complex number literals [complex.literals]

1
#
This subclause describes literal suffixes for constructing complex number literals.
The suffixes i, il, and if create complex numbers of the types complex<double>, complex<long double>, and complex<float> respectively, with their imaginary part denoted by the given literal number and the real part being zero.
🔗
constexpr complex<long double> operator""il(long double d); constexpr complex<long double> operator""il(unsigned long long d);
2
#
Returns: complex<long double>{0.0L, static_cast<long double>(d)}.
🔗
constexpr complex<double> operator""i(long double d); constexpr complex<double> operator""i(unsigned long long d);
3
#
Returns: complex<double>{0.0, static_cast<double>(d)}.
🔗
constexpr complex<float> operator""if(long double d); constexpr complex<float> operator""if(unsigned long long d);
4
#
Returns: complex<float>{0.0f, static_cast<float>(d)}.