home | help 
std::complex(3) 	       C++ Standard Libary		 std::complex(3)

NAME
     std::complex - std::complex

Synopsis
	Defined in header <complex>
	template< class T >		       (1)
	class complex;
	template<> class complex<float>;       (2) (until C++23)
	template<> class complex<double>;      (3) (until C++23)
	template<> class complex<long double>; (4) (until C++23)

	Specializations of std::complex for cv-unqualified
	standard
	(until C++23) floating-point types are
	TriviallyCopyable
	(since	C++23)	LiteralTypes  for  representing and manipulating complex
     number.

Template parameters
	    the type of the real and imaginary parts. The behavior  is	unspeci-
     fied (and may
	T - fail to compile) if T is not a cv-unqualified
	    standard
	    (until C++23) floating-point type and undefined if T is not Numeric-
     Type.

Member types
	Member type Definition
	value_type  T

Member functions
	constructor   constructs a complex number
		      (public member function)
	operator=     assigns the contents
		      (public member function)
	real	      accesses the real part of the complex number
		      (public member function)
	imag	      accesses the imaginary part of the complex number
		      (public member function)
	operator+=
	operator-=     compound  assignment  of two complex numbers or a complex
     and a scalar
	operator*=    (public member function)
	operator/=

Non-member functions
	operator+	    applies unary operators to complex numbers
	operator-	    (function template)
	operator+	    performs complex number arithmetic	on  two  complex
     values or a
	operator-	    complex and a scalar
	operator*	    (function template)
	operator/
	operator==	     compares  two  complex  numbers  or a complex and a
     scalar
	operator!=	    (function template)
	(removed in C++20)
	operator<<	    serializes and deserializes a complex number
	operator>>	    (function template)
	get(std::complex)   obtains a reference to real or imaginary part from a
	(C++26) 	    std::complex
			    (function template)
	real		    returns the real part
			    (function template)
	imag		    returns the imaginary part
			    (function template)
	abs(std::complex)   returns the magnitude of a complex number
			    (function template)
	arg		    returns the phase angle
			    (function template)
	norm		    returns the squared magnitude
			    (function template)
	conj		    returns the complex conjugate
			    (function template)
	proj		    returns the projection onto the Riemann sphere
	(C++11) 	    (function template)
	polar		    constructs a complex number from magnitude and phase
     angle
			    (function template)

Exponential functions
	exp(std::complex)   complex base e exponential
			    (function template)
			    complex natural logarithm with the branch cuts along
     the
	log(std::complex)   negative real axis
			    (function template)
			    complex common logarithm with the branch cuts  along
     the negative
	log10(std::complex) real axis
			    (function template)

Power functions
	pow(std::complex)    complex  power, one or both arguments may be a com-
     plex number
			    (function template)
	sqrt(std::complex)  complex square root in the range of the right  half-
     plane
			    (function template)

Trigonometric functions
	sin(std::complex)	computes    sine    of	  a    complex	  number
     (\({\small\sin{z}}\)sin(z))
			    (function template)
	cos(std::complex)     computes	  cosine    of	  a    complex	  number
     (\({\small\cos{z}}\)cos(z))
			    (function template)
	tan(std::complex)      computes    tangent    of    a	complex   number
     (\({\small\tan{z}}\)tan(z))
			    (function template)
	asin(std::complex)  computes arc sine of a complex number
	(C++11) 	    (\({\small\arcsin{z}}\)arcsin(z))
			    (function template)
	acos(std::complex)  computes arc cosine of a complex number
	(C++11) 	    (\({\small\arccos{z}}\)arccos(z))
			    (function template)
	atan(std::complex)  computes arc tangent of a complex number
	(C++11) 	    (\({\small\arctan{z}}\)arctan(z))
			    (function template)

Hyperbolic functions
			    computes hyperbolic sine of a complex number
	sinh(std::complex)  (\({\small\sinh{z}}\)sinh(z))
			    (function template)
			    computes hyperbolic cosine of a complex number
	cosh(std::complex)  (\({\small\cosh{z}}\)cosh(z))
			    (function template)
			    computes hyperbolic tangent of a complex number
	tanh(std::complex)  (\({\small\tanh{z}}\)tanh(z))
			    (function template)
	asinh(std::complex) computes area hyperbolic sine of a complex number
	(C++11) 	    (\({\small\operatorname{arsinh}{z}}\)arsinh(z))
			    (function template)
	acosh(std::complex) computes area hyperbolic cosine of a complex number
	(C++11) 	    (\({\small\operatorname{arcosh}{z}}\)arcosh(z))
			    (function template)
	atanh(std::complex) computes area hyperbolic tangent of a complex number
	(C++11) 	    (\({\small\operatorname{artanh}{z}}\)artanh(z))
			    (function template)

Helper types
	std::tuple_size<std::complex>	 obtains the number of components  of  a
     std::complex
	(C++26) 			 (class template specialization)
	std::tuple_element<std::complex>  obtains the underlying real and imagi-
     nary number
	(C++26) 			 type of a std::complex
					 (class template specialization)

	Array-oriented access

	For    any    object	z    of    type    std::complex<T>,	reinter-
     pret_cast<T(&)[2]>(z)[0] is the
	real part of z and reinterpret_cast<T(&)[2]>(z)[1] is the imaginary part
     of z.

	For any pointer to an element of an array of std::complex<T> named p and
     any valid
	array  index  i,  reinterpret_cast<T*>(p)[2 * i] is the real part of the
     complex number
	p[i], and reinterpret_cast<T*>(p)[2 * i + 1] is the  imaginary	part  of
     the complex
	number p[i].

	The  intent  of this requirement is to preserve binary compatibility be-
     tween the C++
	library complex number types and the C	language  complex  number  types
     (and arrays
	thereof), which have an identical object representation requirement.

Implementation notes
	In order to satisfy the requirements of array-oriented access, an imple-
     mentation is
	constrained to store the real and imaginary parts of a std::complex spe-
     cialization
	in separate and adjacent memory locations. Possible declarations for its
     non-static
	data members include:

	  *  an  array of type value_type[2], with the first element holding the
     real part and
	    the second element holding the imaginary part (e.g. Microsoft Visual
     Studio);
	  * a single member of type value_type _Complex (encapsulating the  cor-
     responding C
	    language complex number type) (e.g. GNU libstdc++);
	  * two members of type value_type, with the same member access, holding
     the real
	    and the imaginary parts respectively (e.g. LLVM libc++).

	An implementation cannot declare additional non-static data members that
     would
	occupy	storage disjoint from the real and imaginary parts, and must en-
     sure that the
	class template specialization does not contain any padding bit. The  im-
     plementation
	must also ensure that optimizations to array access account for the pos-
     sibility that
	a pointer to value_type may be aliasing a std::complex specialization or
     array
	thereof.

Literals
	Defined in inline namespace std::literals::complex_literals
	operator""if
	operator""i    a std::complex literal representing purely imaginary num-
     ber
	operator""il   (function)
	(C++14)

Notes
	    Feature-test macro	     Value    Std		    Feature
				    201711L  (C++20)  Constexpr  simple  complex
     mathematical
	__cpp_lib_constexpr_complex		    functions in <complex>
				    202306L (C++26) More constexpr for <complex>

Example
     // Run this code

      #include <cmath>
      #include <complex>
      #include <iomanip>
      #include <iostream>

      int main()
      {
	  using namespace std::complex_literals;
	  std::cout << std::fixed << std::setprecision(1);

	  std::complex<double> z1 = 1i * 1i; // imaginary unit squared
	  std::cout << "i * i = " << z1 << '\n';

	  std::complex<double> z2 = std::pow(1i, 2); // imaginary unit squared
	  std::cout << "pow(i, 2) = " << z2 << '\n';

	  const double PI = std::acos(-1); // or std::numbers::pi in C++20
	  std::complex<double> z3 = std::exp(1i * PI); // Euler's formula
	  std::cout << "exp(i * pi) = " << z3 << '\n';

	  std::complex<double> z4 = 1.0 + 2i, z5 = 1.0 - 2i; // conjugates
	  std::cout << "(1 + 2i) * (1 - 2i) = " << z4 * z5 << '\n';
      }

Output:
      i * i = (-1.0,0.0)
      pow(i, 2) = (-1.0,0.0)
      exp(i * pi) = (-1.0,0.0)
      (1 + 2i) * (1 - 2i) = (5.0,0.0)

	Defect reports

	The following behavior-changing defect	reports  were  applied	retroac-
     tively to
	previously published C++ standards.

	  DR	 Applied to		 Behavior as published		    Cor-
     rect behavior
	LWG 387 C++98	   std::complex was not guaranteed to be	   guar-
     anteed to be
			   compatible with C complex			    com-
     patible

See also
	C documentation for
	Complex number arithmetic

http://cppreference.com 	   2024.06.10			 std::complex(3)
home | help