[complex.numbers] (original) (raw)
26 Numerics library [numerics]
The header <complex> defines a class template, and numerous functions for representing and manipulating complex numbers.
The effect of instantiating the templatecomplexfor any type other than float, double, or long double is unspecified.
The specializationscomplex<float>,complex<double>, andcomplex<long double> are literal types.
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.
If z is an lvalue of type cv complex<T> then:
- the expression reinterpret_cast<cv T(&)[2]>(z) is well-formed,
- reinterpret_cast<cv T(&)[2]>(z)[0] designates the real part of z, and
- 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:
- reinterpret_cast<cv T*>(a)[2*i] designates the real part of a[i], and
- reinterpret_cast<cv T*>(a)[2*i + 1] designates the imaginary part of a[i].
26.4.1 Header synopsis [complex.syn]
namespace std {
template class complex;
template<> class complex; template<> class complex; template<> class complex;
template constexpr complex operator+(const complex&, const complex&); template constexpr complex operator+(const complex&, const T&); template constexpr complex operator+(const T&, const complex&);
template constexpr complex operator-(const complex&, const complex&); template constexpr complex operator-(const complex&, const T&); template constexpr complex operator-(const T&, const complex&);
template constexpr complex operator*(const complex&, const complex&); template constexpr complex operator*(const complex&, const T&); template constexpr complex operator*(const T&, const complex&);
template constexpr complex operator/(const complex&, const complex&); template constexpr complex operator/(const complex&, const T&); template constexpr complex operator/(const T&, const complex&);
template constexpr complex operator+(const complex&); template constexpr complex operator-(const complex&);
template constexpr bool operator==(const complex&, const complex&); template constexpr bool operator==(const complex&, const T&);
template<class T, class charT, class traits> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&, complex&);
template<class T, class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const complex&);
template constexpr T real(const complex&); template constexpr T imag(const complex&);
template T abs(const complex&); template T arg(const complex&); template constexpr T norm(const complex&);
template constexpr complex conj(const complex&); template complex proj(const complex&); template complex polar(const T&, const T& = T());
template complex acos(const complex&); template complex asin(const complex&); template complex atan(const complex&);
template complex acosh(const complex&); template complex asinh(const complex&); template complex atanh(const complex&);
template complex cos (const complex&); template complex cosh (const complex&); template complex exp (const complex&); template complex log (const complex&); template complex log10(const complex&);
template complex pow (const complex&, const T&); template complex pow (const complex&, const complex&); template complex pow (const T&, const complex&);
template complex sin (const complex&); template complex sinh (const complex&); template complex sqrt (const complex&); template complex tan (const complex&); template complex tanh (const complex&);
inline namespace literals { inline namespace complex_literals { constexpr complex operator""il(long double); constexpr complex operator""il(unsigned long long); constexpr complex operator""i(long double); constexpr complex operator""i(unsigned long long); constexpr complex operator""if(long double); constexpr complex operator""if(unsigned long long); } } }
26.4.2 Class template complex [complex]
namespace std { template 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;
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>&);}; }
The classcomplexdescribes an object that can store the Cartesian components,real()andimag(), of a complex number.
26.4.3 Specializations [complex.special]
namespace std { template<> class complex { public: using value_type = float;
constexpr complex(float re = 0.0f, float im = 0.0f);
constexpr complex(const complex<float>&) = default;
constexpr explicit complex(const complex<double>&);
constexpr explicit complex(const complex<long double>&);
constexpr float real() const;
constexpr void real(float);
constexpr float imag() const;
constexpr void imag(float);
constexpr complex& operator= (float);
constexpr complex& operator+=(float);
constexpr complex& operator-=(float);
constexpr complex& operator*=(float);
constexpr complex& operator/=(float);
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>&);};
template<> class complex { public: using value_type = double;
constexpr complex(double re = 0.0, double im = 0.0);
constexpr complex(const complex<float>&);
constexpr complex(const complex<double>&) = default;
constexpr explicit complex(const complex<long double>&);
constexpr double real() const;
constexpr void real(double);
constexpr double imag() const;
constexpr void imag(double);
constexpr complex& operator= (double);
constexpr complex& operator+=(double);
constexpr complex& operator-=(double);
constexpr complex& operator*=(double);
constexpr complex& operator/=(double);
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>&);};
template<> class complex { 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 complex(const complex<long double>&) = default;
constexpr long double real() const;
constexpr void real(long double);
constexpr long double imag() const;
constexpr void imag(long double);
constexpr complex& operator= (long double);
constexpr complex& operator+=(long double);
constexpr complex& operator-=(long double);
constexpr complex& operator*=(long double);
constexpr complex& operator/=(long double);
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>&);}; }
26.4.4 Member functions [complex.members]
template<class T> constexpr complex(const T& re = T(), const T& im = T());
Postconditions: real() == re && imag() == im is true.
constexpr T real() const;
Returns:The value of the real component.
constexpr void real(T val);
Effects:Assigns val to the real component.
constexpr T imag() const;
Returns:The value of the imaginary component.
constexpr void imag(T val);
Effects:Assigns val to the imaginary component.
26.4.5 Member operators [complex.member.ops]
constexpr complex& operator+=(const T& rhs);
Effects:Adds the scalar value rhs to the real part of the complex value*thisand stores the result in the real part of*this, leaving the imaginary part unchanged.
constexpr complex& operator-=(const T& rhs);
Effects:Subtracts the scalar value rhs from the real part of the complex value*thisand stores the result in the real part of*this, leaving the imaginary part unchanged.
constexpr complex& operator*=(const T& rhs);
Effects:Multiplies the scalar value rhs by the complex value*thisand stores the result in*this.
constexpr complex& operator/=(const T& rhs);
Effects:Divides the scalar value rhs into the complex value*thisand stores the result in*this.
template<class X> constexpr complex& operator+=(const complex<X>& rhs);
Effects:Adds the complex value rhs to the complex value*thisand stores the sum in*this.
template<class X> constexpr complex& operator-=(const complex<X>& rhs);
Effects:Subtracts the complex value rhs from the complex value*thisand stores the difference in*this.
template<class X> constexpr complex& operator*=(const complex<X>& rhs);
Effects:Multiplies the complex value rhs by the complex value*thisand stores the product in*this.
template<class X> constexpr complex& operator/=(const complex<X>& rhs);
Effects:Divides the complex value rhs into the complex value*thisand stores the quotient in*this.
26.4.6 Non-member operations [complex.ops]
template<class T> constexpr complex<T> operator+(const complex<T>& lhs);
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);
Returns: complex<T>(lhs) += rhs.
template<class T> constexpr complex<T> operator-(const complex<T>& lhs);
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);
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);
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);
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);
Returns: lhs.real() == rhs.real() && lhs.imag() == rhs.imag().
Remarks:The imaginary part is assumed to beT(), or 0.0, for theTarguments.
template<class T, class charT, class traits> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, complex<T>& x);
Preconditions:The input values are convertible toT.
Effects:Extracts a complex number x of the form:u,(u), or(u,v), whereuis the real part andvis the imaginary part ([istream.formatted]).
If bad input is encountered, callsis.setstate(ios_base::failbit)(which may throwios_base::failure ([iostate.flags])).
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);
Effects:Inserts the complex number xonto 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();
[ 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.
Insertingshowpoint 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
]
26.4.7 Value operations [complex.value.ops]
template<class T> constexpr T real(const complex<T>& x);
template<class T> constexpr T imag(const complex<T>& x);
template<class T> T abs(const complex<T>& x);
Returns:The magnitude of x.
template<class T> T arg(const complex<T>& x);
Returns:The phase angle of x, or atan2(imag(x), real(x)).
template<class T> constexpr T norm(const complex<T>& x);
Returns:The squared magnitude of x.
template<class T> constexpr complex<T> conj(const complex<T>& x);
Returns:The complex conjugate of x.
template<class T> complex<T> proj(const complex<T>& x);
Returns:The projection of x onto the Riemann sphere.
Remarks:Behaves the same as the C function cproj.
See also: ISO C 7.3.9.5
template<class T> complex<T> polar(const T& rho, const T& theta = T());
Preconditions: rho is non-negative and non-NaN.
theta is finite.
Returns:Thecomplexvalue corresponding to a complex number whose magnitude is rho and whose phase angle is theta.
26.4.8 Transcendentals [complex.transcendentals]
template<class T> complex<T> acos(const complex<T>& x);
Returns:The complex arc cosine of x.
Remarks:Behaves the same as the C function cacos.
See also: ISO C 7.3.5.1
template<class T> complex<T> asin(const complex<T>& x);
Returns:The complex arc sine of x.
Remarks:Behaves the same as the C function casin.
See also: ISO C 7.3.5.2
template<class T> complex<T> atan(const complex<T>& x);
Returns:The complex arc tangent of x.
Remarks:Behaves the same as the C function catan.
See also: ISO C 7.3.5.3
template<class T> complex<T> acosh(const complex<T>& x);
Returns:The complex arc hyperbolic cosine of x.
Remarks:Behaves the same as the C function cacosh.
See also: ISO C 7.3.6.1
template<class T> complex<T> asinh(const complex<T>& x);
Returns:The complex arc hyperbolic sine of x.
Remarks:Behaves the same as the C function casinh.
See also: ISO C 7.3.6.2
template<class T> complex<T> atanh(const complex<T>& x);
Returns:The complex arc hyperbolic tangent of x.
Remarks:Behaves the same as the C function catanh.
See also: ISO C 7.3.6.3
template<class T> complex<T> cos(const complex<T>& x);
Returns:The complex cosine of x.
template<class T> complex<T> cosh(const complex<T>& x);
Returns:The complex hyperbolic cosine of x.
template<class T> complex<T> exp(const complex<T>& x);
Returns:The complex base-e exponential of x.
template<class T> complex<T> log(const complex<T>& x);
Returns:The complex natural (base-e) logarithm of x.
For all x,imag(log(x)) lies in the interval [, π].
[ Note
:
The semantics of this function are intended to be the same in C++ as they are for clog in C.
— end note
]
Remarks:The branch cuts are along the negative real axis.
template<class T> complex<T> log10(const complex<T>& x);
Returns:The complex common (base-10) logarithm of x, defined aslog(x) / log(10).
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);
Returns:The complex power of base x raised to the power, defined asexp(y * log(x)).
The value returned forpow(0, 0)is implementation-defined.
Remarks:The branch cuts are along the negative real axis.
template<class T> complex<T> sin(const complex<T>& x);
Returns:The complex sine of x.
template<class T> complex<T> sinh(const complex<T>& x);
Returns:The complex hyperbolic sine of x.
template<class T> complex<T> sqrt(const complex<T>& x);
Returns:The complex square root of x, in the range of the right half-plane.
[ Note
:
The semantics of this function are intended to be the same in C++ as they are for csqrt in C.
— end note
]
Remarks:The branch cuts are along the negative real axis.
template<class T> complex<T> tan(const complex<T>& x);
Returns:The complex tangent of x.
template<class T> complex<T> tanh(const complex<T>& x);
Returns:The complex hyperbolic tangent of x.
26.4.9 Additional overloads [cmplx.over]
The following function templates shall have additional overloads:
arg norm conj proj imag real
where norm, conj, imag, and real are constexpr overloads.
The additional overloads shall be sufficient to ensure:
- If the argument has type long double, then it is effectively cast to complex<long double>.
- Otherwise, if the argument has type double or an integer type, then it is effectively cast to complex<double>.
- Otherwise, if the argument has type float, then it is effectively cast to complex<float>.
Function template pow shall have additional overloads sufficient to ensure, for a call with at least one argument of type complex<T>:
- If either argument has type complex<long double> or type long double, then both arguments are effectively cast tocomplex<long double>.
- Otherwise, if either argument has type complex<double>, double, or an integer type, then both arguments are effectively cast tocomplex<double>.
- Otherwise, if either argument has type complex<float> or float, then both arguments are effectively cast to complex<float>.
26.4.10 Suffixes for complex number literals [complex.literals]
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>, andcomplex<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);
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);
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);
Returns: complex<float>{0.0f, static_cast<float>(d)}.