\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 facilities included from the ISO C library,

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

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

\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} & C library & \tcode{<cmath>} \\

& & \tcode{<ctgmath>} \\

& & \tcode{<tgmath.h>}\\

& & \tcode{<cstdlib>} \\

\end{libsumtab}

\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:

Initialization of raw storage using the default constructor, followed by

assignment, is semantically equivalent to initialization of raw

storage using the copy constructor.

Destruction of an object, followed by

initialization of its raw storage using the copy constructor,

is semantically equivalent to assignment to the original object.

This rule states 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.

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.

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;

\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.

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.

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

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

\indexlibrary{\idxhdr{cfenv}}%

\begin{codeblock}

namespace std {

// types

typedef @\textit{object type}@ fenv_t;

typedef @\textit{integer type}@ fexcept_t;

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

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}

\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}}%

The header also defines the macros:

\begin{codeblock}

FE_ALL_EXCEPT

FE_DIVBYZERO

FE_INEXACT

FE_INVALID

FE_OVERFLOW

FE_UNDERFLOW

FE_DOWNWARD

FE_TONEAREST

FE_TOWARDZERO

FE_UPWARD

FE_DFL_ENV

\end{codeblock}

The header defines all functions, types, and macros the same as

Clause 7.6 of the C standard.

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{std::thread} object~(\ref{thread.thread.class}) at the time it

constructed the object. \enternote That is, the child thread gets the floating-point

state of the parent thread at the time of the child's creation. \exitnote

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

accesses the environment corresponding to its calling thread.

\rSec1[complex.numbers]{Complex numbers}

The header

\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 \emph{cv} \tcode{std::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 \tcode{cv std::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}

\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:

typedef T value_type;

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:

typedef float value_type;

constexpr complex(float re = 0.0f, float im = 0.0f);

explicit constexpr complex(const complex<double>&);

explicit constexpr 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:

typedef double value_type;

constexpr complex(double re = 0.0, double im = 0.0);

constexpr complex(const complex<float>&);

explicit constexpr 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:

typedef long double value_type;

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}!\idxcode{complex}}%

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

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

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

\begin{itemdecl}

constexpr T real() const;

\end{itemdecl}

\begin{itemdescr}

\returns The value of the real component.

\end{itemdescr}

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

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

\begin{itemdecl}

void real(T val);

\end{itemdecl}

\begin{itemdescr}

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

\end{itemdescr}

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

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

\begin{itemdecl}

constexpr T imag() const;

\end{itemdecl}

\begin{itemdescr}

\returns The value of the imaginary component.

\end{itemdescr}

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

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

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

\indexlibrary{\idxcode{operator+=}!\idxcode{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}

\indexlibrary{\idxcode{operator-=}!\idxcode{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}

\indexlibrary{\idxcode{operator*=}!\idxcode{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}

\indexlibrary{\idxcode{operator/=}!\idxcode{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}

\indexlibrary{\idxcode{operator+=}!\idxcode{complex}}%

\begin{itemdecl}

complex<T>& operator+=(const complex<T>& 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}

\indexlibrary{\idxcode{operator-=}!\idxcode{complex}}%

\begin{itemdecl}

complex<T>& operator-=(const complex<T>& 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}

\indexlibrary{\idxcode{operator*=}!\idxcode{complex}}%

\begin{itemdecl}

complex<T>& operator*=(const complex<T>& 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}

\indexlibrary{\idxcode{operator/=}!\idxcode{complex}}%

\begin{itemdecl}

complex<T>& operator/=(const complex<T>& 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}

\indexlibrary{\idxcode{operator+}!\idxcode{complex}}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

unary operator.

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

\end{itemdescr}

\begin{codeblock}

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{codeblock}

\begin{itemdescr}

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

\end{itemdescr}

\indexlibrary{\idxcode{operator-}!\idxcode{complex}}%

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

unary operator.

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

\end{itemdescr}

\indexlibrary{\idxcode{operator-}!\idxcode{complex}}%

\indexlibrary{\idxcode{complex}!\idxcode{operator-}}%

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

\indexlibrary{\idxcode{operator*}!\idxcode{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}

\indexlibrary{\idxcode{operator/}!\idxcode{complex}}%

\indexlibrary{\idxcode{complex}!\idxcode{operator/}}%

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

\indexlibrary{\idxcode{operator==}!\idxcode{complex}}%

\begin{itemdecl}

template<class T>

bool constexpr 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}

\indexlibrary{\idxcode{operator"!=}!\idxcode{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}

\indexlibrary{operator>>@\tcode{operator\shr}!\idxcode{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}

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

The input values shall be convertible to

\tcode{T}.

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}

\indexlibrary{operator<<@\tcode{operator\shl}!\idxcode{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}

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

}

\end{codeblock}

\realnote 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{std::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{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.

Behaves the same as the C function \tcode{cproj}, defined in 7.3.9.4.

\end{itemdescr}

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

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

The

\tcode{complex}

value corresponding

to a complex number whose magnitude is \tcode{rho} and whose phase angle

is \tcode{theta}.

\end{itemdescr}

\rSec2[complex.transcendentals]{\tcode{complex} transcendentals}

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

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

\begin{itemdecl}

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

\end{itemdecl}

\begin{itemdescr}

\returns The complex arc cosine of \tcode{x}.