Difference between revisions of "cpp/numeric/complex/pow"

Latest revision as of 00:50, 29 May 2023

Defined in header `<complex>`
template< class T > std::complex<T> pow( const std::complex<T>& x, int y );	(1)	(until C++11)
template< class T > std::complex<T> pow( const std::complex<T>& x, const std::complex<T>& y );	(2)
template< class T > std::complex<T> pow( const std::complex<T>& x, const T& y );	(3)
template< class T > std::complex<T> pow( const T& x, const std::complex<T>& y );	(4)
Additional overloads (since C++11)
Defined in header `<complex>`
	(A)
template< class T1, class T2 > std::complex</* common-type */> pow( const std::complex<T1>& x, const std::complex<T2>& y );			(until C++23)
template< class T1, class T2 > std::complex<std::common_type_t<T1, T2>> pow( const std::complex<T1>& x, const std::complex<T2>& y );			(since C++23)
		(B)
template< class T, class NonComplex > std::complex</* common-type */> pow( const std::complex<T>& x, const NonComplex& y );				(until C++23)
template< class T, class NonComplex > std::complex<std::common_type_t<T, NonComplex>> pow( const std::complex<T>& x, const NonComplex& y );				(since C++23)
			(C)
template< class T, class NonComplex > std::complex</* common-type */> pow( const NonComplex& x, const std::complex<T>& y );					(until C++23)
template< class T, class NonComplex > std::complex<std::common_type_t<T, NonComplex>> pow( const NonComplex& x, const std::complex<T>& y );					(since C++23)

1-4) Computes complex x raised to a complex power y with a branch cut along the negative real axis for the first argument. Non-complex arguments are treated as complex numbers with positive zero imaginary component.

A-C) Additional overloads are provided. NonComplex is not a specialization of std::complex.

(since C++11)

If base and/or exponent has type std::complex<long double> or long double, then std::pow(base, exponent) has the same effect as std::pow(std::complex<long double>(base),
std::complex<long double>(exponent)).
Otherwise, if base and/or exponent has type std::complex<double>, double, or an integer type, then std::pow(base, exponent) has the same effect as std::pow(std::complex<double>(base),
std::complex<double>(exponent)).
Otherwise, if base and/or exponent has type std::complex<float> or float, then std::pow(base, exponent) has the same effect as std::pow(std::complex<float>(base),
std::complex<float>(exponent)).

(until C++23)

If one argument has type std::complex<T1> and the other argument has type T2 or std::complex<T2>, then std::pow(base, exponent) has the same effect as std::pow(std::complex<std::common_type_t<T1, T2>>(base),
std::complex<std::common_type_t<T1, T2>>(exponent)).

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

(since C++23)

[edit] Example

Run this code

#include <complex>
#include <iostream>
 
int main()
{
    std::cout << std::fixed;
 
    std::complex<double> z(1.0, 2.0);
    std::cout << "(1,2)^2 = " << std::pow(z, 2) << '\n';
 
    std::complex<double> z2(-1.0, 0.0); // square root of -1
    std::cout << "-1^0.5 = " << std::pow(z2, 0.5) << '\n';
 
    std::complex<double> z3(-1.0, -0.0); // other side of the cut
    std::cout << "(-1,-0)^0.5 = " << std::pow(z3, 0.5) << '\n';
 
    std::complex<double> i(0.0, 1.0); // i^i = exp(-pi / 2)
    std::cout << "i^i = " << std::pow(i, i) << '\n';
}

Output:

(1,2)^2 = (-3.000000,4.000000)
-1^0.5 = (0.000000,1.000000)
(-1,-0)^0.5 = (0.000000,-1.000000)
i^i = (0.207880,0.000000)

[edit] See also

sqrt(std::complex)	complex square root in the range of the right half-plane (function template) [edit]
powpowfpowl (C++11)(C++11)	raises a number to the given power ($\small{x^y}$ $x y$ ) (function) [edit]
pow(std::valarray)	applies the function std::pow to two valarrays or a valarray and a value (function template) [edit]
C documentation for cpow

@@ Line 1: / Line 1: @@
-{{cpp/title|pow<small>std::complex)</small>}}
+{{cpp/title|pow{{petty|(std::complex)}}}}
 {{cpp/numeric/complex/navbar}}
 {{dcl begin}}
-{{dcl header | complex}}
+{{dcl header|complex}}
-{{dcl | num = 1 | 1=
+{{dcl|num=1|until=c++11|1=
+template< class T >
+std::complex<T> pow( const std::complex<T>& x, int y );
+}}
+{{dcl|num=2|1=
 template< class T >
 std::complex<T> pow( const std::complex<T>& x, const std::complex<T>& y );
 }}
-{{dcl | num = 2 | 1=
+{{dcl|num=3|1=
 template< class T >
-std::complex<T> pow( std::const complex<T>& x, const T& y );
+std::complex<T> pow( const std::complex<T>& x, const T& y );
 }}
-{{dcl | num = 3 | 1=
+{{dcl|num=4|1=
 template< class T >
 std::complex<T> pow( const T& x, const std::complex<T>& y );
 }}
-{{dcl | num = 4 | since=c++11 | 1=
+{{dcl h|[[#Notes|Additional overloads]] {{mark since c++11}}}}
-template< class T, class U >
+{{dcl header|complex}}
-std::complex</*Promoted*/> pow( const std::complex<T>& x, const std::complex<U>& y );
+{{dcl rev multi|num=A|dcl1=
+template< class T1, class T2 >
+std::complex</* common-type */>
+    pow( const std::complex<T1>& x, const std::complex<T2>& y );
+|since2=c++23|dcl2=
+template< class T1, class T2 >
+std::complex<std::common_type_t<T1, T2>>
+    pow( const std::complex<T1>& x, const std::complex<T2>& y );
 }}
-{{dcl | num = 5 | since=c++11 | 1=
+{{dcl rev multi|num=B|dcl1=
-template< class T, class U >
+template< class T, class NonComplex >
-std::complex</*Promoted*/> pow( const std::complex<T>& x, const U& y );
+std::complex</* common-type */>
+    pow( const std::complex<T>& x, const NonComplex& y );
+|since2=c++23|dcl2=
+template< class T, class NonComplex >
+std::complex<std::common_type_t<T, NonComplex>>
+    pow( const std::complex<T>& x, const NonComplex& y );
 }}
-{{dcl | num = 6 | since=c++11 | 1=
+{{dcl rev multi|num=C|dcl1=
-template< class T, class U >
+template< class T, class NonComplex >
-std::complex</*Promoted*/> pow( const T& x, const std::complex<U>& y );
+std::complex</* common-type */>
+    pow( const NonComplex& x, const std::complex<T>& y );
+|since2=c++23|dcl2=
+template< class T, class NonComplex >
+std::complex<std::common_type_t<T, NonComplex>>
+    pow( const NonComplex& x, const std::complex<T>& y );
 }}
 {{dcl end}}
-@1-3@ Computes complex {{tt|x}} raised to a complex power {{tt|y}} with a branch cut along the negative real axis for the first argument.
+@1-4@ Computes complex {{c|x}} raised to a complex power {{c|y}} with a branch cut along the negative real axis for the first argument. Non-complex arguments are treated as complex numbers with positive zero imaginary component.
 {{rrev|since=c++11|
-@4-6@ Additional overloads are provided for all arithmetic types, such that
+@A-C@ Additional overloads are provided. {{tt|NonComplex}} is not a specialization of {{lc|std::complex}}.
-:1. If either argument is {{c|long double}} or {{c|std::complex<long double>}}, then both arguments are cast to {{c|std::complex<long double>}}
-:2. Otherwise, if either argument is {{c|double}}, {{c|std::complex<double>}} or integer type, then both arguments are cast to {{c|std::complex<double>}}
-:3. Otherwise, if either argument is {{c|float}} or {{c|std::complex<float>}}, then both arguments are cast to {{c|std::complex<float>}}
 }}
 ===Parameters===
 {{par begin}}
-{{par | x | base as a complex value}}
+{{par|x|base}}
-{{par | y | exponent as a complex value}}
+{{par|y|exponent}}
 {{par end}}
 ===Return value===
-If no errors occur, the complex power {{math|x{{su|p=y}}}}, is returned.
+@1-4@ If no errors occur, the complex power {{math|x{{su|p=y}}}}, is returned.
+@@ Errors and special cases are handled as if the operation is implemented by {{c|std::exp(y * std::log(x))}}.
+@@ The result of {{c|std::pow(0, 0)}} is implementation-defined.
+@A-C@ Same as {{v|2-4}}.
-Errors and special cases are handled as if the operation is implemented by {{c|std::exp(y*std::log(x))}}
+===Notes===
+Overload {{v|1}} was provided in C++98 to match the extra overloads {{v|2}} of {{lc|std::pow}}. Those overloads were removed by the resolution of {{lwg|550}}, and overload {{v|1}} was removed by the resolution of {{lwg|844}}.
-The result of {{c|std::pow(0, 0)}} is implementation-defined.
+The additional overloads are not required to be provided exactly as {{v|A-C}}. They only need to be sufficient to ensure that for their first argument {{c|base}} and second argument {{c|exponent}}:
+{{rev begin}}
+{{rev|until=c++23|
+If {{c|base}} and/or {{c|exponent}} has type {{c/core|std::complex<T>}}:
+* If {{c|base}} and/or {{c|exponent}} has type {{c/core|std::complex<long double>}} or {{c/core|long double}}, then {{box|{{tt|std::pow(base, exponent)}}}} has the same effect as {{box|{{tt|std::pow}}{{c/core|(std::complex<long double>(base),}}<br>{{c/core|         std::complex<long double>(exponent))}}}}.
+* Otherwise, if {{c|base}} and/or {{c|exponent}} has type {{c/core|std::complex<double>}}, {{c/core|double}}, or an integer type, then {{box|{{tt|std::pow(base, exponent)}}}} has the same effect as {{box|{{tt|std::pow}}{{c/core|(std::complex<double>(base),}}<br>{{c/core|         std::complex<double>(exponent))}}}}.
+* Otherwise, if {{c|base}} and/or {{c|exponent}} has type {{c/core|std::complex<float>}} or {{c/core|float}}, then {{box|{{tt|std::pow(base, exponent)}}}} has the same effect as {{box|{{tt|std::pow}}{{c/core|(std::complex<float>(base),}}<br>{{c/core|         std::complex<float>(exponent))}}}}.
+}}
+{{rev|since=c++23|
+If one argument has type {{c/core|std::complex<T1>}} and the other argument has type {{tt|T2}} or {{c/core|std::complex<T2>}}, then {{box|{{tt|std::pow(base, exponent)}}}} has the same effect as {{box|{{tt|std::pow}}{{c/core|(std::complex<std::common_type_t<T1, T2>>(base),
+         std::complex<std::common_type_t<T1, T2>>(exponent))}}}}.
+If {{c/core|std::common_type_t<T1, T2>}} is not well-formed, then the program is ill-formed.
+}}
+{{rev end}}
 ===Example===
 {{example|
 |code=
-#include <iostream>
 #include <complex>
+#include <iostream>
 int main()
 {
      std::cout << std::fixed;
-     std::complex<double> z(1, 2);
+     std::complex<double> z(1.0, 2.0);
      std::cout << "(1,2)^2 = " << std::pow(z, 2) << '\n';
-     std::complex<double> z2(-1, 0);  // square root of -1
+     std::complex<double> z2(-1.0, 0.0); // square root of -1
      std::cout << "-1^0.5 = " << std::pow(z2, 0.5) << '\n';
-     std::complex<double> z3(-1, -0.0);  // other side of the cut
+     std::complex<double> z3(-1.0, -0.0); // other side of the cut
-     std::cout << "(-1, -0)^0.5 = " << std::pow(z3, 0.5) << '\n';
+     std::cout << "(-1,-0)^0.5 = " << std::pow(z3, 0.5) << '\n';
-     std::complex<double> i(0, 1); // i^i = exp(-pi/2)
+     std::complex<double> i(0.0, 1.0); // i^i = exp(-pi / 2)
      std::cout << "i^i = " << std::pow(i, i) << '\n';
 }
@@ Line 76: / Line 112: @@
 (1,2)^2 = (-3.000000,4.000000)
 -1^0.5 = (0.000000,1.000000)
-(-1, -0)^0.5 = (0.000000,-1.000000)
+(-1,-0)^0.5 = (0.000000,-1.000000)
 i^i = (0.207880,0.000000)
 }}
@@ Line 82: / Line 118: @@
 ===See also===
 {{dsc begin}}
-{{dsc inc | cpp/numeric/complex/dsc sqrt}}
+{{dsc inc|cpp/numeric/complex/dsc sqrt}}
-{{dsc inc | cpp/numeric/math/dsc pow}}
+{{dsc inc|cpp/numeric/math/dsc pow}}
-{{dsc inc | cpp/numeric/valarray/dsc pow}}
+{{dsc inc|cpp/numeric/valarray/dsc pow}}
-{{dsc see c | c/numeric/complex/cpow}}
+{{dsc see c|c/numeric/complex/cpow}}
 {{dsc end}}
 {{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/numeric/complex/pow"

Latest revision as of 00:50, 29 May 2023

Contents

[edit] Parameters

[edit] Return value

[edit] Notes

[edit] Example

[edit] See also

Navigation

Toolbox