Pow

定义于头文件 <cmath> 中。

描述

计算 `base` 的 `exp` 次幂的值。该库为所有 cv-unqualified 浮点类型（作为 `base` 和 `exp` 参数的类型）提供了 `std::pow` 的重载。

声明

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

附加重载

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

附加重载

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

参数

base - 浮点或整数值作为底数 exp - 浮点或整数值作为指数

返回值

如果没有错误发生，则返回 `base` 的 `exp` 次幂 (base^exp)。

如果发生域错误，则返回实现定义的值（如果支持，返回 NaN）。

如果发生由于溢出的极点错误或范围错误，则返回 ±HUGE_VAL、±HUGE_VALF 或 ±HUGE_VALL。

如果因下溢导致范围错误，则返回正确结果（舍入后）。

错误处理

错误按 math_errhandling 中指定的方式报告。

如果 base 是有限的负数，且 exp 是有限的非整数，则会发生域错误，并且可能会发生范围错误。

如果 base 为零且 exp 为零，则可能会发生域错误。

如果 base 为零且 exp 为负数，则可能会发生域错误或极点错误。

如果实现支持 IEEE 浮点运算（IEC 60559）

• pow(+0, exp)，其中 exp 是负奇数整数，返回 +∞ 并引发 FE_DIVBYZERO
• pow(-0, exp)，其中 exp 是负奇数整数，返回 -∞ 并引发 FE_DIVBYZERO
• pow(±0, exp)，其中 exp 是负数、有限，并且是偶数整数或非整数，返回 +∞ 并引发 FE_DIVBYZERO
• pow(±0, -∞) 返回 +∞ 并可能引发 FE_DIVBYZERO
• pow(+0, exp)，其中 exp 是正奇数整数，返回 +0
• pow(-0, exp)，其中 exp 是正奇数整数，返回 -0
• pow(±0, exp)，其中 exp 是正非整数或正偶数整数，返回 +0
• pow(-1, ±∞) 返回 1
• pow(+1, exp) 对于任何 exp 返回 1，即使 exp 是 NaN
• pow(base, ±0) 对于任何 base 返回 1，即使 base 是 NaN
• pow(base, exp) 返回 NaN 并引发 FE_INVALID，如果 base 是有限的负数，且 exp 是有限的非整数。
• pow(base, -∞) 对于任何 |base|<1 返回 +∞
• pow(base, -∞) 对于任何 |base|>1 返回 +0
• pow(base, +∞) 对于任何 |base|<1 返回 +0
• pow(base, +∞) 对于任何 |base|>1 返回 +∞
• pow(-∞, exp) 如果 exp 是负奇数整数，则返回 -0
• pow(-∞, exp) 如果 exp 是负非整数或负偶数整数，则返回 +0
• pow(-∞, exp) 如果 exp 是正奇数整数，则返回 -∞
• pow(-∞, exp) 如果 exp 是正非整数或正偶数整数，则返回 +∞
• pow(+∞, exp) 对于任何负 exp 返回 +0
• pow(+∞, exp) 对于任何正 exp 返回 +∞
• 除非另有说明，如果任何参数是 NaN，则返回 NaN

备注

​(C++98) 在 C 语言的 pow() 基础上添加了 exp 类型为 int 的重载，并且 std::pow(float, int) 的返回类型是 float。然而，C++11 中引入的额外重载规定 std::pow(float, int) 应返回 double。为了解决这个冲突，提出了 LWG issue 550，解决方案是移除额外的 int exp 重载。

尽管 std::pow 不能用于获取负数的根，但对于 exp 为 1/3 的常见情况，提供了 std::cbrt。

不需要严格按照 附加重载 提供附加重载。它们只需要足以确保对于它们的第一个参数 num1 和第二个参数 num2

如果 num1 或 num2 的类型是 long double，则
std::pow(num1, num2) 的效果与
​std::pow(static_cast<long double>(num1), static_cast<long double>(num2))

否则，如果 num1 和/或 num2 的类型是 double 或整数类型，则
std::pow(num1, num2) 的效果与
​std::pow(static_cast<double>(num1), static_cast<double>(num2))

​否则，如果 num1 或 num2 的类型是 float，则
std::pow(num1, num2) 的效果与
​std::pow(static_cast<float>(num1), static_cast<float>(num2))  (直到 C++23)

如果 num1 和 num2 具有算术类型，则
std::pow(num1, num2) 的效果与
std::pow(static_cast</* common-floating-point-type */>(num1), static_cast</* common-floating-point-type */>(num2))

其中 /* common-floating-point-type */ 是 num1 和 num2 的类型之间浮点转换等级和浮点转换次等级最高的浮点类型，整数类型的参数被认为具有与 double 相同的浮点转换等级。

如果不存在具有最高等级和子等级的浮点类型，则重载决议不会从提供的重载中产生可用的候选。

示例

#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