std::pow, std::powf, std::powl

Parameters

Return value

If no errors occur, base raised to the power of exp (baseexp

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

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
• pow(-0, exp), where exp
• pow(±0, exp), where exp
• pow(-1, ±∞) returns 1.
• pow(+1, exp) returns 1 for any exp, even when exp
• pow(base, ±0) returns 1 for any base, even when base
• pow(base, exp) returns NaN and raises FE_INVALID if base is finite and negative and exp
• 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
• pow(-∞, exp) returns +0 if exp
• pow(-∞, exp) returns -∞ if exp
• pow(-∞, exp) returns +∞ if exp
• 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

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

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

Example

#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";
}

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

See also