\rSec0[numerics]{Numerics library}

\rSec1[numerics.general]{General}

This Clause describes components that \Cpp programs may use to perform

seminumerical operations.

The following subclauses describe components for

complex number types, random number generation,

numeric (%

\textit{n}-at-a-time)

arrays, generalized numeric algorithms,

and mathematical functions for floating-point types,

as summarized in Table~\ref{tab:numerics.lib.summary}.

\begin{libsumtab}{Numerics library summary}{tab:numerics.lib.summary}

\ref{numerics.defns} & Definitions & \\

\ref{numeric.requirements} & Requirements & \\ \rowsep

\ref{cfenv} & Floating-point environment & \tcode{<cfenv>} \\ \rowsep

\ref{complex.numbers} & Complex numbers & \tcode{<complex>} \\ \rowsep

\ref{rand} & Random number generation & \tcode{<random>} \\ \rowsep

\ref{numarray} & Numeric arrays & \tcode{<valarray>} \\ \rowsep

\ref{numeric.ops} & Generalized numeric operations & \tcode{<numeric>} \\ \rowsep

\ref{c.math} & Mathematical functions for & \tcode{<cmath>} \\

& floating-point types & \tcode{<cstdlib>} \\

\end{libsumtab}

\rSec1[numerics.defns]{Definitions}

\indexlibrary{generalized_noncommutative_sum@\tcode{\placeholder{GENERALIZED_NONCOMMUTATIVE_SUM}}}%

Define \tcode{\placeholdernc{GENERALIZED_NONCOMMUTATIVE_SUM}(op, a1, ..., aN)} as follows:

\begin{itemize}

\tcode{a1} when \tcode{N} is \tcode{1}, otherwise

\tcode{op(\placeholdernc{GENERALIZED_NONCOMMUTATIVE_SUM}(op, a1, ..., aK),} \\

\tcode{\phantom{op(}\placeholdernc{GENERALIZED_NONCOMMUTATIVE_SUM}(op, aM, ..., aN))}

for any \tcode{K} where $1 < \mathtt{K}+1 = \mathtt{M} \leq \mathtt{N}$.

\end{itemize}

\indexlibrary{generalized_sum@\tcode{\placeholder{GENERALIZED_SUM}}}%

Define \tcode{\placeholdernc{GENERALIZED_SUM}(op, a1, ..., aN)} as

\tcode{\placeholdernc{GENERALIZED_NONCOMMUTATIVE_SUM}(op, b1, ..., bN)},

where

\tcode{b1, ..., bN} may be any permutation of \tcode{a1, ..., aN}.

\rSec1[numeric.requirements]{Numeric type requirements}

\indextext{requirements!numeric type}

The

\tcode{complex}

and

\tcode{valarray}

components are parameterized by the type of information they contain and manipulate.

A \Cpp program shall instantiate these components only with a type

\tcode{T}

that satisfies the

following requirements:\footnote{In other words, value types.

These include arithmetic types,

pointers, the library class

\tcode{complex},

and instantiations of

\tcode{valarray}

for value types.}

\begin{itemize}

\item \tcode{T} is not an abstract class (it has no pure virtual member functions);

\item \tcode{T} is not a reference type;

\item \tcode{T} is not cv-qualified;

\item If \tcode{T} is a class, it has a public default constructor;

\item If \tcode{T} is a class, it has a public copy constructor with the signature \tcode{T::T(const T\&)}

\item If \tcode{T} is a class, it has a public destructor;

\item If \tcode{T} is a class, it has a public assignment operator whose signature is either

\tcode{T\& T::operator=(const T\&)}

or

\tcode{T\& T::operator=(T)}

\item If \tcode{T} is a class, its assignment operator, copy and default constructors,

and destructor shall correspond to each other in the following sense:

\begin{itemize}

\item Initialization of raw storage using the copy constructor

on the value of \tcode{T()}, however obtained,

is semantically equivalent to value-initialization of the same raw storage.

\item Initialization of raw storage using the default constructor,

followed by assignment,

is semantically equivalent to initialization of raw storage using the copy constructor.

\item Destruction of an object,

followed by initialization of its raw storage using the copy constructor,

is semantically equivalent to assignment to the original object.

\end{itemize}

\begin{note}

This rule states, in part, that there shall not be any subtle differences in the semantics

of initialization versus assignment.

This gives an implementation

considerable flexibility in how arrays are initialized.

\begin{example}

An implementation is allowed to initialize a

\tcode{valarray}

by allocating storage using the

\tcode{new}

operator (which

implies a call to the default constructor for each element) and then

assigning each element its value.

Or the implementation can allocate raw

storage and use the copy constructor to initialize each element.

\end{example}

If the distinction between initialization and assignment is important

for a class, or if it fails to satisfy any of

the other conditions listed above, the programmer should use

\tcode{vector}~(\ref{vector}) instead of

\tcode{valarray}

for that class.

\end{note}

\item If \tcode{T} is a class, it does not overload unary

\tcode{operator\&}.

\end{itemize}

If any operation on \tcode{T}

throws an exception the effects are undefined.

In addition, many member and related functions of

\tcode{valarray<T>}

can be successfully instantiated

and will exhibit well-defined behavior if and only if

\tcode{T} satisfies additional requirements specified for each such member

or related function.

\begin{example}

It is valid to instantiate

\tcode{valarray<complex>},

but

\tcode{operator>()}

will not be successfully instantiated for

\tcode{valarray<complex>}

operands, since

\tcode{complex}

does not have any ordering operators.

\end{example}

\rSec1[cfenv]{The floating-point environment}

\rSec2[cfenv.syn]{Header \tcode{<cfenv>} synopsis}

\indextext{\idxhdr{cfenv}}%

\indexlibrary{\idxhdr{cfenv}}%

\indexlibrary{\idxcode{fenv_t}}%

\indexlibrary{\idxcode{fexcept_t}}%

\indexlibrary{\idxcode{feclearexcept}}%

\indexlibrary{\idxcode{fegetexceptflag}}%

\indexlibrary{\idxcode{feraiseexcept}}%

\indexlibrary{\idxcode{fesetexceptflag}}%

\indexlibrary{\idxcode{fetestexcept}}%

\indexlibrary{\idxcode{fegetround}}%

\indexlibrary{\idxcode{fesetround}}%

\indexlibrary{\idxcode{fegetenv}}%

\indexlibrary{\idxcode{feholdexcept}}%

\indexlibrary{\idxcode{fesetenv}}%

\indexlibrary{\idxcode{feupdateenv}}%

\indexlibrary{\idxcode{FE_ALL_EXCEPT}}%

\indexlibrary{\idxcode{FE_DIVBYZERO}}%

\indexlibrary{\idxcode{FE_INEXACT}}%

\indexlibrary{\idxcode{FE_INVALID}}%

\indexlibrary{\idxcode{FE_OVERFLOW}}%

\indexlibrary{\idxcode{FE_UNDERFLOW}}%

\indexlibrary{\idxcode{FE_DOWNWARD}}%

\indexlibrary{\idxcode{FE_TONEAREST}}%

\indexlibrary{\idxcode{FE_TOWARDZERO}}%

\indexlibrary{\idxcode{FE_UPWARD}}%

\indexlibrary{\idxcode{FE_DFL_ENV}}%

\begin{codeblock}

#define FE_ALL_EXCEPT @\seebelow@

#define FE_DIVBYZERO @\seebelow@

#define FE_INEXACT @\seebelow@

#define FE_INVALID @\seebelow@

#define FE_OVERFLOW @\seebelow@

#define FE_UNDERFLOW @\seebelow@

#define FE_DOWNWARD @\seebelow@

#define FE_TONEAREST @\seebelow@

#define FE_TOWARDZERO @\seebelow@

#define FE_UPWARD @\seebelow@

#define FE_DFL_ENV @\seebelow@

namespace std {

// types

using fenv_t = @\textit{object type}@;

using fexcept_t = @\textit{integer type}@;

// functions

int feclearexcept(int except);

int fegetexceptflag(fexcept_t* pflag, int except);

int feraiseexcept(int except);

int fesetexceptflag(const fexcept_t* pflag, int except);

int fetestexcept(int except);

int fegetround();

int fesetround(int mode);

int fegetenv(fenv_t* penv);

int feholdexcept(fenv_t* penv);

int fesetenv(const fenv_t* penv);

int feupdateenv(const fenv_t* penv);

}

\end{codeblock}

The contents and meaning of the header \tcode{<cfenv>}

are the same as the C standard library header \tcode{<fenv.h>}.

\begin{note}

This International Standard does not require an implementation to support the

\tcode{FENV_ACCESS} pragma;

it is \impldef{whether pragma \tcode{FENV_ACCESS} is supported}~(\ref{cpp.pragma})

whether the pragma is supported. As a consequence,

it is \impldef{whether \tcode{<cfenv>} functions can be used to manage floating-point status}

whether these functions can be used to test floating-point status flags,

set floating-point control modes, or run under non-default mode settings.

If the pragma is used to enable control over the floating-point environment,

this International Standard does not specify the effect on

floating-point evaluation in constant expressions.

\end{note}

The floating-point environment has thread storage

duration~(\ref{basic.stc.thread}). The initial state for a thread's floating-point

environment is the state of the floating-point environment of the thread that constructs

the corresponding \tcode{thread} object~(\ref{thread.thread.class}) at the time it

constructed the object. \begin{note} That is, the child thread gets the floating-point

state of the parent thread at the time of the child's creation. \end{note}

A separate floating-point environment shall be maintained for each thread. Each function

accesses the environment corresponding to its calling thread.

\xref ISO C 7.6

\rSec1[complex.numbers]{Complex numbers}

The header

\indextext{\idxhdr{complex}}%

\indexlibrary{\idxhdr{complex}}%

\tcode{<complex>}

defines a

class template,

and numerous functions for representing and manipulating complex numbers.

The effect of instantiating the template

\tcode{complex}

for any type other than \tcode{float}, \tcode{double}, or \tcode{long double} is unspecified.

The specializations

\tcode{complex<float>},

\tcode{complex<double>}, and

\tcode{complex<long double>} are literal types~(\ref{basic.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 \tcode{z} is an lvalue expression of type \cv{} \tcode{complex<T>} then:

\begin{itemize}

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

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

\item \tcode{reinterpret_cast<\cv{} T(\&)[2]>(z)[1]} shall designate the imaginary part of \tcode{z}.

\end{itemize}

Moreover, if \tcode{a} is an expression of type \cv{}~\tcode{complex<T>*} and the expression \tcode{a[i]} is well-defined for an integer expression \tcode{i}, then:

\begin{itemize}

\item \tcode{reinterpret_cast<\cv{} T*>(a)[2*i]} shall designate the real part of \tcode{a[i]}, and

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

\end{itemize}

\rSec2[complex.syn]{Header \tcode{<complex>} synopsis}

\indextext{\idxhdr{complex}}%

\indexlibrary{\idxhdr{complex}}%

\begin{codeblock}

namespace std {

template<class T> class complex;

template<> class complex<float>;

template<> class complex<double>;

template<> class complex<long double>;

// \ref{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>&);

// \ref{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);

// \ref{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>&);

// \ref{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);

}

}

}

\end{codeblock}

\rSec2[complex]{Class template \tcode{complex}}

\indexlibrary{\idxcode{complex}}%

\begin{codeblock}

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

};

}

\end{codeblock}

The class

\tcode{complex}

describes an object that can

store the Cartesian components,

\tcode{real()}

and

\tcode{imag()},

of a complex

number.

\rSec2[complex.special]{\tcode{complex} specializations}

\begin{codeblock}

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

};

}

\end{codeblock}

\rSec2[complex.members]{\tcode{complex} member functions}

\indexlibrary{\idxcode{complex}!constructor}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

Constructs an object of class

\tcode{complex}.

\tcode{real() == re \&\& imag() == im}.

\end{itemdescr}

\indexlibrarymember{real}{complex}%

\begin{itemdecl}

constexpr T real() const;

\end{itemdecl}

\begin{itemdescr}

\returns The value of the real component.

\end{itemdescr}

\indexlibrarymember{real}{complex}%

\begin{itemdecl}

void real(T val);

\end{itemdecl}

\begin{itemdescr}

\effects Assigns \tcode{val} to the real component.

\end{itemdescr}

\indexlibrarymember{imag}{complex}%

\begin{itemdecl}

constexpr T imag() const;

\end{itemdecl}

\begin{itemdescr}

\returns The value of the imaginary component.

\end{itemdescr}

\indexlibrarymember{imag}{complex}%

\begin{itemdecl}

void imag(T val);

\end{itemdecl}

\begin{itemdescr}

\effects Assigns \tcode{val} to the imaginary component.

\end{itemdescr}

\rSec2[complex.member.ops]{\tcode{complex} member operators}

\indexlibrarymember{operator+=}{complex}%

\begin{itemdecl}

complex<T>& operator+=(const T& rhs);

\end{itemdecl}

\begin{itemdescr}

Adds the scalar value \tcode{rhs} to the real part of the complex value

\tcode{*this}

and stores the result in the real part of

\tcode{*this},

leaving the imaginary part unchanged.

\tcode{*this}.

\end{itemdescr}

\indexlibrarymember{operator-=}{complex}%

\begin{itemdecl}

complex<T>& operator-=(const T& rhs);

\end{itemdecl}

\begin{itemdescr}

Subtracts the scalar value \tcode{rhs} from the real part of the complex value

\tcode{*this}

and stores the result in the real part of

\tcode{*this},

leaving the imaginary part unchanged.

\tcode{*this}.

\end{itemdescr}

\indexlibrarymember{operator*=}{complex}%

\begin{itemdecl}

complex<T>& operator*=(const T& rhs);

\end{itemdecl}

\begin{itemdescr}

Multiplies the scalar value \tcode{rhs} by the complex value

\tcode{*this}

and stores the result in

\tcode{*this}.

\tcode{*this}.

\end{itemdescr}

\indexlibrarymember{operator/=}{complex}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

Divides the scalar value \tcode{rhs} into the complex value

\tcode{*this}

and stores the result in

\tcode{*this}.

\tcode{*this}.

\end{itemdescr}

\indexlibrarymember{operator+=}{complex}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

Adds the complex value \tcode{rhs} to the complex value

\tcode{*this}

and stores the sum in

\tcode{*this}.

\tcode{*this}.

\end{itemdescr}

\indexlibrarymember{operator-=}{complex}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

Subtracts the complex value \tcode{rhs} from the complex value

\tcode{*this}

and stores the difference in

\tcode{*this}.

\tcode{*this}.

\end{itemdescr}

\indexlibrarymember{operator*=}{complex}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

Multiplies the complex value \tcode{rhs} by the complex value

\tcode{*this}

and stores the product in

\tcode{*this}.

\tcode{*this}.

\end{itemdescr}

\indexlibrarymember{operator/=}{complex}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

Divides the complex value \tcode{rhs} into the complex value

\tcode{*this}

and stores the quotient in

\tcode{*this}.

\tcode{*this}.

\end{itemdescr}

\rSec2[complex.ops]{\tcode{complex} non-member operations}

\indexlibrarymember{operator+}{complex}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

\tcode{complex<T>(lhs)}.

unary operator.

\end{itemdescr}

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

\tcode{complex<T>(lhs) += rhs}.

\end{itemdescr}

\indexlibrarymember{operator-}{complex}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

\tcode{complex<T>(-lhs.real(),-lhs.imag())}.

unary operator.

\end{itemdescr}

\indexlibrarymember{operator-}{complex}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

\tcode{complex<T>(lhs) -= rhs}.

\end{itemdescr}

\indexlibrarymember{operator*}{complex}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

\tcode{complex<T>(lhs) *= rhs}.

\end{itemdescr}

\indexlibrarymember{operator/}{complex}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

\tcode{complex<T>(lhs) /= rhs}.

\end{itemdescr}

\indexlibrarymember{operator==}{complex}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

\tcode{lhs.real() == rhs.real() \&\& lhs.imag() == rhs.imag()}.

The imaginary part is assumed to be

\tcode{T()},

or 0.0, for the

\tcode{T}

arguments.

\end{itemdescr}

\indexlibrarymember{operator"!=}{complex}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

\tcode{rhs.real() != lhs.real() || rhs.imag() != lhs.imag()}.

\end{itemdescr}

\indexlibrarymember{operator>>}{complex}%

\begin{itemdecl}

template<class T, class charT, class traits>

basic_istream<charT, traits>&

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

\end{itemdecl}

\begin{itemdescr}

The input values shall be convertible to

\tcode{T}.

Extracts a complex number \tcode{x} of the form:

\tcode{u},

\tcode{(u)},

or

\tcode{(u,v)},

where

\tcode{u}

is the real part and

\tcode{v}

is the imaginary part~(\ref{istream.formatted}).

If bad input is encountered, calls

\tcode{is.setstate(ios_base::failbit)}

(which may throw

\tcode{ios::failure} (\ref{iostate.flags})).

\tcode{is}.

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.

\end{itemdescr}

\indexlibrarymember{operator<<}{complex}%

\begin{itemdecl}

template<class T, class charT, class traits>

basic_ostream<charT, traits>&

operator<<(basic_ostream<charT, traits>& o, const complex<T>& x);

\end{itemdecl}

\begin{itemdescr}

Inserts the complex number \tcode{x}

onto the stream \tcode{o} as if it were implemented as follows:

\begin{codeblock}

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

\end{codeblock}

\begin{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

\tcode{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}

\end{itemdescr}

\rSec2[complex.value.ops]{\tcode{complex} value operations}

\indexlibrary{\idxcode{real}!\idxcode{complex}}%

\begin{itemdecl}

template<class T> constexpr T real(const complex<T>& x);

\end{itemdecl}

\begin{itemdescr}

\tcode{x.real()}.

\end{itemdescr}

\indexlibrary{\idxcode{imag}!\idxcode{complex}}%

\begin{itemdecl}

template<class T> constexpr T imag(const complex<T>& x);

\end{itemdecl}

\begin{itemdescr}

\tcode{x.imag()}.

\end{itemdescr}

\indexlibrary{\idxcode{abs}!\idxcode{complex}}%

\begin{itemdecl}

template<class T> T abs(const complex<T>& x);

\end{itemdecl}

\begin{itemdescr}

The magnitude of \tcode{x}.

\end{itemdescr}

\indexlibrary{\idxcode{arg}!\idxcode{complex}}%

\begin{itemdecl}

template<class T> T arg(const complex<T>& x);

\end{itemdecl}

\begin{itemdescr}

The phase angle of \tcode{x}, or \tcode{atan2(imag(x), real(x))}.

\end{itemdescr}

\indexlibrary{\idxcode{norm}!\idxcode{complex}}%

\begin{itemdecl}

template<class T> T norm(const complex<T>& x);

\end{itemdecl}

\begin{itemdescr}

The squared magnitude of \tcode{x}.

\end{itemdescr}

\indexlibrary{\idxcode{conj}!\idxcode{complex}}%

\begin{itemdecl}

template<class T> complex<T> conj(const complex<T>& x);

\end{itemdecl}

\begin{itemdescr}

The complex conjugate of \tcode{x}.

\end{itemdescr}

\indexlibrary{\idxcode{proj}!\idxcode{complex}}%

\begin{itemdecl}

template<class T> complex<T> proj(const complex<T>& x);

\end{itemdecl}

\begin{itemdescr}

\returns The projection of \tcode{x} onto the Riemann sphere.