モジュール java.base
パッケージ java.math

クラスBigDecimal

java.lang.Object
java.lang.Number
java.math.BigDecimal
すべての実装されたインタフェース:
Serializable, Comparable<BigDecimal>
public class BigDecimal extends Number implements Comparable<BigDecimal>
変更が不可能な、任意精度の符号付き10進数です。 BigDecimalは、任意の精度整数「スケールなしの値」および32ビットの整数scaleで構成されます。 スケールがゼロまたは正の場合、スケールは小数点の右側の桁数です。 スケールが負の場合、数値のスケール解除値に10を掛けてスケールを否定します。 したがって、BigDecimalで表される数値は(unscaledValue × 10-scale)です。

BigDecimalクラスは、算術、スケール操作、丸め、比較、ハッシング、および書式変換の演算を提供します。 toString()メソッドはBigDecimalの正規表現を提供します。

BigDecimalクラスは、ユーザーが丸め動作を完全に制御できるようにします。 端数処理モードが指定されず、正確な結果を表示できない場合は、ArithmeticExceptionがスローされます。指定されていない場合は、適切なMathContextオブジェクトを操作に指定することで、選択した精度および端数処理モードに計算を実行できます。 どちらの場合も、丸めの制御に8つの丸めモードが提供されます。 このクラス(ROUND_HALF_UPなど)の整数フィールドを使用して丸めモードを表すことは非推奨です。かわりに、RoundingMode enumの列挙値、(RoundingMode.HALF_UPなど)を使用する必要があります。

MathContextオブジェクトに精度設定0 (たとえば、 MathContext.UNLIMITED)が指定されている場合、その算術メソッドはMathContextオブジェクトを使用しないため、算術演算は正確です。 結果の計算が正確であるため、精度0の設定を持つ MathContextオブジェクトの丸めモード設定は使用されず、無関係です。 除算の場合、正確な商は小数点以下が無限の長さを持つ可能性があります(たとえば、 1÷3)。 商の小数点以下が無限で、演算が正確な結果を返すように指定されている場合、 ArithmeticExceptionがスローされます。 そうでない場合、ほかの演算と同様に、除算の正確な結果が返されます。

精度設定が0でない場合、 BigDecimalの算術ルールは、ANSI X3.274-1996およびANSI X3.274-1996/AM 1-2000 (セクション7.4)で定義されている、選択された演算モードと広範な互換性があります。 これらの標準とは異なり、BigDecimalには多くの端数処理モードが含まれます。 これらのANSI規格とBigDecimal仕様の競合は、BigDecimalを優先する方法で解決されます。

同じ数値でも表現が異なる(スケールが異なる)可能性があるため、算術および丸めのルールは、数値的な結果と、結果の表現に使用するスケールの両方を指定する必要があります。 同じ数値の異なる表現は、同じ「コーホート」のメンバーと呼ばれます。 BigDecimalの「自然順序」では、同じコホートのメンバーが互いに等しいとみなされます。 一方、equalsメソッドでは、等価を保持するために数値と表現の両方が同じである必要があります。 scaleやunscaledValue()などのメソッドの結果は、異なる表現を持つ数値で異なります。

一般に、端数処理モードと精度の設定によって、正確な結果に返される桁数よりも桁数が(分裂と平方根の場合にはおそらく無限に多く)の桁数が多い場合に、操作が限られた桁数で結果を返す方法が決まります。 まず、返される桁の合計数はMathContextのprecision設定で指定されます。これにより、結果の精度が決定されます。 桁数のカウントは、正確な結果のもっとも左の0でない桁から始まります。 丸めモードでは、破棄される桁が返される結果にどのように影響するかが決定されます。

すべての算術演算子について、最初に正確な中間結果が計算されたかのように演算が実行され、選択した丸めモードを使用して、精度設定(必要に応じて)で指定された桁数に丸められます。 正確な結果が返されない場合、正確な結果のいくつかの桁位置が破棄されます。 丸めにより、返される結果の絶対値が増える場合、先頭の「9」の桁に対して桁の繰上げを実行することで新しい桁位置を作成できます。 たとえば、999.9という値を切り上げて3桁に丸めると、1000と等しくなり、これは100×101として表現されます。 このような場合、新しい「1」が返される結果の先頭の桁位置になります。

MathContextパラメータのあるメソッドおよびコンストラクタでは、結果が正確でなく、丸めモードがUNNECESSARYの場合、 ArithmeticExceptionがスローされます。

論理的に正確な結果のほか、各算術演算には結果を表現するために優先されるスケールがあります。 各演算の優先スケールを、次の表に示します。

算術演算の結果で優先されるスケール
操作優先される結果のスケール
追加max(addend.scale(), augend.scale())
減算max(minuend.scale(), subtrahend.scale())
乗算multiplier.scale() + multiplicand.scale()
除算dividend.scale() - divisor.scale()
平方根radicand.scale()/2
これらのスケールは、正確な算術結果を返すメソッドによってだけ使用されます。ただし、正確な除算では、正確な結果の桁数が多い可能性があるため、より大きなスケールを使用する必要がある場合があります。 たとえば、1/32は0.03125です。

丸めの前は、論理的に正確な中間結果のスケールがその演算の優先スケールです。 正確な数値結果をprecision桁で表現できない場合、返す桁セットが丸めにより選択され、その結果のスケールは中間結果のスケールから、実際に返されるprecision桁を表すことのできる最小のスケールに縮小されます。 正確な結果がprecision桁で表現できる場合、その結果の表現は優先スケールにもっとも近いスケールで返されます。 特に、正確に表現可能な商は、末尾の0を削除し、スケールを小さくすることで、precision桁よりも少ない桁で表現できます。 たとえば、floor丸めモードを使用した3桁への丸めでは、次のようになります。
19/100 = 0.19 // integer=19, scale=2
ただし、次も成り立ちます。
21/110 = 0.190 // integer=190, scale=3

加算、減算、および乗算では、スケールの縮小は、正確な結果の破棄される桁位置の数と等しくなる点に注意してください。 丸めによる桁の繰上げで新しい上位の桁位置が作成される場合、新しい桁位置が作成されないと、結果の追加された桁は破棄されます。

ほかのメソッドは、少し異なる丸めセマンティックスを持つ可能性があります。 たとえば、指定されたアルゴリズムを使用するpowメソッドの結果は、丸められた数学的結果と、最終桁の1単位以上、つまり1 ulp以上異なる場合があります。

BigDecimalのスケール操作には、スケーリング/丸め演算と小数点移動演算の2種類があります。 スケーリング/丸め演算(setScaleとround)は、値がオペランドの値とほぼ(または正確に)等しいがスケールまたは精度は指定された値であるBigDecimalを返します。このスケールまたは精度により、値に対して最小限の影響で、格納される数値の精度が上下します。 小数点移動演算(movePointLeftとmovePointRight)は、指定した方向に指定した桁だけ小数点を移動することによりオペランドから作成されるBigDecimalを返します。

32ビット整数として、スケールの値セットは大きいが、制限されています。 結果のスケールがオーバーフローまたはアンダー・フローによって32ビット整数範囲を超える場合、その操作はArithmeticExceptionをスローする可能性があります。

説明をわかりやすく簡潔にするために、BigDecimalメソッドの説明では全体を通して擬似コードを使用します。 擬似コード式(i+j)は、「値がBigDecimal iの値とBigDecimal jの値の和であるBigDecimal」を示します。 擬似コード式(i == j)は、「BigDecimal iがBigDecimal jと同じ値を表す場合にだけtrueであること」を示します。 ほかの擬似コード式も同じように解釈されます。 角カッコは、BigDecimal値を定義する特別なBigIntegerとスケールのペアを表すために使用されます。たとえば、[19, 2]は、スケール2を持つ0.19と数値的に等しいBigDecimalです。

このクラスのメソッドおよびコンストラクタはすべて、入力パラメータに対してnullオブジェクト参照が渡されるとNullPointerExceptionをスローします。

APIのノート:
BigDecimalの「自然順序付け」は「equalsと矛盾」であるため、BigDecimalオブジェクトがSortedMapのキーまたはSortedSetの要素として使用されている場合は注意が必要です。 詳細については、Comparable、SortedMapまたはSortedSetを参照してください。

IEEE 754十進演算との関係

2008改訂以降、「浮動小数点演算用IEEE 754標準」には10進形式および操作が含まれています。 IEEE 754とこのクラスによって定義された10進数の演算に多くの類似性がありますが、重要な違いもあります。 BigDecimalとIEEE 754の10進数の算術で共有される基本的な類似性は、演算の無限に正確な実数値を計算し、その実数を「端数処理ポリシー」の表形式の浮動小数点値にマッピングする概念的演算です。 端数処理ポリシーは、BigDecimalの「端数処理モード」と呼ばれ、IEEE 754-2019の丸め方向属性と呼ばれます。 正確な値が代用可能でない場合、端数処理ポリシーによって、正確な値が計算結果として選択される2つの代表可能な10進数値のうちどれかが決まります。 「優先スケール/優先指数」の概念も両方のシステムによって共有されます。

相違点については、IEEE 754には、負のゼロ、符号付き無限、およびNaN (not-a-number)など、BigDecimalによってモデル化されない複数の種類の値が含まれています。 IEEE 754は、ベース (2進または10進)、精度の桁数、指数範囲でパラメータ化されたフォーマットを定義します。 フォーマットは、代表可能な値のセットを決定します。 ほとんどの演算は、特定の書式の1つ以上の値を入力として受け入れ、同じ形式で結果を生成します。 BigDecimalのscaleは、IEEE 754値の指数を無視することと同じです。 BigDecimal値の形式は同じ意味ではありません。すべての値のスケール/指数の範囲が同じであり、「スケールなしの値」の精度は任意です。 かわりに、MathContextパラメータを使用するBigDecimal操作の場合、MathContextにゼロ以外の精度がある場合、結果の表現可能な値のセットは、MathContext引数の精度によって決まります。 たとえば、BigDecimalでは、精度が3のMathContextオブジェクトのコンテキストで、0以外の3桁の数値と0以外の4桁数を乗算すると、結果は3桁の(オーバーフローやアンダー・フローなどがないと想定します。)になります。

「端数処理モード」で示されるBigDecimal操作によって実装される端数処理ポリシーは、IEEE 754端数処理方向属性の適切なスーパーセットです。

BigDecimal演算は、IEEE 754小数形式に対応するMathContext (decimal64やdecimal128など)がすべての開始値と中間演算の丸めに使用される場合、IEEE 754進数の演算に最も似ています。 MathContextがBigDecimalの結果のスケールを制約しないために、近似しているIEEE 754形式の指数範囲を超えた場合、計算される数値は異なる可能性があります。 NaNまたは完全無限度を生成する操作(ゼロで除算するなど)は、BigDecimal算術でArithmeticExceptionをスローします。

アルゴリズムの複雑さ

BigDecimal値に対する操作には、アルゴリズムの複雑さの範囲があります。一般に、これらの複雑さは、スケーリングされていない値のサイズとスケールのサイズの両方の機能です。 たとえば、2つのBigDecimal値の「正確な乗算」は、スケーリングされていない値のBigInteger乗算と同じ「複雑性の制約」の対象となります。 一方、new BigDecimal(1E-1000000000)のようなコンパクトな表現を持つBigDecimal値には、10億文字を超えるtoPlainString()結果があります。

操作では、中間結果を割り当ててコンピュートすることもできます。これらの割当ては、アルゴリズムの実行時間に比例して大きくなる可能性があります。

実行時間または操作領域の境界に関係するBigDecimalのユーザーは、BigDecimal値をスケールなしの値でスクリーニングしたり、選択した大きさを超えるスケールをスクリーニングできます。

導入されたバージョン:
1.1
関連項目: