Pow

Defined in header <cmath>.

Description

Computes the value of base raised to the power exp. The library provides overloads of std::pow for all cv-unqualified floating-point types as the type of the parameters base and exp.

Declarations

C++23

// 1)
/* floating-point-type */ pow( /* floating-point-type */ base,
                               /* floating-point-type */ exp )
// 2)
float powf( float base, float exp );
// 3)
long double powl( long double base, long double exp );

Additional Overloads

// 4)
template< class Arithmetic1, class Arithmetic2 >
/* common-floating-point-type */ pow( Arithmetic1 base, Arithmetic2 exp );

C++11

// 1)
float pow ( float base, float exp );
// 2)
double pow ( double base, double exp );
// 3)
long double pow ( long double base, long double exp );
// 4)
float powf( float base, float exp );
// 5)
long double powl( long double base, long double exp );

Additional Overloads

// 6)
template< class Arithmetic1, class Arithmetic2 >
/* common-floating-point-type */ pow( Arithmetic1 base, Arithmetic2 exp );

C++98

// 1)
float pow ( float base, int exp );
// 2)
double pow ( double base, int exp );
// 3)
long ouble pow ( long double base, int exp );

Parameters

base - base as a floating-point or integer value exp - exponent as a floating-point or integer value

Return value

If no errors occur, base raised to the power of exp (base^exp ), is returned.

If a domain error occurs, an implementation-defined value is returned (NaN where supported).

If a pole error or a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is returned.

If a range error occurs due to underflow, the correct result (after rounding) is returned.

Error handling

Errors are reported as specified in math_errhandling.

If base is finite and negative and exp is finite and non-integer, a domain error occurs and a range error may occur.

If base is zero and exp is zero, a domain error may occur.

If base is zero and exp is negative, a domain error or a pole error may occur.

If the implementation supports IEEE floating-point arithmetic (IEC 60559):

• pow(+0, exp), where exp is a negative odd integer, returns +∞ and raises FE_DIVBYZERO
• pow(-0, exp), where exp is a negative odd integer, returns -∞ and raises FE_DIVBYZERO
• pow(±0, exp), where exp is negative, finite, and is an even integer or a non-integer, returns +∞ and raises FE_DIVBYZERO
• pow(±0, -∞) returns +∞ and may raise FE_DIVBYZERO
• pow(+0, exp), where exp is a positive odd integer, returns +0
• pow(-0, exp), where exp is a positive odd integer, returns -0
• pow(±0, exp), where exp is positive non-integer or a positive even integer, returns +0
• pow(-1, ±∞) returns 1
• pow(+1, exp) returns 1 for any exp, even when exp is NaN
• pow(base, ±0) returns 1 for any base, even when base is NaN
• pow(base, exp) returns NaN and raises FE_INVALID if base is finite and negative and exp is finite and non-integer.
• pow(base, -∞) returns +∞ for any |base|<1
• pow(base, -∞) returns +0 for any |base|>1
• pow(base, +∞) returns +0 for any |base|<1
• pow(base, +∞) returns +∞ for any |base|>1
• pow(-∞, exp) returns -0 if exp is a negative odd integer
• pow(-∞, exp) returns +0 if exp is a negative non-integer or negative even integer
• pow(-∞, exp) returns -∞ if exp is a positive odd integer
• pow(-∞, exp) returns +∞ if exp is a positive non-integer or positive even integer
• pow(+∞, exp) returns +0 for any negative exp
• pow(+∞, exp) returns +∞ for any positive exp
• except where specified above, if any argument is NaN, NaN is returned

Notes

​(C++98) added overloads where exp has type int on top of C pow(), and the return type of std::pow(float, int) was float. However, the additional overloads introduced in C++11 specify that std::pow(float, int) should return double. LWG issue 550 was raised to target this conflict, and the resolution is to removed the extra int exp overloads.

Although std::pow cannot be used to obtain a root of a negative number, std::cbrt is provided for the common case where exp is 1/3.

The additional overloads are not required to be provided exactly as Additional Overloads. They only need to be sufficient to ensure that for their first argument num1 and second argument num2:

If num1 or num2 has type long double, then
std::pow(num1, num2) has the same effect as
​std::pow(static_cast<long double>(num1), static_cast<long double>(num2))

Otherwise, if num1 and/or num2 has type double or an integer type, then
std::pow(num1, num2) has the same effect as
​std::pow(static_cast<double>(num1), static_cast<double>(num2))

​Otherwise, if num1 or num2 has type float, then
std::pow(num1, num2) has the same effect as
​std::pow(static_cast<float>(num1), static_cast<float>(num2))  (do C++23)

If num1 and num2 have arithmetic types, then
std::pow(num1, num2) has the same effect as
std::pow(static_cast</* common-floating-point-type */>(num1), static_cast</* common-floating-point-type */>(num2))

where /* common-floating-point-type */ is the floating-point type with the greatest floating-point conversion rank and greatest floating-point conversion subrank between the types of num1 and num2, arguments of integer type are considered to have the same floating-point conversion rank as double.

If no such floating-point type with the greatest rank and subrank exists, then overload resolution does not result in a usable candidate from the overloads provided.

Examples

#include <cerrno>
#include <cfenv>
#include <cmath>
#include <cstring>
#include <iostream>
 
#pragma STDC FENV_ACCESS ON
 
int main()
{
    // typical usage
    std::cout 
        << "pow(2, 10) = " 
        << std::pow(2, 10) << '\n'
        << "pow(2, 0.5) = " 
        << std::pow(2, 0.5) << '\n'
        << "pow(-2, -3) = " 
        << std::pow(-2, -3) << '\n';
 
    // special values
    std::cout 
        << "pow(-1, NAN) = " 
        << std::pow(-1, NAN) << '\n'
        << "pow(+1, NAN) = " 
        << std::pow(+1, NAN) << '\n'
        << "pow(INFINITY, 2) = " 
        << std::pow(INFINITY, 2) << '\n'
        << "pow(INFINITY, -1) = " 
        << std::pow(INFINITY, -1) << '\n';
 
    // error handling
    errno = 0;
    std::feclearexcept(FE_ALL_EXCEPT);
 
    std::cout 
        << "pow(-1, 1/3) = " 
        << std::pow(-1, 1.0 / 3) << '\n';
    if (errno == EDOM)
        std::cout 
            << "errno == EDOM " 
            << std::strerror(errno) << '\n';
    if (std::fetestexcept(FE_INVALID))
        std::cout 
            << "FE_INVALID raised\n";
 
    std::feclearexcept(FE_ALL_EXCEPT);
 
    std::cout 
        << "pow(-0, -3) = " 
        << std::pow(-0.0, -3) << '\n';
    if (std::fetestexcept(FE_DIVBYZERO))
        std::cout 
            << "FE_DIVBYZERO raised\n";
}

Possible Result

pow(2, 10) = 1024
pow(2, 0.5) = 1.41421
pow(-2, -3) = -0.125
pow(-1, NAN) = nan
pow(+1, NAN) = 1
pow(INFINITY, 2) = inf
pow(INFINITY, -1) = 0
pow(-1, 1/3) = -nan
errno == EDOM Numerical argument out of domain
FE_INVALID raised
pow(-0, -3) = -inf
FE_DIVBYZERO raised