cppdraft_translate/cppdraft/complex/numbers.md

[complex.numbers]

29 Numerics library [numerics]

29.4 Complex numbers [complex.numbers]

29.4.1 General [complex.numbers.general]

1

#

The header defines a class template, and numerous functions for representing and manipulating complex numbers.

2

#

The effect of instantiating the primary template of complex for any type that is not a cv-unqualified floating-point type ([basic.fundamental]) is unspecified.

Specializations of complex for cv-unqualified floating-point types are trivially copyable literal types ([basic.types.general]).

3

#

If the result of a function is not mathematically defined or not in the range of representable values for its type, the behavior is undefined.

4

#

If z is an lvalue of type cv complex then:

• (4.1)

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

• (4.2)

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

• (4.3)

reinterpret_cast<cv T(&)[2]>(z)[1] designates the imaginary part of z.

Moreover, if a is an expression of type cv complex* and the expression a[i] is well-defined for an integer expression i, then:

• (4.4)

reinterpret_cast<cv T*>(a)[2 * i] designates the real part of a[i], and

• (4.5)

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

29.4.2 Header synopsis [complex.syn]

🔗

namespace std {// [complex], class template complextemplate class complex; // [complex.ops], operatorstemplate 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&); // [complex.value.ops], valuestemplate constexpr T real(const complex&); template constexpr T imag(const complex&); template constexpr T abs(const complex&); template constexpr T arg(const complex&); template constexpr T norm(const complex&); template constexpr complex conj(const complex&); template constexpr complex proj(const complex&); template constexpr complex polar(const T&, const T& = T()); // [complex.transcendentals], transcendentalstemplate constexpr complex acos(const complex&); template constexpr complex asin(const complex&); template constexpr complex atan(const complex&); template constexpr complex acosh(const complex&); template constexpr complex asinh(const complex&); template constexpr complex atanh(const complex&); template constexpr complex cos (const complex&); template constexpr complex cosh (const complex&); template constexpr complex exp (const complex&); template constexpr complex log (const complex&); template constexpr complex log10(const complex&); template constexpr complex pow (const complex&, const T&); template constexpr complex pow (const complex&, const complex&); template constexpr complex pow (const T&, const complex&); template constexpr complex sin (const complex&); template constexpr complex sinh (const complex&); template constexpr complex sqrt (const complex&); template constexpr complex tan (const complex&); template constexpr complex tanh (const complex&); // [complex.tuple], tuple interfacetemplate struct tuple_size; template<size_t I, class T> struct tuple_element; template struct tuple_size<complex>; template<size_t I, class T> struct tuple_element<I, complex>; template<size_t I, class T>constexpr T& get(complex&) noexcept; template<size_t I, class T>constexpr T&& get(complex&&) noexcept; template<size_t I, class T>constexpr const T& get(const complex&) noexcept; template<size_t I, class T>constexpr const T&& get(const complex&&) noexcept; // [complex.literals], complex literalsinline 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); }}}

29.4.3 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&) = default; template constexpr explicit(see below) complex(const complex&); 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 constexpr complex& operator= (const complex&); template constexpr complex& operator+=(const complex&); template constexpr complex& operator-=(const complex&); template constexpr complex& operator*=(const complex&); template constexpr complex& operator/=(const complex&); };}

1

#

The classcomplex describes an object that can store the Cartesian components,real() andimag(), of a complex number.

29.4.4 Member functions [complex.members]

🔗

constexpr complex(const T& re = T(), const T& im = T());

1

#

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

🔗

template<class X> constexpr explicit(see below) complex(const complex<X>& other);

2

#

Effects: Initializes the real part with other.real() and the imaginary part with other.imag().

3

#

Remarks: The expression inside explicit evaluates to false if and only if the floating-point conversion rank of T is greater than or equal to the floating-point conversion rank of X.

🔗

constexpr T real() const;

4

#

Returns: The value of the real component.

🔗

constexpr void real(T val);

5

#

Effects: Assigns val to the real component.

🔗

constexpr T imag() const;

6

#

Returns: The value of the imaginary component.

🔗

constexpr void imag(T val);

7

#

Effects: Assigns val to the imaginary component.

29.4.5 Member operators [complex.member.ops]

🔗

constexpr complex& operator+=(const T& rhs);

1

#

Effects: Adds the scalar value rhs to the real part of the complex valuethis and stores the result in the real part ofthis, leaving the imaginary part unchanged.

2

#

Returns: *this.

🔗

constexpr complex& operator-=(const T& rhs);

3

#

Effects: Subtracts the scalar value rhs from the real part of the complex valuethis and stores the result in the real part ofthis, leaving the imaginary part unchanged.

4

#

Returns: *this.

🔗

constexpr complex& operator*=(const T& rhs);

5

#

Effects: Multiplies the scalar value rhs by the complex valuethis and stores the result inthis.

6

#

Returns: *this.

🔗

constexpr complex& operator/=(const T& rhs);

7

#

Effects: Divides the scalar value rhs into the complex valuethis and stores the result inthis.

8

#

Returns: *this.

🔗

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

9

#

Effects: Assigns the value rhs.real() to the real part and the value rhs.imag() to the imaginary part of the complex value *this.

10

#

Returns: *this.

🔗

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

11

#

Effects: Adds the complex value rhs to the complex valuethis and stores the sum inthis.

12

#

Returns: *this.

🔗

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

13

#

Effects: Subtracts the complex value rhs from the complex valuethis and stores the difference inthis.

14

#

Returns: *this.

🔗

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

15

#

Effects: Multiplies the complex value rhs by the complex valuethis and stores the product inthis.

16

#

Returns: *this.

🔗

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

17

#

Effects: Divides the complex value rhs into the complex valuethis and stores the quotient inthis.

18

#

Returns: *this.

29.4.6 Non-member operations [complex.ops]

🔗

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

1

#

Returns: complex(lhs).

🔗

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

2

#

Returns: complex(lhs) += rhs.

🔗

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

3

#

Returns: complex(-lhs.real(),-lhs.imag()).

🔗

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

4

#

Returns: complex(lhs) -= rhs.

🔗

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

5

#

Returns: complex(lhs) *= rhs.

🔗

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

6

#

Returns: complex(lhs) /= rhs.

🔗

template<class T> constexpr bool operator==(const complex<T>& lhs, const complex<T>& rhs); template<class T> constexpr bool operator==(const complex<T>& lhs, const T& rhs);

7

#

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

8

#

Remarks: The imaginary part is assumed to beT(), or 0.0, for theT arguments.

🔗

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

9

#

Preconditions: The input values are convertible toT.

10

#

Effects: Extracts a complex number x of the form:u,(u), or(u,v), whereu is the real part andv is the imaginary part ([istream.formatted]).

11

#

If bad input is encountered, callsis.setstate(ios_base​::​failbit) (which may throwios_base​::​​failure ([iostate.flags])).

12

#

Returns: is.

13

#

Remarks: This extraction is performed as a series of simpler extractions.

Therefore, the skipping of whitespace is specified to be the same for each of the simpler extractions.

🔗

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

14

#

Effects: Inserts the complex number x onto the stream o as if it were implemented as follows:basic_ostringstream<charT, traits> s; s.flags(o.flags()); s.imbue(o.getloc()); s.precision(o.precision()); s << '(' << x.real() << ',' << x.imag() << ')';return o << s.str();

15

#

[Note 1:

In a locale in which comma is used as a decimal point character, the use of comma as a field separator can be ambiguous.

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]

29.4.7 Value operations [complex.value.ops]

🔗

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

1

#

Returns: x.real().

🔗

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

2

#

Returns: x.imag().

🔗

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

3

#

Returns: The magnitude of x.

🔗

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

4

#

Returns: The phase angle of x, or atan2(imag(x), real(x)).

🔗

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

5

#

Returns: The squared magnitude of x.

🔗

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

6

#

Returns: The complex conjugate of x.

🔗

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

7

#

Returns: The projection of x onto the Riemann sphere.

8

#

Remarks: Behaves the same as the C function cproj.

See also: ISO/IEC 9899:2024, 7.3.9.5

🔗

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

9

#

Preconditions: rho is non-negative and non-NaN.

theta is finite.

10

#

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

29.4.8 Transcendentals [complex.transcendentals]

🔗

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

1

#

Returns: The complex arc cosine of x.

2

#

Remarks: Behaves the same as the C function cacos.

See also: ISO/IEC 9899:2024, 7.3.5.1

🔗

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

3

#

Returns: The complex arc sine of x.

4

#

Remarks: Behaves the same as the C function casin.

See also: ISO/IEC 9899:2024, 7.3.5.2

🔗

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

5

#

Returns: The complex arc tangent of x.

6

#

Remarks: Behaves the same as the C function catan.

See also: ISO/IEC 9899:2024, 7.3.5.3

🔗

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

7

#

Returns: The complex arc hyperbolic cosine of x.

8

#

Remarks: Behaves the same as the C function cacosh.

See also: ISO/IEC 9899:2024, 7.3.6.1

🔗

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

9

#

Returns: The complex arc hyperbolic sine of x.

10

#

Remarks: Behaves the same as the C function casinh.

See also: ISO/IEC 9899:2024, 7.3.6.2

🔗

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

11

#

Returns: The complex arc hyperbolic tangent of x.

12

#

Remarks: Behaves the same as the C function catanh.

See also: ISO/IEC 9899:2024, 7.3.6.3

🔗

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

13

#

Returns: The complex cosine of x.

🔗

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

14

#

Returns: The complex hyperbolic cosine of x.

🔗

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

15

#

Returns: The complex base-e exponential of x.

🔗

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

16

#

Returns: The complex natural (base-e) logarithm of x.

For all x,imag(log(x)) lies in the interval [−π, π].

[Note 1:

The semantics of this function are intended to be the same in C++ as they are for clog in C.

— end note]

17

#

Remarks: The branch cuts are along the negative real axis.

🔗

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

18

#

Returns: The complex common (base-10) logarithm of x, defined aslog(x) / log(10).

19

#

Remarks: The branch cuts are along the negative real axis.

🔗

template<class T> constexpr complex<T> pow(const complex<T>& x, const complex<T>& y); template<class T> constexpr complex<T> pow(const complex<T>& x, const T& y); template<class T> constexpr complex<T> pow(const T& x, const complex<T>& y);

20

#

Returns: The complex power of base x raised to the yth power, defined asexp(y * log(x)).

The value returned forpow(0, 0) is implementation-defined.

21

#

Remarks: The branch cuts are along the negative real axis.

🔗

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

22

#

Returns: The complex sine of x.

🔗

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

23

#

Returns: The complex hyperbolic sine of x.

🔗

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

24

#

Returns: The complex square root of x, in the range of the right half-plane.

[Note 2:

The semantics of this function are intended to be the same in C++ as they are for csqrt in C.

— end note]

25

#

Remarks: The branch cuts are along the negative real axis.

🔗

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

26

#

Returns: The complex tangent of x.

🔗

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

27

#

Returns: The complex hyperbolic tangent of x.

29.4.9 Tuple interface [complex.tuple]

🔗

`template struct tuple_size<complex> : integral_constant<size_t, 2> {};

template<size_t I, class T> struct tuple_element<I, complex> { using type = T; }; `

1

#

Mandates: I < 2 is true.

🔗

template<size_t I, class T> constexpr T& get(complex<T>& z) noexcept; template<size_t I, class T> constexpr T&& get(complex<T>&& z) noexcept; template<size_t I, class T> constexpr const T& get(const complex<T>& z) noexcept; template<size_t I, class T> constexpr const T&& get(const complex<T>&& z) noexcept;

2

#

Mandates: I < 2 is true.

3

#

Returns: A reference to the real part of z if I == 0 is true, otherwise a reference to the imaginary part of z.

29.4.10 Additional overloads [cmplx.over]

1

#

The following function templates have additional constexpr overloads:arg norm conj proj imag real

2

#

The additional constexpr overloads are sufficient to ensure:

• (2.1)

  If the argument has a floating-point type T, then it is effectively cast to complex.

• (2.2)

  Otherwise, if the argument has integer type, then it is effectively cast to complex.

3

#

Function template pow has additional constexpr overloads sufficient to ensure, for a call with one argument of type complex and the other argument of type T2 or complex, both arguments are effectively cast to complex<common_type_t<T1, T3>>, where T3 isdouble if T2 is an integer type and T2 otherwise.

If common_type_t<T1, T3> is not well-formed, then the program is ill-formed.

29.4.11 Suffixes for complex number literals [complex.literals]

1

#

This subclause describes literal suffixes for constructing complex number literals.

The suffixes i, il, and if create complex numbers of the types complex, complex, andcomplex 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{0.0L, static_cast(d)}.

🔗

constexpr complex<double> operator""i(long double d); constexpr complex<double> operator""i(unsigned long long d);

3

#

Returns: complex{0.0, static_cast(d)}.

🔗

constexpr complex<float> operator""if(long double d); constexpr complex<float> operator""if(unsigned long long d);

4

#

Returns: complex{0.0f, static_cast(d)}.