cmath

<cmath>ヘッダでは、一般的な数学関数および各種マクロを提供する。

• 標準Cライブラリとの差異
• エラーの扱い
• エラーの種類
• 三角関数
• 双曲線関数
• 指数関数と対数関数
• 仮数と指数
• 累乗・冪根と絶対値
• 誤差関数とガンマ関数
• その他特殊関数
• 最近傍整数
• 剰余
• 浮動小数点操作
• 最大値・最小値と正の差
• 乗算・加算
• 線形補間
• 数値分類
• NaNの扱い
• 数値比較
• 型
• 数値のマクロ
• 数値分類のマクロ
• その他のマクロ

フリースタンディング

このヘッダの一部の機能が、フリースタンディング処理系でも使用できる。どの機能が使用できるかは各機能のページを参照。

標準Cライブラリとの差異

<cmath>は基本的には、標準 C ライブラリの <math.h> に準拠しているが、いくつかの変更点がある。

C++98のC90との差異

• 各関数は std 名前空間に定義されている。
• fabs と等価の関数 abs を追加している。
• pow の第 2 引数が int のオーバーロードを追加している。
• 各関数（上記 2 関数を含む）に対して、引数および戻り値の double に対応する箇所が float および long double になっているオーバーロードバージョンを追加している。

C++11のC99との差異

• 各関数は std 名前空間に定義されている。
• fabs と等価の関数 abs を追加している。
• 引数に double を含む各関数（上記 abs を含む）に対して、引数および戻り値の double に対応する箇所が float と long double のオーバーロードバージョンを追加している。
  なお、C99 にも同様の関数（接尾辞が f および l のもの）が存在するが、それらについては規格書では言及されていない。
  ただし、nan については、引数の型では区別がつかないため、C99 の nanf および nanl をそのまま使用する。
• 数値分類、および、数値比較の各マクロの替わりに、引数が各浮動小数点型で、戻り値が bool の関数を追加している。

• 上記に加えて、以下のようなオーバーロード解決ができるように、更にオーバーロードを追加している。

  1. double 型の仮引数に対応する実引数のいずれかが long double である場合、double 型の仮引数に対応する全ての実引数を long double にキャストしてからオーバーロード解決を行う。
  2. 上記以外で、double 型の仮引数に対応する実引数のいずれかが double 型または整数型である場合、double 型の仮引数に対応する全ての実引数を double にキャストしてからオーバーロード解決を行う。
  3. 上記以外の場合、double 型の仮引数に対応する全ての実引数を float にキャストしてからオーバーロード解決を行う。

  これらの規則は、C99 で導入された <tgmath.h> の type-generic マクロとほぼ等価であるが、以下の点が異なる。

  • C99 では modf は type-generic マクロの対象ではないが、C++11 ではオーバーロード解決の対象である。
  • C99 では列挙型も整数型とみなされるが、C++11 では列挙型は（スコープ付き・スコープ無し共に）整数型とはみなされない。
  • C++ のクラス型は変換演算子を持つことができるため、実引数の型が変換演算子を持つクラス型の場合も上記に従ってオーバーロード解決が行われる。

  しかし、上記のオーバーロード解決の規則に厳密に従うと、列挙型や変換演算子を持つクラス型の引数が float と等価の扱いになってしまう。
  このため、上記に記載のある無条件の「キャスト」は、C++14 ではその対象が「算術型」のみに限られることになり、列挙型や変換演算子を持つクラス型は上記の「キャスト」の対象とはならなくなった。
  （もちろん、オーバーロード解決の後の暗黙の変換は依然として有効であるため、スコープ無し列挙型や explicit でない変換演算子を持つクラス型は、明示的なキャスト無しで実引数になり得る。）
  なお、C++11 の記載にある無条件のキャストは規格のバグとされたため、C++11 であってもスコープ付き列挙型や explicit な変換演算子のあるクラス型に、上記規則にある無条件のキャストが適用されると想定すべきではない。
  （LWG 2086. Overly generic type support for math functions 参照）

  各関数の個別ページでは、上記のオーバーロード関数をコードで示す際には、引数や戻り値の型を斜体で示す。

  Integral      // 任意の整数型
  Arithmetic    // 任意の算術型
  Promoted      // 決定された戻り値型
  

  複数の引数がある場合には、数字のサフィックスで区別する。 例を以下に示す。

  double atan(Integral x);
  
  Promoted atan2(Arithmetic1 y, Arithmetic2 x);
  

C++23での差異

constexpr対応

C++23では、多くの数学関数がconstexprに対応し、定数式内で使用できるようになった。C++23時点では、コンパイラベンダの負担が少ない機能をconstexpr対応した。

C++23でconstexpr対応する関数の条件は以下：

1. 有理数の集合、または実数のどこにも密でない部分集合に作用すると見なされ、関数が閉じていること
2. 関数が丸めモードに強く依存しないこと

exp()、log()、sqrt()、cos()、sin()は1. の条件を満たさないため、C++23ではconstexprに対応しない。

nearbyint()は2. の条件を満たさないため、C++23ではconstexprに対応しない。

ただし、コンパイラが先行してconstexpr非対応の関数も対応している可能性がある。

なお、C++20ではlerp()のみconstexprに対応している。これはC標準ライブラリからの移植ではなく、C++で標準化された関数だからである (errnoや浮動小数点例外のようなグローバル状態を使用しない)。

拡張浮動小数点数型への対応

C++23では<stdfloat>に拡張浮動小数点数型が追加された。その対応として、以下のようなfloat、double、long doubleに対するオーバーロードは、

float abs(float x);
double abs(double x);
long double abs(long double x);

以下のようにfloating-point-typeへのオーバーロードに統合され、拡張浮動小数点数型も扱えるようになった。

floating-point-type abs(floating-point-type x);

エラーの扱い

<cmath> で提供される各関数は、特に明記されていない限り、引数の型が表現できる全ての値についての挙動が定義されている。 なお、ここで言う「挙動が定義されている」とは、未定義動作を引き起こさないというだけで、エラーが発生したり、実装依存の挙動となる場合がある事に注意。

<cmath> で提供される各関数においてエラーが発生した場合、errno、あるいは、浮動小数点例外のいずれか、もしくは両方によってエラーが通知される。
C++11 以降の場合、どちらの方法によって通知されるかは math_errhandling の値によって判別可能である。（利用者が選択する事はできない）
C++98 までの場合、errno でしか通知されない。

errno によるエラーの通知

errno によってエラーが通知される場合、エラー内容は errno に設定された値によって判別可能である。
なお、エラーが発生しなかった場合でも errno がクリアされる事は無いので、エラー発生の有無を errno で判断するためにはあらかじめ errno にゼロを設定しておく必要がある。

浮動小数点例外によるエラーの通知（C++11 以降）

名称に「例外」と付いているが、C++ の例外とは全く関係ないため注意。
浮動小数点例外によってエラーが通知される場合、エラー内容は浮動小数点状態フラグに設定されるため、fetestexcept によって判別可能である。
なお、エラーが発生しなかった場合でも浮動小数点状態フラグがクリアされる事は無いので、エラー発生の有無を浮動小数点状態フラグで判断するためにはあらかじめ feclearexcept で浮動小数点状態フラグをクリアしておく必要がある。

エラーの種類

<cmath> で提供される各関数で発生するエラーは、以下の 5 種類ある。

定義域エラー（domain error）

引数の値が、関数の数学的な定義域の範囲外であることを示すエラー。（例：sqrt(-1.0) や、asin(2.0) 等）

定義域エラーが発生しなければならない条件は関数毎に規格で規定されているが、数学的な定義と整合的である場合には追加の条件で定義域エラーが発生する事が処理系に許されている。

定義域エラーが発生した場合、通知は以下のように行われる。

• errno によってエラーが通知される場合、EDOM（定義域エラー、Error DOMain）が設定される。
• 浮動小数点例外によってエラーが通知される場合、FE_INVALID（無効演算浮動小数点例外）が設定される。

定義域エラーが発生した場合、関数の戻り値は処理系定義であるが、戻り値の型が quiet NaN（quiet Not a Number：静かな非数）を表現可能（std::numeric_limits<T>::has_quiet_NaN が真）の場合、一般的には quiet NaN が返る。

極エラー（pole error）

引数の値が有限値である場合に、関数の当該値に対する数学的な極限値が無限大であることを示すエラー。（例：log(0.0) や、atanh(1.0) 等）
引数の値が無限大の場合には、極エラーではないので注意。

極エラーが発生しなければならない条件は関数毎に規格で規定されているが、数学的な定義と整合的である場合には追加の条件で極エラーが発生する事が処理系に許されている。

極エラーが発生した場合、通知は以下のように行われる。

• errno によってエラーが通知される場合、ERANGE（値域エラー、Error RANGE）が設定される。
• 浮動小数点例外によってエラーが通知される場合、FE_DIVBYZERO（ゼロ除算浮動小数点例外）が設定される（注：「ゼロ除算浮動小数点例外」は誤記では無い）。

極エラーが発生した場合、関数の戻り値は処理系定義であるが、戻り値の型が浮動小数点数の場合、一般的には HUGE_VAL（double）、HUGE_VALF（float 、C++11 以降のみ）、HUGE_VALL（long double、C++11 以降のみ）に正しい符号を付加した値が返る。 また、戻り値の型が無限大を表現可能（std::numeric_limits<T>::has_infinity が真）の場合、一般的には無限大（std::numeric_limits<T>::infinity()）が返る。 なお、マクロ INFINITY も、定義されている場合には無限大を表すものではあるが、float 型であることに注意。

オーバーフローエラー（overflow error）

戻り値が有限だが大きすぎるため、余分な丸め誤差無しでは戻り値の型で表す事が出来ないことを示すエラー。

オーバーフローエラーが発生した場合、通知は以下のように行われる。

• errno によってエラーが通知される場合、ERANGE（値域エラー、Error RANGE）が設定される。
• 浮動小数点例外によってエラーが通知される場合、FE_OVERFLOW（オーバーフロー浮動小数点例外）が設定される。

オーバーフローエラーが発生した場合、戻り値の型が浮動小数点型でデフォルトの丸めモードが有効であれば、HUGE_VAL（double）、HUGE_VALF（float 、C++11 以降のみ）、HUGE_VALL（long double、C++11 以降のみ）に正しい符号を付加した値が返る。

アンダーフローエラー（underflow error）

戻り値の絶対値が小さすぎるため、余分な丸め誤差無しでは戻り値の型で表す事が出来ないことを示すエラー。

アンダーフローエラーが発生した場合でも処理系によってはエラーの通知が行われないが（規格でエラーの通知が任意となっているため）、通知される場合には以下のように行われる。

• errno によってエラーが通知される場合、ERANGE（値域エラー、Error RANGE）が設定される。
• 浮動小数点例外によってエラーが通知される場合、FE_UNDERFLOW（アンダーフロー浮動小数点例外）が設定される。

アンダーフローエラーが発生した場合、関数の戻り値は処理系定義であるが、戻り値の絶対値はその型における最小の正の正規化数（std::numeric_limits<T>::min()）以下である。（非正規化数、あるいは、ゼロを含む）

不正確エラー（inexact error）

戻り値が戻り値の型では正確に表す事が出来ないことを示すエラー。（例：exp(1.0) や、sqrt(2.0) 等）
浮動小数点演算ではほとんどの場合に発生する。

不正確エラーが発生した場合でも処理系によってはエラーの通知が行われないが（規格でエラーの通知が任意となっているため）、通知される場合には以下のように行われる。

• errno によるエラーの通知は行われない。
• 浮動小数点例外によってエラーが通知される場合、FE_INEXACT（不正確浮動小数点例外）が設定される。

不正確エラーが発生した場合、関数の戻り値は真の値を丸めた値となるが、その際の丸め方式は処理系定義である。（関数に特別に規定がある場合を除く）
特に、fesetround で設定した丸め方式に従うとは限らないため、注意が必要である。

定数式になる条件

constexpr対応する数学関数において、以下のいずれかの条件に合致する場合、定数式とならない (引数によってコンパイルエラーになる)

• FE_INEXACT以外の、以下の浮動小数点例外が発生した場合：
  • FE_DIVBYZERO (ゼロ除算)
  • FE_INVALID (不正な演算)
  • FE_OVERFLOW (オーバーフロー)
  • FE_UNDERFLOW (アンダーフロー)
• math_errhandling & MATH_ERRNOが真で、errnoが設定された場合

NaN の扱い

浮動小数点規格ISO/IEC 60559 (IEEE 754) に準拠する環境では、C言語規格の Annex F (F.10 paragraph 11) により、以下の一般規則が定められている：

NaN の引数をもつ関数は、NaN の結果を返し、浮動小数点例外を発生させない。ただし、個別に規定がある場合を除く。

この規則は __STDC_IEC_559__ が定義されている（ISO/IEC 60559 に準拠する）環境で適用される。

また、推奨される実装として、ひとつ以上の NaN 引数をもつ関数が NaN を返す場合、その結果は入力の NaN 引数のいずれかと同じ値（型変換後、符号は異なる可能性がある）であることが望ましいとされている。

例外となる関数

以下の関数は、NaN の引数を受け取っても NaN を返さない場合がある：

pow と hypot の例外は、NaN をどのような実数値に置き換えても結果が同じになるという原則に基づいている（任意の実数の 0 乗は 1、任意の実数と無限大の hypot は無限大）。

fmax と fmin は、NaN を欠損値として扱い、有効な数値を優先して返す。ただし、両方の引数が NaN の場合は NaN を返す。

なお、数値分類関数（fpclassify、isnan、isinf 等）は戻り値が整数型であるため、NaN の伝播規則の対象外である。

三角関数

双曲線関数

指数関数と対数関数

仮数と指数

累乗・冪根と絶対値

誤差関数とガンマ関数

その他特殊関数

以下の関数は引数に NaN が渡された場合、 NaN を返さなければならないが定義域エラーを報告してはならない。 引数が NaN ではないが次の条件を一つでも満たす場合、定義域エラーを報告しなければならない:

• 規格が関数の定義域を明示していて (各解説ページを参照)、その定義域内にない
• 数学関数の値の虚部が 0 でない
• 数学関数が数学的に定義されていない

数学関数が数学的に定義されるのは以下のいずれかの場合である:

• ある集合において明示的に定義されている
• 極限が存在する (右極限と左極限が存在し、一致する)

特記のない限り、以下の関数は全ての有限値と正負の無限大において定義される。

最近傍整数

剰余

浮動小数点操作

最大値・最小値と正の差

乗算-加算

線形補間

数値分類

数値比較

型

数値のマクロ

数値分類のマクロ

その他のマクロ

関連項目

• <numbers>

参照

• N1568 Proposed additions to TR-1 to improve compatibility with C99
• P0175R0 Synopses for the C library
  • C++17 からf、lサフィックス付きのC関数を導入
• P0533R9 constexpr for <cmath> and <cstdlib>
  • C++23での、一部関数のconstexpr対応