SysTutorials

Linux Manual Pages › Section 3

stdpowstdpowfstdpowl(3)

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

Synopsis

Defined in header <cmath>
float pow ( float base, float exp );
float powf( float base, float exp ); (since C++11)
double pow ( double base, double exp ); (2)
long double pow ( long double base, long double exp );
long double powl( long double base, long double exp ); (1) (since C++11)
float pow ( float base, int iexp ); (3) (4) (until C++11)
double pow ( double base, int iexp ); (5) (until C++11)
long double pow ( long double base, int iexp ); (6) (until C++11)
Promoted pow ( Arithmetic1 base, Arithmetic2 exp ); (7) (since C++11)
1-6) Computes the value of base raised to the power exp or iexp.
7) A set of overloads or a function template for all combinations of arguments of arithmetic type not covered by 1-3). If any argument has integral_type, it is cast to double. If any argument is long double, then the return type Promoted is also long double, otherwise the return type is always double.

Parameters

base – base as a value of floating-point or integral_type
exp – exponent as a value of floating-point or integral_type
iexp – exponent as integer value

Return value

If no errors occur, base raised to the power of exp (or iexp) (baseexp
), 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 even integer
* pow(-∞, exp) returns -∞ if exp is a positive odd integer
* pow(-∞, exp) returns +∞ if exp is a positive non-integer or 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

pow(float, int) returns float until C++11 (per overload 4) but returns double since C++11 (per overload 7)
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

Example

// Run this code

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

Possible output:

  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

sqrt
sqrtf computes square root (
sqrtl √
                   x)
                   (function)
(C++11)
(C++11)
cbrt computes cubic root (
cbrtf 3
cbrtl √
                   x)
(C++11) (function)
(C++11)
(C++11)
hypot computes square root of the sum of the squares of two given numbers (
hypotf √
hypotl x2
                   +y2
(C++11) )
(C++11) (function)
(C++11)
                   complex power, one or both arguments may be a complex number
pow(std::complex) (function template)
                   applies the function std::pow to two valarrays or a valarray and a value
pow(std::valarray) (function template)