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-pointtypes as the type of the parameters `base`

and `exp`

.

### Declarations

- C++23
- C++11
- C++98

`// 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 );

### 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 overloadsintroduced 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 removedthe 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 firstargument `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))`

(until 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 greatestfloating-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