26 Numerics library [numerics]

26.5 Complex numbers [complex.numbers]

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 other than float, double, or long double is unspecified. The specializations complex<float>, complex<double>, and complex<long double> are literal types ([basic.types]).

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 expression of type cv complex<T> then:

  • (4.1)

    the expression reinterpret_cast<cv T(&)[2]>(z) shall be well-formed,

  • (4.2)

    reinterpret_cast<cv T(&)[2]>(z)[0] shall designate the real part of z, and

  • (4.3)

    reinterpret_cast<cv T(&)[2]>(z)[1] shall designate 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] shall designate the real part of a[i], and

  • (4.5)

    reinterpret_cast<cv T*>(a)[2*i + 1] shall designate the imaginary part of a[i].

26.5.1 Header <complex> synopsis [complex.syn]

namespace std {
  template<class T> class complex;
  template<> class complex<float>;
  template<> class complex<double>;
  template<> class complex<long double>;

  // [complex.ops], operators
  template<class T>
    complex<T> operator+(const complex<T>&, const complex<T>&);
  template<class T> complex<T> operator+(const complex<T>&, const T&);
  template<class T> complex<T> operator+(const T&, const complex<T>&);

  template<class T> complex<T> operator-(
    const complex<T>&, const complex<T>&);
  template<class T> complex<T> operator-(const complex<T>&, const T&);
  template<class T> complex<T> operator-(const T&, const complex<T>&);

  template<class T> complex<T> operator*(
    const complex<T>&, const complex<T>&);
  template<class T> complex<T> operator*(const complex<T>&, const T&);
  template<class T> complex<T> operator*(const T&, const complex<T>&);

  template<class T> complex<T> operator/(
    const complex<T>&, const complex<T>&);
  template<class T> complex<T> operator/(const complex<T>&, const T&);
  template<class T> complex<T> operator/(const T&, const complex<T>&);

  template<class T> complex<T> operator+(const complex<T>&);
  template<class T> 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> constexpr bool operator==(const T&, 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> constexpr bool operator!=(const T&, const complex<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> T norm(const complex<T>&);

  template<class T> 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& = 0);

  // [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);
    }
  }
}

26.5.2 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&);
    template<class X> constexpr complex(const complex<X>&);

    constexpr T real() const;
    void real(T);
    constexpr T imag() const;
    void imag(T);

    complex<T>& operator= (const T&);
    complex<T>& operator+=(const T&);
    complex<T>& operator-=(const T&);
    complex<T>& operator*=(const T&);
    complex<T>& operator/=(const T&);

    complex& operator=(const complex&);
    template<class X> complex<T>& operator= (const complex<X>&);
    template<class X> complex<T>& operator+=(const complex<X>&);
    template<class X> complex<T>& operator-=(const complex<X>&);
    template<class X> complex<T>& operator*=(const complex<X>&);
    template<class X> complex<T>& operator/=(const complex<X>&);
  };
}
1

The class complex describes an object that can store the Cartesian components, real() and imag(), of a complex number.

26.5.3 complex specializations [complex.special]

namespace std {
  template<> class complex<float> {
  public:
    using value_type = float;

    constexpr complex(float re = 0.0f, float im = 0.0f);
    constexpr explicit complex(const complex<double>&);
    constexpr explicit complex(const complex<long double>&);

    constexpr float real() const;
    void real(float);
    constexpr float imag() const;
    void imag(float);

    complex<float>& operator= (float);
    complex<float>& operator+=(float);
    complex<float>& operator-=(float);
    complex<float>& operator*=(float);
    complex<float>& operator/=(float);

    complex<float>& operator=(const complex<float>&);
    template<class X> complex<float>& operator= (const complex<X>&);
    template<class X> complex<float>& operator+=(const complex<X>&);
    template<class X> complex<float>& operator-=(const complex<X>&);
    template<class X> complex<float>& operator*=(const complex<X>&);
    template<class X> complex<float>& operator/=(const complex<X>&);
  };

  template<> class complex<double> {
  public:
    using value_type = double;

    constexpr complex(double re = 0.0, double im = 0.0);
    constexpr complex(const complex<float>&);
    constexpr explicit complex(const complex<long double>&);

    constexpr double real() const;
    void real(double);
    constexpr double imag() const;
    void imag(double);

    complex<double>& operator= (double);
    complex<double>& operator+=(double);
    complex<double>& operator-=(double);
    complex<double>& operator*=(double);
    complex<double>& operator/=(double);

    complex<double>& operator=(const complex<double>&);
    template<class X> complex<double>& operator= (const complex<X>&);
    template<class X> complex<double>& operator+=(const complex<X>&);
    template<class X> complex<double>& operator-=(const complex<X>&);
    template<class X> complex<double>& operator*=(const complex<X>&);
    template<class X> complex<double>& operator/=(const complex<X>&);
  };

  template<> class complex<long double> {
  public:
    using value_type = long double;

    constexpr complex(long double re = 0.0L, long double im = 0.0L);
    constexpr complex(const complex<float>&);
    constexpr complex(const complex<double>&);

    constexpr long double real() const;
    void real(long double);
    constexpr long double imag() const;
    void imag(long double);

    complex<long double>& operator=(const complex<long double>&);
    complex<long double>& operator= (long double);
    complex<long double>& operator+=(long double);
    complex<long double>& operator-=(long double);
    complex<long double>& operator*=(long double);
    complex<long double>& operator/=(long double);

    template<class X> complex<long double>& operator= (const complex<X>&);
    template<class X> complex<long double>& operator+=(const complex<X>&);
    template<class X> complex<long double>& operator-=(const complex<X>&);
    template<class X> complex<long double>& operator*=(const complex<X>&);
    template<class X> complex<long double>& operator/=(const complex<X>&);
  };
}

26.5.4 complex member functions [complex.members]

template<class T> constexpr complex(const T& re = T(), const T& im = T());

1

Effects: Constructs an object of class complex.

2

Postconditions: real() == re && imag() == im.

constexpr T real() const;

Returns: The value of the real component.

void real(T val);

Effects: Assigns val to the real component.

constexpr T imag() const;

Returns: The value of the imaginary component.

void imag(T val);

Effects: Assigns val to the imaginary component.

26.5.5 complex member operators [complex.member.ops]

complex<T>& 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.

complex<T>& 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.

complex<T>& 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.

complex<T>& 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> complex<T>& 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> complex<T>& 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> complex<T>& operator*=(const complex<X>& rhs);

13

Effects: Multiplies the complex value rhs by the complex value *this and stores the product in *this.

Returns: *this.

template<class X> complex<T>& operator/=(const complex<X>& rhs);

14

Effects: Divides the complex value rhs into the complex value *this and stores the quotient in *this.

15

Returns: *this.

26.5.6 complex non-member operations [complex.ops]

template<class T> complex<T> operator+(const complex<T>& lhs);

1

Returns: complex<T>(lhs).

2

Remarks: unary operator.

template<class T> complex<T> operator+(const complex<T>& lhs, const complex<T>& rhs); template<class T> complex<T> operator+(const complex<T>& lhs, const T& rhs); template<class T> complex<T> operator+(const T& lhs, const complex<T>& rhs);

3

Returns: complex<T>(lhs) += rhs.

template<class T> complex<T> operator-(const complex<T>& lhs);

4

Returns: complex<T>(-lhs.real(),-lhs.imag()).

5

Remarks: unary operator.

template<class T> complex<T> operator-(const complex<T>& lhs, const complex<T>& rhs); template<class T> complex<T> operator-(const complex<T>& lhs, const T& rhs); template<class T> complex<T> operator-(const T& lhs, const complex<T>& rhs);

6

Returns: complex<T>(lhs) -= rhs.

template<class T> complex<T> operator*(const complex<T>& lhs, const complex<T>& rhs); template<class T> complex<T> operator*(const complex<T>& lhs, const T& rhs); template<class T> complex<T> operator*(const T& lhs, const complex<T>& rhs);

7

Returns: complex<T>(lhs) *= rhs.

template<class T> complex<T> operator/(const complex<T>& lhs, const complex<T>& rhs); template<class T> complex<T> operator/(const complex<T>& lhs, const T& rhs); template<class T> complex<T> operator/(const T& lhs, const complex<T>& rhs);

8

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); template<class T> constexpr bool operator==(const T& lhs, const complex<T>& rhs);

9

Returns: lhs.real() == rhs.real() && lhs.imag() == rhs.imag().

10

Remarks: The imaginary part is assumed to be T(), or 0.0, for the T arguments.

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); template<class T> constexpr bool operator!=(const T& lhs, const complex<T>& rhs);

11

Returns: rhs.real() != lhs.real() || rhs.imag() != lhs.imag().

template<class T, class charT, class traits> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, complex<T>& x);

12

Requires: The input values shall be convertible to T.

13

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]).

14

If bad input is encountered, calls is.setstate(ios_base::failbit) (which may throw ios::failure ([iostate.flags])).

15

Returns: is.

16

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);

17

Effects: inserts the complex number x onto the stream o as if it were implemented as follows:

template<class T, class charT, class traits>
basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& o, const complex<T>& x) {
  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();
}
18

Note: 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.

26.5.7 complex 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> T norm(const complex<T>& x);

5

Returns: The squared magnitude of x.

template<class T> 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, defined in 7.3.9.4.

template<class T> complex<T> polar(const T& rho, const T& theta = 0);

9

Requires: rho shall be non-negative and non-NaN. theta shall be finite.

10

Returns: The complex value corresponding to a complex number whose magnitude is rho and whose phase angle is theta.

26.5.8 complex 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 C function cacos, defined in 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 C function casin, defined in 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 C function catan, defined in 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 C function cacosh, defined in 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 C function casinh, defined in 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 C function catanh, defined in 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 [-π, π], and when x is a negative real number, imag(log(x)) is π.

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 yth 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. If the argument is a negative real number, the value returned lies on the positive imaginary axis.

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.

26.5.9 Additional overloads [cmplx.over]

1

The following function templates shall have additional overloads: 

arg                   norm 
conj                  proj
imag                  real
2

The additional overloads shall be sufficient to ensure:

  1. 1.

    If the argument has type long double, then it is effectively cast to complex<long double>.

  2. 2.

    Otherwise, if the argument has type double or an integer type, then it is effectively cast to complex<double>.

  3. 3.

    Otherwise, if the argument has type float, then it is effectively cast to complex<float>.

3

Function template pow shall have additional overloads sufficient to ensure, for a call with at least one argument of type complex<T>:

  1. 1.

    If either argument has type complex<long double> or type long double, then both arguments are effectively cast to complex<long double>.

  2. 2.

    Otherwise, if either argument has type complex<double>, double, or an integer type, then both arguments are effectively cast to complex<double>.

  3. 3.

    Otherwise, if either argument has type complex<float> or float, then both arguments are effectively cast to complex<float>.

26.5.10 Suffixes for complex number literals [complex.literals]

1

This section 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)}.

26.5.11 Header <ccomplex> synopsis [ccomplex.syn]

#include <complex>
1

The header <ccomplex> behaves as if it simply includes the header <complex>.