std::fma, std::fmaf, std::fmal

来自cppreference.com
< cpp‎ | numeric‎ | math
 
C++
 
数值库
 
常用数学函数
函数
基本运算
(C++11)
(C++11)
fma
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)(C++11)(C++11)
指数函数
(C++11)
(C++11)
(C++11)
(C++11)
幂函数
(C++11)
(C++11)
三角与双曲函数
(C++11)
(C++11)
(C++11)
误差与伽马函数
(C++11)
(C++11)
(C++11)
(C++11)
临近整数的浮点运算
(C++11)(C++11)(C++11)
(C++11)
(C++11)
(C++11)(C++11)(C++11)
浮点操作函数
(C++11)(C++11)
(C++11)
(C++11)
(C++11)(C++11)
(C++11)
分类/比较
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
宏常量
(C++11)(C++11)(C++11)(C++11)(C++11)
 
在标头 <cmath> 定义
(1)
float       fma ( float x, float y, float z );

double      fma ( double x, double y, double z );

long double fma ( long double x, long double y, long double z );
 (C++11 起)
(C++23 前)
constexpr /* 浮点类型 */
            fma ( /* 浮点类型 */ x, /* 浮点类型 */ y, /* 浮点类型 */ z );
 (C++23 起)
float       fmaf( float x, float y, float z );
 (2) (C++11 起)
(C++23 起 constexpr)
long double fmal( long double x, long double y, long double z );
 (3) (C++11 起)
(C++23 起 constexpr)
#define FP_FAST_FMA  /* 由实现定义 */
 (4) (C++11 起)
#define FP_FAST_FMAF /* 由实现定义 */
 (5) (C++11 起)
#define FP_FAST_FMAL /* 由实现定义 */
 (6) (C++11 起)
在标头 <cmath> 定义
template< class Arithmetic1, class Arithmetic2, class Arithmetic3 >
/* 公共浮点类型 */ fma( Arithmetic1 x, Arithmetic2 y, Arithmetic3 z );
 (A) (C++11 起)
(C++23 起 constexpr)
1-3) 如同用无限精度计算 x * y + z，并且只会舍入一次到结果类型。标准库提供所有以无 cv 限定的浮点类型作为参数 x、y 和 z 的类型的 std::fma 重载。 (C++23 起)
4-6) 如果定义了宏常量 FP_FAST_FMAF、FP_FAST_FMA 或 FP_FAST_FMAL，那么函数 std::fma 分别（在精度更高的基础上）求值快于 float、double 和 long double 参数的表达式 x * y + z。这些宏在有定义时求值为整数 1。
A) 为算术类型的所有其他组合提供额外重载。

参数

x, y, z - 浮点或整数值

返回值

在成功时返回 x * y + z 的值，如同计算为无限精度再舍入一次以适合目标类型（或者说是作为单次三元浮点运算计算）。

如果出现上溢导致的值域错误，那么返回 ±HUGE_VAL、±HUGE_VALF 或 ±HUGE_VALL。

如果出现下溢导致的值域错误，那么返回（舍入后的）正确结果。

错误处理

报告 math_errhandling 中指定的错误。

如果实现支持 IEEE 浮点算术（IEC 60559），那么

  • 如果 x 为零而 y 是无穷大或 x 是无穷大而 y 为零，那么
    • 如果 z 非 NaN，那么返回 NaN 并引发 FE_INVALID
    • 如果 z 是 NaN，那么返回 NaN 并可能引发 FE_INVALID
  • 如果 x * y 是准确的无穷大且 z 是带相反符号的无穷大，那么返回 NaN 并引发 FE_INVALID
  • 如果 x 或 y 是 NaN，那么返回 NaN
  • 如果 z 是 NaN，且 x * y 不是 0*Inf 或 Inf*0，那么返回 NaN（而不引发 FE_INVALID）

注解

此运算经常在硬件中实现为融合乘加 CPU 指令。如果硬件支持，那么期待定义相应的 FP_FAST_FMA? 宏，但多数实现即使在不定义这些宏时也利用该 CPU 指令。

POSIX 另外指定被指定为返回 FE_INVALID 的情形是定义域错误。

由于 std::fma 无限的中间精度，它是其他正确舍入数学运算，如 std::sqrt 或甚至除法（在 CPU 不支持的平台上，例如 Itanium）的常用构建块。

同所有浮点表达式，表达式 x * y + z 可编译为融合乘加，除非 #pragma STDC FP_CONTRACT 是关闭状态。

额外重载不需要以 (A) 的形式提供。它们只需要能够对它们的第一个实参 num1，第二个实参 num2 和第三个实参 num3 满足以下要求：

  • 如果 num1，num2 或 num3 具有 long double 类型，那么 std::fma(num1, num2, num3) 和 std::fma(static_cast<long double>(num1),
             static_cast<long double>(num2),
             static_cast<long double>(num3))     的效果相同。
  • 否则，如果 num1，num2 和/或 num3 具有 double 或整数类型，那么 std::fma(num1, num2, num3) 和 std::fma(static_cast<double>(num1),
             static_cast<double>(num2),
             static_cast<double>(num3))     的效果相同。
  • 否则，如果 num1，num2 或 num3 具有 float 类型，那么 std::fma(num1, num2, num3) 和 std::fma(static_cast<float>(num1),
             static_cast<float>(num2),
             static_cast<float>(num3))     的效果相同。
(C++23 前)

如果 num1，num2 和 num3 具有算术类型，那么 std::fma(num1, num2, num3) 和 std::fma(static_cast</* 公共浮点类型 */>(num1),
         static_cast</* 公共浮点类型 */>(num2),
         static_cast</* 公共浮点类型 */>(num3)) 的效果相同，其中 /* 公共浮点类型 */ 是 num1，num2 和 num3 的类型中浮点转换等级和浮点转换子等级最高的浮点类型，整数类型的实参被视为具有与 double 相等的浮点转换等级。

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

(C++23 起)

示例

运行此代码
#include <cfenv>
#include <cmath>
#include <iomanip>
#include <iostream>
 
#ifndef __GNUC__
#pragma STDC FENV_ACCESS ON
#endif
 
int main()
{
    // 演示 fma 与内建运算符间的差别
    double in = 0.1;
    std::cout << "0.1 double 是 " << std::setprecision(23) << in
              << "（" << std::hexfloat << in << std::defaultfloat << "）\n"
              << "0.1*10 是 1.0000000000000000555112（0x8.0000000000002p-3），"
              << "或在舍入到 double 后是 1.0\n";
 
    double expr_result = 0.1 * 10 - 1;
    double fma_result = fma(0.1, 10, -1);
    std::cout << "0.1 * 10 - 1 = " << expr_result
              << "：在中间舍入步骤后减去 1\n"
              << "fma(0.1, 10, -1) = " << std::setprecision(6) << fma_result << "（"
              << std::hexfloat << fma_result << std::defaultfloat << "）\n\n";
 
    // fma 用于 double-double 算术
    double high = 0.1 * 10;
    double low = fma(0.1, 10, -high);
    std::cout << "在 double-double 算术中，0.1 * 10 可以表示为 "
              << high << " + " << low << "\n\n";
 
    // 错误处理
    std::feclearexcept(FE_ALL_EXCEPT);
    std::cout << "fma(+Inf, 10, -Inf) = " << std::fma(INFINITY, 10, -INFINITY) << '\n';
    if (std::fetestexcept(FE_INVALID))
        std::cout << "    发生 FE_INVALID\n";
}

可能的输出： 

0.1 double 是 0.10000000000000000555112（0x1.999999999999ap-4）
0.1*10 是 1.0000000000000000555112（0x8.0000000000002p-3），或在舍入到 double 后是 1.0
0.1 * 10 - 1 = 0：在中间舍入步骤后减去 1
fma(0.1, 10, -1) = 5.55112e-17（0x1p-54）
 
在 double-double 算术中，0.1 * 10 可以表示为 1 + 5.55112e-17
 
fma(+Inf, 10, -Inf) = -nan
    发生 FE_INVALID

参阅

(C++11)(C++11)(C++11)
 除法运算的有符号余数
(函数)
(C++11)(C++11)(C++11)
 除法运算的有符号余数和最后三个二进制位
(函数)
来自“https://zh.cppreference.com/mwiki/index.php?title=cpp/numeric/math/fma&oldid=77048”