Namespaces
Variants
Views
Actions

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

From cppreference.com
< cpp‎ | numeric‎ | complex
m (Text replace - "{{cpp|" to "{{c|")
m (Minor fix.)
 
(24 intermediate revisions by 10 users not shown)
Line 1: Line 1:
−
{{cpp/title|pow{{small|(std::complex)}}}}
+
{{cpp/title|pow{{petty|(std::complex)}}}}
−
{{cpp/numeric/complex/sidebar}}
+
{{cpp/numeric/complex/navbar}}
−
{{ddcl list begin}}
+
{{dcl begin}}
−
{{ddcl list header | complex}}
+
{{dcl header|complex}}
−
{{ddcl list item | 1=
+
{{dcl|num=1|until=c++11|1=
−
template< class T >  
+
template< class T >
−
complex<T> pow( const complex<T>& base, const complex<T>& exp );
+
std::complex<T> pow( const std::complex<T>& x, int y );
 
}}
 
}}
−
{{ddcl list item | 1=
+
{{dcl|num=2|1=
−
template< class T >  
+
template< class T >
−
complex<T> pow( const complex<T>& base, const T& exp );
+
std::complex<T> pow( const std::complex<T>& x, const std::complex<T>& y );
 
}}
 
}}
−
{{ddcl list item | 1=
+
{{dcl|num=3|1=
−
template< class T >  
+
template< class T >
−
complex<T> pow( const T& base, const complex<T>& exp );
+
std::complex<T> pow( const std::complex<T>& x, const T& y );
 
}}
 
}}
−
{{ddcl list end}}
+
{{dcl|num=4|1=
 +
template< class T >
 +
std::complex<T> pow( const T& x, const std::complex<T>& y );
 +
}}
 +
{{dcl h|[[#Notes|Additional overloads]] {{mark since c++11}}}}
 +
{{dcl header|complex}}
 +
{{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 rev multi|num=B|dcl1=
 +
template< class T, class NonComplex >
 +
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 rev multi|num=C|dcl1=
 +
template< class T, class NonComplex >
 +
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}}
  
−
Computes complex {{tt|base}} raised to a complex power {{tt|exp}}. The operation is defined as {{math|exp(''base'' &middot; log(''exp'')}}. A branch cut exists along the negative real axis.
+
@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.
  
−
The result of {{c|pow(0, 0)}} is implementation-defined.
+
{{rrev|since=c++11|
 +
@A-C@ Additional overloads are provided. {{tt|NonComplex}} is not a specialization of {{lc|std::complex}}.
 +
}}
  
 
===Parameters===
 
===Parameters===
−
{{param list begin}}
+
{{par begin}}
−
{{param list item | base | base as a complex value}}
+
{{par|x|base}}
−
{{param list item | exp | exponent as a complex value}}
+
{{par|y|exponent}}
−
{{param list end}}
+
{{par end}}
  
 
===Return value===
 
===Return value===
 +
@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}}.
  
−
{{tt|base}} raised to a power {{tt|exp}}.
+
===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 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 <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)
 +
}}
  
 
===See also===
 
===See also===
−
{{dcl list begin}}
+
{{dsc begin}}
−
{{dcl list template | cpp/numeric/complex/dcl list exp}}
+
{{dsc inc|cpp/numeric/complex/dsc sqrt}}
−
{{dcl list end}}
+
{{dsc inc|cpp/numeric/math/dsc pow}}
 +
{{dsc inc|cpp/numeric/valarray/dsc pow}}
 +
{{dsc see c|c/numeric/complex/cpow}}
 +
{{dsc end}}
 +
 
 +
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Latest revision as of 00:50, 29 May 2023

 
C++
 
Numerics library
Common mathematical functions
Mathematical special functions (C++17)
Mathematical constants (C++20)
Basic linear algebra algorithms (C++26)
Floating-point environment (C++11)
Complex numbers
Numeric array (valarray)
Pseudo-random number generation
Factor operations
(C++17)
(C++17)
Interpolations
(C++20)
(C++20)
Saturation arithmetic
(C++26)
(C++26)
(C++26)
(C++26)
(C++26)

Generic numeric operations
Bit operations
(C++20)    
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++23)
(C++20)
 
std::complex
 
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)

Contents

[edit] Parameters

x - base
y - exponent

[edit] Return value

1-4) If no errors occur, the complex power xy, is returned.
Errors and special cases are handled as if the operation is implemented by std::exp(y * std::log(x)).
The result of std::pow(0, 0) is implementation-defined.
A-C) Same as (2-4).

[edit] Notes

Overload (1) was provided in C++98 to match the extra overloads (2) of std::pow. Those overloads were removed by the resolution of LWG issue 550, and overload (1) was removed by the resolution of LWG issue 844.

The additional overloads are not required to be provided exactly as (A-C). They only need to be sufficient to ensure that for their first argument base and second argument exponent:

If base and/or exponent has type std::complex<T>:

  • 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

 complex square root in the range of the right half-plane
(function template) [edit]
(C++11)(C++11)
 raises a number to the given power (xy)
(function) [edit]
applies the function std::pow to two valarrays or a valarray and a value
(function template) [edit]
C documentation for cpow
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/numeric/complex/pow&oldid=152476"