"decimal" --- 10進固定小数点と浮動小数点の演算
**********************************************

**ソースコード:** Lib/decimal.py

======================================================================

"decimal" モジュールは、高速で正しく丸められる 10 進浮動小数点演算をサ
ポートします。 "float" データ型に比べて次のような利点があります:

* Decimal は「人間を念頭に設計された 浮動小数点モデル に基づいており、
  当然ながら次の最重要の指針に従っています。 コンピューターは、人間が
  学校で習う算術と同じように動作する算術を提供しなければならない」— 十
  進数演算仕様からの抜粋。

* 十進数を正確に表現できます。 "1.1" や "2.2" のような数は、二進数の浮
  動小数点型では正しく表現できません。エンドユーザは普通、 二進数にお
  ける "1.1 + 2.2" の近似値が "3.3000000000000003" だからといって、そ
  のように表示してほしいとは考えないものです。

* 値の正確さは算術にも及びます。十進の浮動小数点による計算では、 "0.1
  + 0.1 + 0.1 - 0.3" は厳密にゼロに等しくなります。 二進浮動小数点では
  "5.5511151231257827e-017" になってしまいます。ゼロに近い値とはいえ、
  この誤差は数値間の等価性テストの信頼性を阻害します。また、誤差が蓄積
  されることもあります。こうした理由から、数値間の等価性を厳しく保たな
  ければならないようなアプリケーションを考えるなら、十進数による数値表
  現が望ましいということになります。

* "decimal" モジュールでは、有効桁数の表記が取り入れられており、例えば
  "1.30 + 1.20" は "2.50" になります。すなわち、末尾のゼロは有効数字を
  示すために残されます。こうした仕様は通貨計算を行うアプリケーションで
  は慣例です。乗算の場合、「教科書的な」アプローチでは、乗算の被演算子
  すべての桁数を使います。例えば、 "1.3 * 1.2" は "1.56" になり、
  "1.30 * 1.20" は "1.5600" になります。

* ハードウェアによる 2 進浮動小数点演算と違い、"decimal" モジュールで
  はユーザーが精度を変更できます (デフォルトは 28 桁です)。 問題に応じ
  て必要なだけ精度を高くできます:

  >>> from decimal import *
  >>> getcontext().prec = 6
  >>> Decimal(1) / Decimal(7)
  Decimal('0.142857')
  >>> getcontext().prec = 28
  >>> Decimal(1) / Decimal(7)
  Decimal('0.1428571428571428571428571429')

* 二進と十進の浮動小数点は、いずれも広く公開されている標準仕様のもとに
  実装されています。組み込みの浮動小数点型では、標準仕様で提唱されてい
  る機能のほんのささやかな部分を利用できるにすぎませんが、 "decimal"
  では標準仕様が要求している全ての機能を利用できます。必要に応じて、プ
  ログラマは値の丸めやシグナル処理を完全に制御できます。この中には全て
  の不正確な操作を例外でブロックして正確な算術を遵守させるオプションも
  あります。

* decimal モジュールは「偏見なく、正確な丸めなしの十進算術(固定小数点
  算術と呼ばれることもある)と丸めありの浮動小数点数算術」(十進数演算仕
  様より引用)をサポートするようにデザインされました。

このモジュールは、十進数型、算術コンテキスト (context for arithmetic)
、そしてシグナル (signal) という三つの概念を中心に設計されています。

十進数型は変更不能です。これは符号、係数部、そして指数を持ちます。有効
桁数を残すために、仮数部の末尾にあるゼロは切り詰められません。
"decimal" では、 "Infinity", "-Infinity", および "NaN" といった特殊な
値も定義されています。標準仕様では "-0" と "+0" も区別します。

算術コンテキストとは、精度や値丸めの規則、指数部の制限を決めている環境
です。この環境では、演算結果を表すためのフラグや、演算上発生した特定の
シグナルを例外として扱うかどうかを決めるトラップイネーブラも定義してい
ます。丸め規則には "ROUND_CEILING", "ROUND_DOWN", "ROUND_FLOOR",
"ROUND_HALF_DOWN", "ROUND_HALF_EVEN", "ROUND_HALF_UP", "ROUND_UP", お
よび "ROUND_05UP" があります。

シグナルとは、演算の過程で生じる例外的条件です。個々のシグナルは、アプ
リケーションそれぞれの要求に従って、無視されたり、単なる情報とみなされ
たり、例外として扱われたりします。 "decimal" モジュールには、
"Clamped", "InvalidOperation", "DivisionByZero", "Inexact", "Rounded",
"Subnormal", "Overflow", "Underflow", および "FloatOperation" といった
シグナルがあります。

各シグナルには、フラグとトラップイネーブラがあります。演算上何らかのシ
グナルに遭遇すると、フラグは 1 にセットされます。このとき、もしトラッ
プイネーブラが 1 にセットされていれば、例外を送出します。フラグの値は
膠着型 (sticky) なので、演算によるフラグの変化をモニタしたければ、予め
フラグをリセットしておかなければなりません。

参考:

  * IBM による汎用十進演算仕様、The General Decimal Arithmetic
    Specification。


入門チュートリアル
==================

普通、 "decimal" を使うときには、モジュールをインポートし、現在の演算
コンテキストを "getcontext()" で調べ、必要なら、精度、丸め、有効なトラ
ップを設定します:

   >>> from decimal import *
   >>> getcontext()
   Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,
           capitals=1, clamp=0, flags=[], traps=[Overflow, DivisionByZero,
           InvalidOperation])

   >>> getcontext().prec = 7       # 新しい精度を設定します

"Decimal" インスタンスは、整数、文字列、浮動小数点数、またはタプルから
構成できます。整数や浮動小数点数からの構成は、整数や浮動小数点数の値を
正確に変換します。 "Decimal" は "非数 (Not a Number)" を表す "NaN" や
正負の "Infinity" (無限大)、 "-0" といった特殊な値も表現できます:

   >>> getcontext().prec = 28
   >>> Decimal(10)
   Decimal('10')
   >>> Decimal('3.14')
   Decimal('3.14')
   >>> Decimal(3.14)
   Decimal('3.140000000000000124344978758017532527446746826171875')
   >>> Decimal((0, (3, 1, 4), -2))
   Decimal('3.14')
   >>> Decimal(str(2.0 ** 0.5))
   Decimal('1.4142135623730951')
   >>> Decimal(2) ** Decimal('0.5')
   Decimal('1.414213562373095048801688724')
   >>> Decimal('NaN')
   Decimal('NaN')
   >>> Decimal('-Infinity')
   Decimal('-Infinity')

"FloatOperation" シグナルがトラップされる場合、コンストラクタや順序比
較において誤って decimal と float が混ざると、例外が送出されます:

   >>> c = getcontext()
   >>> c.traps[FloatOperation] = True
   >>> Decimal(3.14)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   decimal.FloatOperation: [<class 'decimal.FloatOperation'>]
   >>> Decimal('3.5') < 3.7
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   decimal.FloatOperation: [<class 'decimal.FloatOperation'>]
   >>> Decimal('3.5') == 3.5
   True

Added in version 3.3.

新たな "Decimal" の有効桁数は入力の桁数だけで決まります。演算コンテキ
ストにおける精度や値丸めの設定が影響するのは算術演算の間だけです。

   >>> getcontext().prec = 6
   >>> Decimal('3.0')
   Decimal('3.0')
   >>> Decimal('3.1415926535')
   Decimal('3.1415926535')
   >>> Decimal('3.1415926535') + Decimal('2.7182818285')
   Decimal('5.85987')
   >>> getcontext().rounding = ROUND_UP
   >>> Decimal('3.1415926535') + Decimal('2.7182818285')
   Decimal('5.85988')

C バージョンの内部制限を超えた場合、decimal の構成は
"InvalidOperation" を送出します:

   >>> Decimal("1e9999999999999999999")
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   decimal.InvalidOperation: [<class 'decimal.InvalidOperation'>]

バージョン 3.3 で変更.

Decimal は Python の他の多くの機能とうまく連携します。 10 進浮動小数点
数を使った、ちょっとした実演を見てみましょう:

   >>> data = list(map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split()))
   >>> max(data)
   Decimal('9.25')
   >>> min(data)
   Decimal('0.03')
   >>> sorted(data)
   [Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'),
    Decimal('2.35'), Decimal('3.45'), Decimal('9.25')]
   >>> sum(data)
   Decimal('19.29')
   >>> a,b,c = data[:3]
   >>> str(a)
   '1.34'
   >>> float(a)
   1.34
   >>> round(a, 1)
   Decimal('1.3')
   >>> int(a)
   1
   >>> a * 5
   Decimal('6.70')
   >>> a * b
   Decimal('2.5058')
   >>> c % a
   Decimal('0.77')

Decimal は、組み込みの "format()" や f-strings を使って、固定小数点表
記や科学表記に書式化できます。 書式指定の構文 (書式指定ミニ言語 を参照
) は組み込みの "float" 型と同じです:

   >>> format(Decimal('2.675'), "f")
   '2.675'
   >>> format(Decimal('2.675'), ".2f")
   '2.68'
   >>> f"{Decimal('2.675'):.2f}"
   '2.68'
   >>> format(Decimal('2.675'), ".2e")
   '2.68e+0'
   >>> with localcontext() as ctx:
   ...     ctx.rounding = ROUND_DOWN
   ...     print(format(Decimal('2.675'), ".2f"))
   ...
   2.67

いくつかの数学的関数も Decimal には用意されています:

>>> getcontext().prec = 28
>>> Decimal(2).sqrt()
Decimal('1.414213562373095048801688724')
>>> Decimal(1).exp()
Decimal('2.718281828459045235360287471')
>>> Decimal('10').ln()
Decimal('2.302585092994045684017991455')
>>> Decimal('10').log10()
Decimal('1')

"quantize()" メソッドは位を固定して数値を丸めます。このメソッドは、結
果を固定の桁数で丸めることがよくある、金融アプリケーションで便利です:

>>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)
Decimal('7.32')
>>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)
Decimal('8')

前述のように、 "getcontext()" 関数を使うと現在の演算コンテキストにアク
セスでき、設定を変更できます。ほとんどのアプリケーションはこのアプロー
チで十分です。

より高度な処理では、"Context()" コンストラクタで別のコンテキストを作る
と便利な場合があります。 別のコンテキストを有効にするには
"setcontext()" 関数を使います。

"decimal" モジュールは仕様に従い、そのまま使える 2 つの標準コンテキス
ト "BasicContext" と "ExtendedContext" を提供します。 前者は多くのトラ
ップが有効になっているので、特にデバッグに便利です:

   >>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)
   >>> setcontext(myothercontext)
   >>> Decimal(1) / Decimal(7)
   Decimal('0.142857142857142857142857142857142857142857142857142857142857')

   >>> ExtendedContext
   Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,
           capitals=1, clamp=0, flags=[], traps=[])
   >>> setcontext(ExtendedContext)
   >>> Decimal(1) / Decimal(7)
   Decimal('0.142857143')
   >>> Decimal(42) / Decimal(0)
   Decimal('Infinity')

   >>> setcontext(BasicContext)
   >>> Decimal(42) / Decimal(0)
   Traceback (most recent call last):
     File "<pyshell#143>", line 1, in -toplevel-
       Decimal(42) / Decimal(0)
   DivisionByZero: x / 0

演算コンテキストには、演算中に遭遇した例外的状況をモニタするためのシグ
ナルフラグがあります。フラグが一度セットされると、明示的にクリアするま
で残り続けます。そのため、フラグのモニタを行いたいような演算の前には
"clear_flags()" メソッドでフラグをクリアしておくのがベストです。

   >>> setcontext(ExtendedContext)
   >>> getcontext().clear_flags()
   >>> Decimal(355) / Decimal(113)
   Decimal('3.14159292')
   >>> getcontext()
   Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,
           capitals=1, clamp=0, flags=[Inexact, Rounded], traps=[])

*flags* エントリから、pi の有理数による近似値が丸められた (コンテキス
ト内で決められた精度を超えた桁数が捨てられた) ことと、計算結果が厳密で
ない (無視された桁の値に非ゼロのものがあった) ことがわかります。

コンテキストの "traps" 属性に入っている辞書を使うと、個々のトラップを
セットできます:

   >>> setcontext(ExtendedContext)
   >>> Decimal(1) / Decimal(0)
   Decimal('Infinity')
   >>> getcontext().traps[DivisionByZero] = 1
   >>> Decimal(1) / Decimal(0)
   Traceback (most recent call last):
     File "<pyshell#112>", line 1, in -toplevel-
       Decimal(1) / Decimal(0)
   DivisionByZero: x / 0

ほとんどのプログラムでは、開始時に一度だけ現在の演算コンテキストを修正
します。また、多くのアプリケーションでは、データから "Decimal" への変
換はループ内で一度だけキャストして行います。コンテキストを設定し、
"Decimal" オブジェクトを生成できたら、ほとんどのプログラムは他の
Python 数値型と全く変わらないかのように "Decimal" を操作できます。


Decimal オブジェクト
====================

class decimal.Decimal(value='0', context=None)

   *value* に基づいて新たな "Decimal" オブジェクトを構築します。

   *value* は整数、文字列、タプル、 "float" および他の "Decimal" オブ
   ジェクトにできます。 *value* を指定しない場合、 "Decimal('0')" を返
   します。 *value* が文字列の場合、先頭と末尾の空白および全てのアンダ
   ースコアを取り除いた後には以下の 10進数文字列の文法に従わなければな
   りません:

      sign           ::=  '+' | '-'
      digit          ::=  '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
      indicator      ::=  'e' | 'E'
      digits         ::=  digit [digit]...
      decimal-part   ::=  digits '.' [digits] | ['.'] digits
      exponent-part  ::=  indicator [sign] digits
      infinity       ::=  'Infinity' | 'Inf'
      nan            ::=  'NaN' [digits] | 'sNaN' [digits]
      numeric-value  ::=  decimal-part [exponent-part] | infinity
      numeric-string ::=  [sign] numeric-value | [sign] nan

   上記の "digit" には、他の Unicode の 10 進数字も使えます。 例えばア
   ラビア・インド数字やデーヴァナーガリー数字など、さまざまな文字体系
   の 10 進数字や、全角数字 "'\uff10'" から "'\uff19'" が含まれます。
   大文字・小文字は区別しないので、例えば "inf"、"Inf"、"INFINITY"、
   "iNfINity" はすべて正の無限大を表す表記として使えます。

   *value* を "tuple" にする場合、タプルは三つの要素を持ち、それぞれ符
   号 (正なら "0" 、負なら "1")、仮数部を表す数字の "tuple" 、そして指
   数を表す整数でなければなりません。例えば、 "Decimal((0, (1, 4, 1,
   4), -3))" は "Decimal('1.414')" を返します。

   *value* が "float" の場合、その 2 進浮動小数点数の値を、損失なく正
   確に対応する 10 進数へ変換します。 この変換には 53 桁以上の精度が必
   要になることもよくあります。 例えば "Decimal(float('1.1'))" は
   "Decimal('1.100000000000000088817841970012523233890533447265625')"
   に変換されます。

   *context* の精度 (precision) は、記憶される桁数には影響しません。桁
   数は *value* に指定した桁数だけから決定されます。例えば、演算コンテ
   キストに指定された精度が 3 桁しかなくても、"Decimal('3.00000')" は
   5 つのゼロを全て記憶します。

   *context* 引数の目的は、 *value* が正しくない形式の文字列であった場
   合に行う処理を決めることにあります; 演算コンテキストが
   "InvalidOperation" をトラップするようになっていれば、例外を送出しま
   す。それ以外の場合には、コンストラクタは値が "NaN" の "Decimal" を
   返します。

   一度生成すると、 "Decimal" オブジェクトは変更不能 (immutable) にな
   ります。

   バージョン 3.2 で変更: コンストラクタに対する引数に "float" インス
   タンスも許されるようになりました。

   バージョン 3.3 で変更: "FloatOperation" トラップがセットされていた
   場合 "float" 引数は例外を送出します。デフォルトでトラップはオフです
   。

   バージョン 3.6 で変更: コード中の整数リテラルや浮動小数点リテラルと
   同様に、アンダースコアを用いて桁をグルーピングできます。

   10 進浮動小数点オブジェクトは、"float" や "int" などの他の組み込み
   数値型と多くの性質を共有しています。 通常の数学演算や特殊メソッドは
   すべて利用できます。 また、コピー、pickle 化、表示、辞書のキーや集
   合の要素としての利用、比較、ソート、他の型 ("float" や "int" など)
   への変換もできます。

   十進オブジェクトの算術演算と整数や浮動小数点数の算術演算には少々違
   いがあります。十進オブジェクトに対して剰余演算を適用すると、計算結
   果の符号は除数の符号ではなく *被除数* の符号と一致します:

      >>> (-7) % 4
      1
      >>> Decimal(-7) % Decimal(4)
      Decimal('-3')

   整数除算演算子 "//" も同様に、実際の商の切り捨てではなく (0に近付く
   ように丸めた) 整数部分を返します。そのため通常の恒等式 "x == (x //
   y) * y + x % y" が維持されます:

      >>> -7 // 4
      -2
      >>> Decimal(-7) // Decimal(4)
      Decimal('-1')

   演算子 "%" と演算子 "//" は (それぞれ) 仕様にあるような "剰余" 操作
   と "整数除算" 操作を実装しています。

   Decimal オブジェクトは一般に、算術演算で浮動小数点数や
   "fractions.Fraction" オブジェクトと組み合わせることができません。例
   えば、 "Decimal" に "float" を足そうとすると、 "TypeError" が送出さ
   れます。ただし、Python の比較演算子を使って "Decimal" インスタンス
   "x" と別の数 "y" を比較することができます。これにより、異なる型の数
   間の等価比較の際に、紛らわしい結果を避けます。

   バージョン 3.2 で変更: "Decimal" インスタンスと他の数値型が混在する
   比較が完全にサポートされるようになりました。

   10 進浮動小数点オブジェクトには、標準的な数値の性質に加えて、次のよ
   うな専用メソッドがあります:

   adjusted()

      仮数の先頭の一桁だけが残るように右側の数字を追い出す桁シフトを行
      い、その結果の指数部を返します: "Decimal('321e+5').adjusted()"
      は 7 を返します。最上桁の小数点からの相対位置を調べる際に使いま
      す。

   as_integer_ratio()

      与えられた "Decimal" インスタンスを、既約分数で分母が正数の分数
      として表現した整数のペア "(n, d)" を返します。

         >>> Decimal('-3.14').as_integer_ratio()
         (-157, 50)

      変換は正確に行われます。無限大に対してはOverflowErrorを、NaNに対
      してはValueError を送出します。

   Added in version 3.6.

   as_tuple()

      数値を表現するための *名前付きタプル*: "DecimalTuple(sign,
      digits, exponent)" を返します。

   canonical()

      引数の標準的(canonical)エンコーディングを返します。現在のところ
      、 "Decimal" インスタンスのエンコーディングは常に標準的なので、
      この操作は引数に手を加えずに返します。

   compare(other, context=None)

      二つの Decimal インスタンスの値を比較します。 "compare()" は
      Decimal インスタンスを返し、被演算子のどちらかが NaN ならば結果
      は NaN です:

         a または b が NaN  ==> Decimal('NaN')
         a < b            ==> Decimal('-1')
         a == b           ==> Decimal('0')
         a > b            ==> Decimal('1')

   compare_signal(other, context=None)

      この演算は "compare()" とほとんど同じですが、全ての NaN がシグナ
      ルを送るところが異なります。すなわち、どちらの比較対象も発信
      (signaling) NaN でないならば無言 (quiet) NaN である比較対象があ
      たかも発信 NaN であるかのように扱われます。

   compare_total(other, context=None)

      二つの対象を数値によらず抽象表現によって比較します。 "compare()"
      に似ていますが、結果は "Decimal" に全順序を与えます。この順序づ
      けによると、数値的に等しくても異なった表現を持つ二つの "Decimal"
      インスタンスの比較は等しくなりません:

      >>> Decimal('12.0').compare_total(Decimal('12'))
      Decimal('-1')

      無言 NaN と発信 NaN もこの全順序に位置付けられます。この関数の結
      果は、もし比較対象が同じ表現を持つならば "Decimal('0')" であり、
      一つめの比較対象が二つめより下位にあれば "Decimal('-1')"、上位に
      あれば "Decimal('1')" です。全順序の詳細については仕様を参照して
      ください。

      この演算はコンテキストに影響されず、静かです。すなわち、フラグは
      変更されず、丸めは行われません。例外として、2番目の比較対象の厳
      密な変換ができない場合、C バージョンのライブラリでは
      InvalidOperation 例外を送出するかもしれません。

   compare_total_mag(other, context=None)

      二つの対象を "compare_total()" のように数値によらず抽象表現によ
      って比較しますが、両者の符号を無視します。
      "x.compare_total_mag(y)" は
      "x.copy_abs().compare_total(y.copy_abs())" と等価です。

      この演算はコンテキストに影響されず、静かです。すなわち、フラグは
      変更されず、丸めは行われません。例外として、2番目の比較対象の厳
      密な変換ができない場合、C バージョンのライブラリでは
      InvalidOperation 例外を送出するかもしれません。

   conjugate()

      self を返すだけです。このメソッドは十進演算仕様に適合するためだ
      けのものです。

   copy_abs()

      引数の絶対値を返します。この演算はコンテキストに影響されず、静か
      です。すなわち、フラグは変更されず、丸めは行われません。

   copy_negate()

      引数の符号を変えて返します。この演算はコンテキストに影響されず、
      静かです。すなわち、フラグは変更されず、丸めは行われません。

   copy_sign(other, context=None)

      最初の演算対象のコピーに二つめと同じ符号を付けて返します。たとえ
      ば:

      >>> Decimal('2.3').copy_sign(Decimal('-1.5'))
      Decimal('-2.3')

      この演算はコンテキストに影響されず、静かです。すなわち、フラグは
      変更されず、丸めは行われません。例外として、2番目の比較対象の厳
      密な変換ができない場合、C バージョンのライブラリでは
      InvalidOperation 例外を送出するかもしれません。

   exp(context=None)

      与えられた数での(自然)指数関数 "e**x" の値を返します。結果は
      "ROUND_HALF_EVEN" 丸めモードで正しく丸められます。

      >>> Decimal(1).exp()
      Decimal('2.718281828459045235360287471')
      >>> Decimal(321).exp()
      Decimal('2.561702493119680037517373933E+139')

   classmethod from_float(f, /)

      "float" または "int" のインスタンスだけを受け付ける、別形式のコ
      ンストラクタです。

      なお、"Decimal.from_float(0.1)" は "Decimal('0.1')" と同じではあ
      りません。 0.1 は二進浮動小数点数で正確に表せないので、その値は
      表現できる最も近い値、"0x1.999999999999ap-4" として記憶されます
      。 同じ値を十進数で表すと
      "0.1000000000000000055511151231257827021181583404541015625" です
      。

      注釈:

        Python 3.2 以降では、 "Decimal" インスタンスは "float" から直
        接構成できるようになりました。

         >>> Decimal.from_float(0.1)
         Decimal('0.1000000000000000055511151231257827021181583404541015625')
         >>> Decimal.from_float(float('nan'))
         Decimal('NaN')
         >>> Decimal.from_float(float('inf'))
         Decimal('Infinity')
         >>> Decimal.from_float(float('-inf'))
         Decimal('-Infinity')

      Added in version 3.1.

   classmethod from_number(number, /)

      "float"、"int"、"Decimal" のインスタンスだけを受け付け、文字列や
      タプルは受け付けない、別形式のコンストラクタです。

         >>> Decimal.from_number(314)
         Decimal('314')
         >>> Decimal.from_number(0.1)
         Decimal('0.1000000000000000055511151231257827021181583404541015625')
         >>> Decimal.from_number(Decimal('3.14'))
         Decimal('3.14')

      Added in version 3.14.

   fma(other, third, context=None)

      融合積和(fused multiply-add)です。self*other+third を途中結果の
      積 self*other で丸めを行わずに計算して返します。

      >>> Decimal(2).fma(3, 5)
      Decimal('11')

   is_canonical()

      引数が標準的(canonical)ならば "True" を返し、そうでなければ
      "False" を返します。現在のところ、 "Decimal" のインスタンスは常
      に標準的なのでこのメソッドの結果はいつでも "True" です。

   is_finite()

      引数が有限の数値ならば "True" を、無限大か NaN ならば "False" を
      返します。

   is_infinite()

      引数が正または負の無限大ならば "True" を、そうでなければ "False"
      を返します。

   is_nan()

      引数が (無言か発信かは問わず) NaN であれば "True" を、そうでなけ
      れば "False" を返します。

   is_normal(context=None)

      引数が *正規(normal)* の有限数値ならば "True" を返します。引数が
      ゼロ、非正規(subnormal)、無限大または NaN であれば "False" を返
      します。

   is_qnan()

      引数が無言 NaN であれば "True" を、そうでなければ "False" を返し
      ます。

   is_signed()

      引数に負の符号がついていれば "True" を、そうでなければ "False"
      を返します。注意すべきはゼロや NaN なども符号を持ち得ることです
      。

   is_snan()

      引数が発信 NaN であれば "True" を、そうでなければ "False" を返し
      ます。

   is_subnormal(context=None)

      引数が非正規数(subnormal)であれば "True" を、そうでなければ
      "False" を返します。

   is_zero()

      引数が(正または負の)ゼロであれば "True" を、そうでなければ
      "False" を返します。

   ln(context=None)

      演算対象の自然対数(底 e の対数)を返します。結果は
      "ROUND_HALF_EVEN" 丸めモードで正しく丸められます。

   log10(context=None)

      演算対象の底 10 の対数を返します。結果は "ROUND_HALF_EVEN" 丸め
      モードで正しく丸められます。

   logb(context=None)

      非零の数値については、 "Decimal" インスタンスとして調整された指
      数を返します。 演算対象がゼロだった場合、 "Decimal('-Infinity')"
      が返され "DivisionByZero" フラグがセットされます。 演算対象が無
      限大だった場合、 "Decimal('Infinity')" が返されます。

   logical_and(other, context=None)

      "logical_and()" は二つの *論理引数* (論理引数 参照)を取る論理演
      算です。結果は二つの引数の数字ごとの "and" です。

   logical_invert(context=None)

      "logical_invert()" は論理演算です。結果は引数の数字ごとの反転で
      す。

   logical_or(other, context=None)

      "logical_or()" は二つの *論理引数* (論理引数 参照)を取る論理演算
      です。結果は二つの引数の数字ごとの "or" です。

   logical_xor(other, context=None)

      "logical_xor()" は二つの *論理引数* (論理引数 参照)を取る論理演
      算です。結果は二つの引数の数字ごとの排他的論理和です。

   max(other, context=None)

      "max(self, other)" と同じですが、値を返す前に現在のコンテキスト
      に即した丸め規則を適用します。また、 "NaN" に対して、(コンテキス
      トの設定と、発信か無言どちらのタイプであるかに応じて) シグナルを
      発行するか無視します。

   max_mag(other, context=None)

      "max()" メソッドに似ていますが、比較は絶対値で行われます。

   min(other, context=None)

      "min(self, other)" と同じですが、値を返す前に現在のコンテキスト
      に即した丸め規則を適用します。また、 "NaN" に対して、(コンテキス
      トの設定と、発信か無言どちらのタイプであるかに応じて) シグナルを
      発行するか無視します。

   min_mag(other, context=None)

      "min()" メソッドに似ていますが、比較は絶対値で行われます。

   next_minus(context=None)

      与えられたコンテキスト(またはコンテキストが渡されなければ現スレ
      ッドのコンテキスト)において表現可能な、操作対象より小さい最大の
      数を返します。

   next_plus(context=None)

      与えられたコンテキスト(またはコンテキストが渡されなければ現スレ
      ッドのコンテキスト)において表現可能な、操作対象より大きい最小の
      数を返します。

   next_toward(other, context=None)

      二つの比較対象が等しくなければ、一つめの対象に最も近く二つめの対
      象へ近付く方向の数を返します。もし両者が数値的に等しければ、二つ
      めの対象の符号を採った一つめの対象のコピーを返します。

   normalize(context=None)

      現在のコンテキストまたは指定したコンテキスト内で、同値類の標準形
      となる値を生成するために使います。

      単項プラス演算と同じ意味を持ちますが、最終結果が有限の場合は、末
      尾のゼロをすべて取り除き、符号を保ったまま最も単純な形にします。
      具体的には、係数がゼロでない 10 の倍数である間、係数を 10 で割っ
      て指数を 1 増やします。 それ以外 (係数がゼロ) の場合は指数を 0
      にします。 いずれの場合も符号は変わりません。

      例えば "Decimal('32.100')" と "Decimal('0.321000e+2')" は、どち
      らも同じ値を持つ "Decimal('32.1')" に正規化されます。

      最も単純な形にする *前に* 丸めが適用されます。

      この演算は、新しい版の仕様では "reduce" とも呼ばれています。

   number_class(context=None)

      操作対象の *クラス* を表す文字列を返します。返されるのは以下の10
      種類のいずれかです。

      * ""-Infinity"", 負の無限大であることを示します。

      * ""-Normal"", 負の通常数であることを示します。

      * ""-Subnormal"", 負の非正規数であることを示します。

      * ""-Zero"", 負のゼロであることを示します。

      * ""+Zero"", 正のゼロであることを示します。

      * ""+Subnormal"", 正の非正規数であることを示します。

      * ""+Normal"", 正の通常数であることを示します。

      * ""+Infinity"", 正の無限大であることを示します。

      * ""NaN"", 無言 (quiet) NaN (Not a Number) であることを示します
        。

      * ""sNaN"", 発信(signaling) NaN であることを示します。

   quantize(exp, rounding=None, context=None)

      二つ目の操作対象と同じ指数を持つように丸めを行った、一つめの操作
      対象と等しい値を返します。

      >>> Decimal('1.41421356').quantize(Decimal('1.000'))
      Decimal('1.414')

      他の操作と違い、打ち切り(quantize)操作後の係数の長さが精度を越え
      た場合には、 "InvalidOperation" がシグナルされます。これによりエ
      ラー条件がない限り打ち切られた指数が常に右側の引数と同じになるこ
      とが保証されます。

      同様に、他の操作と違い、quantize は Underflow を、たとえ結果が非
      正規になったり不正確になったとしても、シグナルしません。

      二つ目の演算対象の指数が一つ目のそれよりも大きければ丸めが必要か
      もしれません。この場合、丸めモードは以下のように決められます。
      "rounding" 引数が与えられていればそれが使われます。そうでなけれ
      ば "context" 引数で決まります。どちらの引数も渡されなければ現在
      のスレッドのコンテキストの丸めモードが使われます。

      処理結果の指数が "Emax" よりも大きい場合や "Etiny()" よりも小さ
      い場合にエラーが返されます。

   radix()

      "Decimal(10)" つまり "Decimal" クラスがその全ての算術を実行する
      基数を返します。仕様との互換性のために取り入れられています。

   remainder_near(other, context=None)

      *self* を *other* で割った剰余を返します。これは "self % other"
      とは違って、剰余の絶対値を小さくするように符号が選ばれます。より
      詳しく言うと、"n" を "self / other" の正確な値に最も近い整数とし
      たときの "self - n * other" が返り値になります。最も近い整数が2
      つある場合には偶数のものが選ばれます。

      結果が0になる場合の符号は *self* の符号と同じになります。

      >>> Decimal(18).remainder_near(Decimal(10))
      Decimal('-2')
      >>> Decimal(25).remainder_near(Decimal(10))
      Decimal('5')
      >>> Decimal(35).remainder_near(Decimal(10))
      Decimal('-5')

   rotate(other, context=None)

      1 つ目の演算対象の数字を、2 つ目の演算対象で指定した桁数だけ巡回
      させた結果を返します。 2 つ目の演算対象は -precision から
      precision までの整数でなければなりません。 その絶対値が巡回させ
      る桁数を表し、正なら左へ、それ以外なら右へ巡回させます。 必要に
      応じて 1 つ目の演算対象の係数の左側をゼロで埋め、長さを
      precision に揃えます。 1 つ目の演算対象の符号と指数は変わりませ
      ん。

   same_quantum(other, context=None)

      *self* と *other* が同じ指数を持っているか、あるいは双方とも
      "NaN" である場合に真を返します。

      この演算はコンテキストに影響されず、静かです。すなわち、フラグは
      変更されず、丸めは行われません。例外として、2番目の比較対象の厳
      密な変換ができない場合、C バージョンのライブラリでは
      InvalidOperation 例外を送出するかもしれません。

   scaleb(other, context=None)

      二つ目の演算対象で調整された指数の一つ目の演算対象を返します。同
      じことですが、一つめの演算対象を "10**other" 倍したものを返しま
      す。二つ目の演算対象は整数でなければなりません。

   shift(other, context=None)

      1 つ目の演算対象の数字を、2 つ目の演算対象で指定した桁数だけシフ
      トした結果を返します。 2 つ目の演算対象は -precision から
      precision までの整数でなければなりません。 その絶対値がシフトす
      る桁数を表し、正なら左へ、それ以外なら右へシフトします。 シフト
      によって係数に入る数字はゼロです。 1 つ目の演算対象の符号と指数
      は変わりません。

   sqrt(context=None)

      引数の平方根を最大精度で求めます。

   to_eng_string(context=None)

      文字列に変換します。指数が必要なら工学表記が使われます。

      工学表記法では指数が 3 の倍数になります。 そのため、小数点の左側
      には最大 3 桁の数字が残り、末尾にゼロを 1 つまたは 2 つ追加する
      必要が生じることがあります。

      たとえば、"Decimal('123E+1')" は "Decimal('1.23E+3')" に変換され
      ます。

   to_integral(rounding=None, context=None)

      "to_integral_value()" メソッドと同じです。"to_integral" の名前は
      古いバージョンとの互換性のために残されています。

   to_integral_exact(rounding=None, context=None)

      最近傍の整数に値を丸め、丸めが起こった場合には "Inexact" または
      "Rounded" のシグナルを適切に出します。丸めモードは以下のように決
      められます。 "rounding" 引数が与えられていればそれが使われます。
      そうでなければ "context" 引数で決まります。どちらの引数も渡され
      なければ現在のスレッドのコンテキストの丸めモードが使われます。

   to_integral_value(rounding=None, context=None)

      "Inexact" や "Rounded" といったシグナルを出さずに最近傍の整数に
      値を丸めます。 *rounding* が指定されていれば適用されます; それ以
      外の場合、値丸めの方法は *context* の設定か現在のコンテキストの
      設定になります。

   Decimal の数値は "round()" 関数で丸められます:

   round(number)

   round(number, ndigits)

      *ndigits* を指定しないか "None" にすると、*number* に最も近い
      "int" を返します。 ちょうど中間なら偶数に丸め、"Decimal" のコン
      テキストの丸めモードは無視します。 *number* が無限大なら
      "OverflowError" を、無言 NaN または発信 NaN なら "ValueError" を
      送出します。

      If *ndigits* is an "int", the context's rounding mode is
      respected and a "Decimal" representing *number* rounded to the
      nearest multiple of "Decimal('1E-ndigits')" is returned; in this
      case, "round(number, ndigits)" is equivalent to
      "self.quantize(Decimal('1E-ndigits'))".  Returns
      "Decimal('NaN')" if *number* is a quiet NaN.  Raises
      "InvalidOperation" if *number* is an infinity, a signaling NaN,
      or if the length of the coefficient after the quantize operation
      would be greater than the current context's precision.  In other
      words, for the non-corner cases:

      * *ndigits* が正なら、*number* を小数点以下 *ndigits* 桁に丸めて
        返します。

      * *ndigits* がゼロなら、*number* を最も近い整数に丸めて返します
        。

      * *ndigits* が負なら、*number* を最も近い "10**abs(ndigits)" の
        倍数に丸めて返します。

      例えば:

         >>> from decimal import Decimal, getcontext, ROUND_DOWN
         >>> getcontext().rounding = ROUND_DOWN
         >>> round(Decimal('3.75'))     # コンテキストの丸めモードは無視します
         4
         >>> round(Decimal('3.5'))      # 中間値は偶数に丸めます
         4
         >>> round(Decimal('3.75'), 0)  # コンテキストの丸めモードを使います
         Decimal('3')
         >>> round(Decimal('3.75'), 1)
         Decimal('3.7')
         >>> round(Decimal('3.75'), -1)
         Decimal('0E+1')


論理引数
--------

"logical_and()", "logical_invert()", "logical_or()", および
"logical_xor()" メソッドはその引数が *論理引数* であると想定しています
。 *論理引数* とは "Decimal" インスタンスで指数と符号は共にゼロであり
、各桁の数字が "0" か "1" であるものです。


Context オブジェクト
====================

コンテキスト (context) とは、算術演算における環境設定です。コンテキス
トは計算精度を決定し、値丸めの方法を設定し、シグナルのどれが例外になる
かを決め、指数の範囲を制限しています。

多重スレッドで処理を行う場合には各スレッドごとに現在のコンテキストがあ
り、 "getcontext()" や "setcontext()" といった関数でアクセスしたり設定
変更できます:

decimal.getcontext()

   アクティブなスレッドの現在のコンテキストを返します。

decimal.setcontext(c, /)

   アクティブなスレッドのコンテキストを *c* に設定します。

"with" 文と "localcontext()" 関数を使って実行するコンテキストを一時的
に変更することもできます。

decimal.localcontext(ctx=None, **kwargs)

   with 文の入口でアクティブなスレッドのコンテキストを *ctx* のコピー
   に設定し、with 文を抜ける時に元のコンテキストに復旧する、コンテキス
   トマネージャを返します。コンテキストが指定されなければ、現在のコン
   テキストのコピーが使われます。*kwargs* 引数は新しいコンテキストの属
   性を設定するのに使われます。

   たとえば、以下のコードでは精度を42桁に設定し、計算を実行し、そして
   元のコンテキストに復帰します:

      from decimal import localcontext

      with localcontext() as ctx:
          ctx.prec = 42   # 高精度で計算します
          s = calculate_something()
      s = +s  # 最終結果をデフォルトの精度に丸めます

   キーワード引数を使うと、次のように書けます。

      from decimal import localcontext

      with localcontext(prec=42) as ctx:
          s = calculate_something()
      s = +s

   *kwargs* に "Context" がサポートしない属性を渡すと "TypeError" を送
   出します。 *kwargs* に属性の不正な値を渡すと "TypeError" または
   "ValueError" を送出します。

   バージョン 3.11 で変更: "localcontext()" でキーワード引数を使ってコ
   ンテキストの属性を設定できるようになりました。

decimal.IEEEContext(bits)

   IEEE の交換形式のいずれかに適した値で初期化したコンテキストオブジェ
   クトを返します。 引数は 32 の倍数で、"IEEE_CONTEXT_MAX_BITS" 未満で
   なければなりません。

   Added in version 3.14.

新たなコンテキストは、以下で説明する "Context" コンストラクタを使って
作成できます。 このほか、モジュールは作成済みのコンテキストを 3 つ提供
しています。

decimal.BasicContext

   汎用十進演算仕様で定義されている標準コンテキストの一つです。精度は
   9 桁に設定されています。丸め規則は "ROUND_HALF_UP" です。すべての演
   算結果フラグはクリアされています。 "Inexact", "Rounded",
   "Subnormal" を除く全ての演算エラートラップが有効 (例外として扱う)
   になっています。

   多くのトラップが有効になっているので、デバッグの際に便利なコンテキ
   ストです。

decimal.ExtendedContext

   汎用十進演算仕様で定義されている標準コンテキストの一つです。精度は
   9 桁に設定されています。丸め規則は "ROUND_HALF_EVEN" です。すべての
   演算結果フラグはクリアされています。トラップは全て無効(演算中に一切
   例外を送出しない) になっています。

   トラップが無効になっているので、エラーの伴う演算結果を "NaN" や
   "Infinity" にし、例外を送出しないようにしたいアプリケーションに向い
   たコンテキストです。このコンテキストを使うと、他の場合にはプログラ
   ムが停止してしまうような状況があっても実行を完了させられます。

decimal.DefaultContext

   "Context" コンストラクタが新たなコンテキストを作成するさいに雛形に
   するコンテキストです。このコンテキストのフィールド (精度の設定など)
   を変更すると、 "Context" コンストラクタが生成する新たなコンテキスト
   に影響を及ぼします。

   このコンテキストは、主に多重スレッド環境で便利です。スレッドを開始
   する前に何らかのフィールドを変更しておくと、システム全体のデフォル
   ト設定に効果を及ぼすことができます。スレッドを開始した後にフィール
   ドを変更すると、競合条件を抑制するためにスレッドを同期化しなければ
   ならないので、推奨しません。

   単一スレッドの環境では、このコンテキストを使わないよう薦めます。下
   で述べるように明示的にコンテキストを作成してください。

   デフォルトの値は、 "Context.prec"="28",
   "Context.rounding"="ROUND_HALF_EVEN" で、トラップ "Overflow",
   "InvalidOperation", および "DivisionByZero" が有効になっています。

上に挙げた三つのコンテキストに加え、 "Context" コンストラクタを使って
新たなコンテキストを生成できます。

class decimal.Context(prec=None, rounding=None, Emin=None, Emax=None, capitals=None, clamp=None, flags=None, traps=None)

   新たなコンテキストを生成します。 あるフィールドが定義されていないか
   "None" であれば、 "DefaultContext" からデフォルト値をコピーします。
   *flags* フィールドが指定されていないか "None" の場合には、全てのフ
   ラグがクリアされます。

   prec

      コンテキスト内の算術演算の精度を設定する、["1", "MAX_PREC"] の範
      囲の整数。

   rounding

      Rounding Modes 節に挙げられた定数のいずれか。

   traps
   flags

      設定するシグナルのリスト。 通常、新しいコンテキストではトラップ
      だけを設定し、フラグはクリアしたままにしてください。

   Emin
   Emax

      指数に許される範囲の上下限を指定する整数。 *Emin* は
      ["MIN_EMIN", "0"]、*Emax* は ["0", "MAX_EMAX"] の範囲でなければ
      なりません。

   capitals

      "0" または "1" (デフォルト)。 "1" にすると指数を大文字の "E" で
      表示し、それ以外では小文字の "e" を使います:
      "Decimal('6.02e+23')"。

   clamp

      "Decimal" インスタンスをこのコンテキストで表現するときの指数の制
      約を指定する、"0" (デフォルト) または "1"。 "1" にすると指数 "e"
      は "Emin - prec + 1 <= e <= Emax - prec + 1" の範囲に厳しく制限
      されます。 *clamp* が "0" の場合は制約が緩く、"Decimal" インスタ
      ンスの調整済み指数が "Emax" 以下であればよいことになります。
      *clamp* が "1" のときは、指数の制約を満たすよう、大きな正規数の
      指数を可能な限り減らし、その分のゼロを係数に追加します。 この変
      換で数値は保たれますが、末尾のゼロの有効桁数に関する情報は失われ
      ます。 例えば次のようになります。

         >>> Context(prec=6, Emax=999, clamp=1).create_decimal('1.23e999')
         Decimal('1.23000E+999')

      *clamp* の値 "1" は、IEEE 754 で規定された固定幅十進交換形式と互
      換にできます。

   "Context" クラスでは、いくつかの汎用のメソッドの他、指定されたコン
   テキストで算術演算を直接行うためのメソッドを数多く定義しています。
   加えて、 "Decimal" の各メソッドについて("adjusted()" および
   "as_tuple()" メソッドを例外として)対応する "Context" のメソッドが存
   在します。 たとえば、 "Context" インスタンス  "C" と "Decimal" イン
   スタンス "x" に対して、 "C.exp(x)" は "x.exp(context=C)" と等価です
   。 それぞれの "Context" メソッドは、Decimal インスタンスが受け付け
   られるところならどこでも、Python の整数 ("int" のインスタンス) を受
   け付けます。

   clear_flags()

      フラグを全て "0" にリセットします。

   clear_traps()

      トラップを全て "0" にリセットします。

      Added in version 3.3.

   copy()

      コンテキストの複製を返します。

   copy_decimal(num, /)

      Decimal インスタンス num のコピーを返します。

   create_decimal(num='0', /)

      *self* をコンテキストとする新たな Decimal インスタンスを *num*
      から生成します。 "Decimal" コンストラクタと違い、数値を変換する
      際にコンテキストの精度、値丸め方法、フラグ、トラップを適用します
      。

      定数値はしばしばアプリケーションの要求よりも高い精度を持っている
      ため、このメソッドが役に立ちます。また、値丸めを即座に行うため、
      例えば以下のように、入力値に値丸めを行わないために合計値にゼロの
      加算を追加するだけで結果が変わってしまうといった、現在の精度より
      も細かい値の影響が紛れ込む問題を防げるという恩恵もあります。以下
      の例は、丸められていない入力を使うということは和にゼロを加えると
      結果が変わり得るという見本です:

         >>> getcontext().prec = 3
         >>> Decimal('3.4445') + Decimal('1.0023')
         Decimal('4.45')
         >>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023')
         Decimal('4.44')

      このメソッドは IBM 仕様の to-number 演算を実装したものです。引数
      が文字列の場合、前や後ろに余計な空白を付けたり、アンダースコアを
      含めたりすることは許されません。

   create_decimal_from_float(f, /)

      浮動小数点数 *f* から新しい Decimal インスタンスを生成しますが、
      *self* をコンテキストとして丸めます。 "Decimal.from_float()" ク
      ラスメソッドとは違い、変換にコンテキストの精度、丸めメソッド、フ
      ラグ、そしてトラップが適用されます。

         >>> context = Context(prec=5, rounding=ROUND_DOWN)
         >>> context.create_decimal_from_float(math.pi)
         Decimal('3.1415')
         >>> context = Context(prec=5, traps=[Inexact])
         >>> context.create_decimal_from_float(math.pi)
         Traceback (most recent call last):
             ...
         decimal.Inexact: None

      Added in version 3.1.

   Etiny()

      非正規数の演算結果で取り得る最小の指数 "Emin - prec + 1" を返し
      ます。 アンダーフローが起きた場合、指数は "Etiny" に設定されます
      。

   Etop()

      "Emax - prec + 1" に等しい値を返します。

   "Decimal" を使った処理を行う場合、通常は "Decimal" インスタンスを生
   成して、算術演算を適用するというアプローチをとります。演算はアクテ
   ィブなスレッドにおける現在のコンテキストの下で行われます。もう一つ
   のアプローチは、コンテキストのメソッドを使った特定のコンテキスト下
   での計算です。コンテキストのメソッドは "Decimal" クラスのメソッドに
   似ているので、ここでは簡単な説明にとどめます。

   abs(x, /)

      *x* の絶対値を返します。

   add(x, y, /)

      *x* と *y* の和を返します。

   canonical(x, /)

      同じ Decimal オブジェクト *x* を返します。

   compare(x, y, /)

      *x* と *y* を数値として比較します。

   compare_signal(x, y, /)

      二つの演算対象の値を数値として比較します。

   compare_total(x, y, /)

      二つの演算対象を抽象的な表現を使って比較します。

   compare_total_mag(x, y, /)

      二つの演算対象を抽象的な表現を使い符号を無視して比較します。

   copy_abs(x, /)

      *x* のコピーの符号を 0 にセットして返します。

   copy_negate(x, /)

      *x* のコピーの符号を反転して返します。

   copy_sign(x, y, /)

      *y* から *x* に符号をコピーします。

   divide(x, y, /)

      *x* を *y* で除算した値を返します。

   divide_int(x, y, /)

      *x* を *y* で除算した値を整数に切り捨てて返します。

   divmod(x, y, /)

      二つの数値間の除算を行い、結果の整数部を返します。

   exp(x, /)

      "e ** x" を返します。

   fma(x, y, z, /)

      *x* を *y* 倍したものに *z* を加えて返します。

   is_canonical(x, /)

      *x* が標準的(canonical)ならば "True" を返します。そうでなければ
      "False" です。

   is_finite(x, /)

      *x* が有限ならば "True" を返します。そうでなければ "False" です
      。

   is_infinite(x, /)

      *x* が無限ならば "True" を返します。そうでなければ "False" です
      。

   is_nan(x, /)

      *x* が qNaN か sNaN であれば "True" を返します。そうでなければ
      "False" です。

   is_normal(x, /)

      *x* が通常の数ならば "True" を返します。そうでなければ "False"
      です。

   is_qnan(x, /)

      *x* が無言 NaN であれば "True" を返します。そうでなければ
      "False" です。

   is_signed(x, /)

      *x* が負の数であれば "True" を返します。そうでなければ "False"
      です。

   is_snan(x, /)

      *x* が発信 NaN であれば "True" を返します。そうでなければ
      "False" です。

   is_subnormal(x, /)

      *x* が非正規数であれば "True" を返します。そうでなければ "False"
      です。

   is_zero(x, /)

      *x* がゼロであれば "True" を返します。そうでなければ "False" で
      す。

   ln(x, /)

      *x* の自然対数(底 e の対数)を返します。

   log10(x, /)

      *x* の底 10 の対数を返します。

   logb(x, /)

      演算対象の MSD の大きさの指数部を返します。

   logical_and(x, y, /)

      それぞれの桁に論理演算 *and* を当てはめます。

   logical_invert(x, /)

      *x* の全ての桁を反転させます。

   logical_or(x, y, /)

      それぞれの桁に論理演算 *or* を当てはめます。

   logical_xor(x, y, /)

      それぞれの桁に論理演算 *xor* を当てはめます。

   max(x, y, /)

      二つの値を数値として比較し、大きいほうを返します。

   max_mag(x, y, /)

      値を符号を無視して数値として比較します。

   min(x, y, /)

      二つの値を数値として比較し、小さいほうを返します。

   min_mag(x, y, /)

      値を符号を無視して数値として比較します。

   minus(x, /)

      Python における単項マイナス演算子に対応する演算です。

   multiply(x, y, /)

      *x* と *y* の積を返します。

   next_minus(x, /)

      *x* より小さい最大の表現可能な数を返します。

   next_plus(x, /)

      *x* より大きい最小の表現可能な数を返します。

   next_toward(x, y, /)

      *x* に *y* の方向に向かって最も近い数を返します。

   normalize(x, /)

      *x* をもっとも単純な形にします。

   number_class(x, /)

      *x* のクラスを指し示すものを返します。

   plus(x, /)

      Python における単項のプラス演算子に対応する演算です。コンテキス
      トにおける精度や値丸めを適用するので、等値 (identity) 演算とは *
      違います*。

   power(x, y, modulo=None)

      "x" の "y" 乗を計算します。"modulo" が指定されていればモジュロを
      取ります。

      引数が 2 つの場合、 "x**y" を計算します。"x" が負の場合、 "y" は
      整数でなければなりません。"y" が整数、結果が有限、結果が
      'precision' 桁で正確に表現できる、という条件をすべて満たさない場
      合、結果は不正確になります。結果はコンテキストの丸めモードを使っ
      て丸められます。結果は常に、Python バージョンにおいて正しく丸め
      られます。

      "Decimal(0) ** Decimal(0)" は "InvalidOperation" を発生させます
      。 "InvalidOperation" をトラップしない場合は "Decimal('NaN')" に
      なります。

      バージョン 3.3 で変更: C モジュールは "power()" を適切に丸められ
      た "exp()" および "ln()" 関数によって計算します。結果は well-
      defined ですが、「ほとんどの場合には適切に丸められる」だけです。

      引数が 3 つの場合、 "(x**y) % modulo" を計算します。この 3 引数
      の形式の場合、引数には以下の制限が課せられます。

      * 全ての引数は整数

      * "y" は非負でなければならない

      * "x" と "y" の少なくともどちらかはゼロでない

      * "modulo" は非零で大きくても 'precision' 桁

      "Context.power(x, y, modulo)" で得られる値は "(x**y) % modulo"
      を精度無制限で計算して得られるものと同じ値ですが、より効率的に計
      算されます。結果の指数は "x", "y", "modulo" の指数に関係なくゼロ
      です。この計算は常に正確です。

   quantize(x, y, /)

      *x* に値丸めを適用し、指数を *y* にした値を返します。

   radix()

      単に 10 を返します。何せ十進ですから :)

   remainder(x, y, /)

      整数除算の剰余を返します。

      剰余がゼロでない場合、符号は割られる数の符号と同じになります。

   remainder_near(x, y, /)

      "x - y * n" を返します。ここで *n* は "x / y" の正確な値に一番近
      い整数です (この結果が 0 ならばその符号は *x* の符号と同じです)
      。

   rotate(x, y, /)

      *x* の *y* 回巡回したコピーを返します。

   same_quantum(x, y, /)

      2つの演算対象が同じ指数を持っている場合に "True" を返します。

   scaleb(x, y, /)

      一つめの演算対象の指数部に二つめの値を加えたものを返します。

   shift(x, y, /)

      *x* を *y* 回シフトしたコピーを返します。

   sqrt(x, /)

      非負の数の平方根をコンテキストの精度で求めます。

   subtract(x, y, /)

      *x* と *y* の間の差を返します。

   to_eng_string(x, /)

      文字列に変換します。指数が必要なら工学表記が使われます。

      工学表記法では指数が 3 の倍数になります。 そのため、小数点の左側
      には最大 3 桁の数字が残り、末尾にゼロを 1 つまたは 2 つ追加する
      必要が生じることがあります。

   to_integral_exact(x, /)

      整数に丸めます。

   to_sci_string(x, /)

      数値を科学表記で文字列に変換します。


定数
====

decimal.SPEC_VERSION

   この実装が準拠する汎用十進演算仕様の最新のバージョン。 仕様は
   https://speleotrove.com/decimal/decarith.html を参照してください。

   Added in version 3.15.

次の定数は C モジュールにのみ関係します。 互換性のため、純 Python 版に
も含まれています。

+-----------------------------------+-----------------------+---------------------------------+
|                                   | 32-bit                | 64-bit                          |
|===================================|=======================|=================================|
| decimal.MAX_PREC                  | "425000000"           | "999999999999999999"            |
+-----------------------------------+-----------------------+---------------------------------+
| decimal.MAX_EMAX                  | "425000000"           | "999999999999999999"            |
+-----------------------------------+-----------------------+---------------------------------+
| decimal.MIN_EMIN                  | "-425000000"          | "-999999999999999999"           |
+-----------------------------------+-----------------------+---------------------------------+
| decimal.MIN_ETINY                 | "-849999999"          | "-1999999999999999997"          |
+-----------------------------------+-----------------------+---------------------------------+
| decimal.IEEE_CONTEXT_MAX_BITS     | "256"                 | "512"                           |
+-----------------------------------+-----------------------+---------------------------------+

decimal.HAVE_THREADS

   値は "True" です。現在のPythonは常にスレッドを持っているので、非推
   奨になりました。

   バージョン 3.9 で非推奨.

decimal.HAVE_CONTEXTVAR

   デフォルト値は "True" です。 Python を "--without-decimal-
   contextvar オプションで構成" した場合、C 版はコルーチンローカルでは
   なくスレッドローカルのコンテキストを使い、値は "False" になります。
   コンテキストを入れ子にする一部の状況では、こちらの方がわずかに高速
   です。

   Added in version 3.8.3.


丸めモード
==========

decimal.ROUND_CEILING

   "Infinity" 方向に丸めます。

decimal.ROUND_DOWN

   ゼロ方向に丸めます。

decimal.ROUND_FLOOR

   "-Infinity" 方向に丸めます。

decimal.ROUND_HALF_DOWN

   近い方に、引き分けはゼロ方向に向けて丸めます。

decimal.ROUND_HALF_EVEN

   近い方に、引き分けは偶数整数方向に向けて丸めます。

decimal.ROUND_HALF_UP

   近い方に、引き分けはゼロから遠い方向に向けて丸めます。

decimal.ROUND_UP

   ゼロから遠い方向に丸めます。

decimal.ROUND_05UP

   ゼロ方向に丸めた後の最後の桁が 0 または 5 ならばゼロから遠い方向に
   、そうでなければゼロ方向に丸めます。


シグナル
========

シグナルは、計算中に生じた様々なエラー条件を表現します。各々のシグナル
は一つのコンテキストフラグと一つのトラップイネーブラに対応しています。

コンテキストフラグは、該当するエラー条件に遭遇するたびにセットされます
。演算後にフラグを調べれば、演算に関する情報 (例えば計算が厳密だったか
どうか) がわかります。フラグを調べたら、次の計算を始める前にフラグを全
てクリアするようにしてください。

あるコンテキストのトラップイネーブラがあるシグナルに対してセットされて
いる場合、該当するエラー条件が生じると Python の例外を送出します。例え
ば、 "DivisionByZero" が設定されていると、エラー条件が生じた際に
"DivisionByZero" 例外を送出します。

class decimal.Clamped

   値の表現上の制限に沿わせるために指数部が変更されたことを通知します
   。

   通常、クランプ (clamp) は、指数部がコンテキストにおける指数桁の制限
   値 "Emin" および "Emax" を越えた場合に発生します。可能な場合には、
   係数部にゼロを加えた表現に合わせて指数部を減らします。

class decimal.DecimalException

   他のシグナルの基底クラスで、 "ArithmeticError" のサブクラスです。

class decimal.DivisionByZero

   有限値をゼロで除算したときのシグナルです。

   除算やモジュロ除算、数を負の値で累乗した場合に起きることがあります
   。このシグナルをトラップしない場合、演算結果は "Infinity" または
   "-Infinity" になり、その符号は演算に使った入力に基づいて決まります
   。

class decimal.Inexact

   値の丸めによって演算結果から厳密さが失われたことを通知します。

   このシグナルは値丸め操作中にゼロでない桁を無視した際に生じます。演
   算結果は値丸め後の値です。シグナルのフラグやトラップは、演算結果の
   厳密さが失われたことを検出するために使えるだけです。

class decimal.InvalidOperation

   無効な演算が実行されたことを通知します。

   ユーザが有意な演算結果にならないような操作を要求したことを示します
   。このシグナルをトラップしない場合、 "NaN" を返します。このシグナル
   の発生原因として考えられるのは、以下のような状況です:

      Infinity - Infinity
      0 * Infinity
      Infinity / Infinity
      x % 0
      Infinity % x
      sqrt(-x) and x > 0
      0 ** 0
      x ** (non-integer)
      x ** Infinity

class decimal.Overflow

   数値オーバフローを示すシグナルです。

   このシグナルは、値丸めを行った後の指数部が "Context.Emax" より大き
   いことを示します。シグナルをトラップしない場合、演算結果は値丸めの
   モードにより、表現可能な最大の数値になるように内側へ引き込んで丸め
   を行った値か、 "Infinity" になるように外側に丸めた値のいずれかにな
   ります。いずれの場合も、 "Inexact" および "Rounded" が同時にシグナ
   ルされます。

class decimal.Rounded

   情報が全く失われていない場合も含み、値丸めが起きたときのシグナルで
   す。

   このシグナルは、値丸めによって桁がなくなると常に発生します。なくな
   った桁がゼロ (例えば "5.00" を丸めて "5.0" になった場合) であっても
   です。このシグナルをトラップしなければ、演算結果をそのまま返します
   。このシグナルは有効桁数の減少を検出する際に使います。

class decimal.Subnormal

   値丸めを行う前に指数部が "Emin" より小さかったことを示すシグナルで
   す。

   演算結果が微小である場合 (指数が小さすぎる場合) に発生します。この
   シグナルをトラップしなければ、演算結果をそのまま返します。

class decimal.Underflow

   演算結果が値丸めによってゼロになった場合に生じる数値アンダフローで
   す。

   演算結果が微小なため、値丸めによってゼロになった場合に発生します。
   "Inexact" および "Subnormal" シグナルも同時に発生します。

class decimal.FloatOperation

   float と Decimal の混合の厳密なセマンティクスを有効にします。

   シグナルがトラップされなかった場合 (デフォルト)、"Decimal" コンスト
   ラクタ、 "create_decimal()" 、およびすべての比較演算子において
   float と Decimal の混合が許されます。変換も比較も正確です。コンテキ
   ストフラグ内に "FloatOperation" を設定することで、混合操作は現れる
   たびに暗黙に記録されます。 "from_float()" や
   "create_decimal_from_float()" による明示的な変換はフラグを設定しま
   せん。

   そうでなければ (シグナルがトラップされれば)、等価性比較および明示的
   な変換のみが静かにに行われ、その他の混合演算は "FloatOperation" を
   送出します。

これらのシグナルの階層構造をまとめると、以下の表のようになります:

   exceptions.ArithmeticError(exceptions.Exception)
       DecimalException
           Clamped
           DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
           Inexact
               Overflow(Inexact, Rounded)
               Underflow(Inexact, Rounded, Subnormal)
           InvalidOperation
           Rounded
           Subnormal
           FloatOperation(DecimalException, exceptions.TypeError)


浮動小数点に関する注意点
========================


精度を上げて丸め誤差を抑制する
------------------------------

十進浮動小数点数を使うと、十進数表現による誤差を抑制できます ("0.1" を
正確に表現できるようになります); しかし、ゼロでない桁が一定の精度を越
えている場合には、演算によっては依然として値丸めによる誤差を引き起こし
ます。

ほぼ相殺する量を加減算すると、丸め誤差の影響が増幅され、桁落ちが生じる
ことがあります。 Knuth は、精度の足りない浮動小数点演算の丸めによって
、加算の結合法則や分配法則が成り立たなくなる 2 つの示唆に富む例を挙げ
ています:

   # Seminumerical Algorithms の 4.2.2 節の例。
   >>> from decimal import Decimal, getcontext
   >>> getcontext().prec = 8

   >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
   >>> (u + v) + w
   Decimal('9.5111111')
   >>> u + (v + w)
   Decimal('10')

   >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
   >>> (u*v) + (u*w)
   Decimal('0.01')
   >>> u * (v+w)
   Decimal('0.0060000')

"decimal" モジュールでは、桁落ちを避けるのに十分な精度まで拡張すること
で、これらの等式を成り立たせることができます:

   >>> getcontext().prec = 20
   >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
   >>> (u + v) + w
   Decimal('9.51111111')
   >>> u + (v + w)
   Decimal('9.51111111')
   >>>
   >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
   >>> (u*v) + (u*w)
   Decimal('0.0060000')
   >>> u * (v+w)
   Decimal('0.0060000')


特殊値
------

"decimal" モジュールの数体系には、"NaN"、"sNaN"、"-Infinity"、
"Infinity"、そして 2 つのゼロ "+0" と "-0" という特殊な値があります。

無限大 (Infinity) は "Decimal('Infinity')" で直接構築できます。また、
"DivisionByZero" をトラップせずにゼロで除算を行った場合にも出てきます
。同様に、 "Overflow" シグナルをトラップしなければ、表現可能な最大の数
値の制限を越えた値を丸めたときに出てきます。

無限大には符号があり (アフィン: affine であり)、算術演算に使用でき、非
常に巨大で不確定の(indeterminate)値として扱われます。例えば、無限大に
何らかの定数を加算すると、演算結果は別の無限大になります。

演算によっては結果が不確定になるものがあり、 "NaN" を返します。ただし
、 "InvalidOperation" シグナルをトラップするようになっていれば例外を送
出します。例えば、 "0/0" は "NaN" を返します。 "NaN" は「非数値 (not a
number)」を表します。このような "NaN" は暗黙のうちに生成され、一度生成
されるとそれを他の計算にも流れてゆき、関係する個々の演算全てが個別の
"NaN" を返すようになります。この挙動は、たまに入力値が欠けるような状況
で一連の計算を行う際に便利です --- 特定の計算に対しては無効な結果を示
すフラグを立てつつ計算を進められるからです。

一方、 "NaN" の変種である "sNaN" は関係する全ての演算で演算後にシグナ
ルを送出します。 "sNaN" は、無効な演算結果に対して特別な処理を行うため
に計算を停止する必要がある場合に便利です。

Python の比較演算は "NaN" が関わってくると少し驚くようなことがあります
。等価性のテストの一方の対象が無言または発信 "NaN" である場合いつでも
"False" を返し(たとえ "Decimal('NaN')==Decimal('NaN')" でも)、一方で不
等価をテストするといつでも "True" を返します。二つの Decimal を "<",
"<=", ">" または ">=" を使って比較する試みは一方が "NaN" である場合に
は "InvalidOperation" シグナルを送出し、このシグナルをトラップしなけれ
ば結果は "False" に終わります。汎用十進演算仕様は直接の比較の振る舞い
について定めていないことに注意しておきましょう。ここでの "NaN" が関係
する比較ルールは IEEE 854 標準から持ってきました (section 5.7 の Table
3 を見て下さい)。厳格に標準遵守を貫くなら、 "compare()" および
"compare_signal()" メソッドを代わりに使いましょう。

アンダフローの起きた計算は、符号付きのゼロ (signed zero) を返すことが
あります。符号は、より高い精度で計算を行った結果の符号と同じになります
。符号付きゼロの大きさはやはりゼロなので、正のゼロと負のゼロは等しいと
みなされ、符号は単なる参考にすぎません。

表現が異なっても値が等しいこの 2 つの符号付きゼロに加え、精度は異なっ
ても値は等しいゼロの表現がさまざまにあります。 これには少し慣れが必要
です。 正規化された浮動小数点表現に慣れていると、次の計算がゼロに等し
い値を返すことは一見して分からないかもしれません:

>>> 1 / Decimal('Infinity')
Decimal('0E-1000026')


スレッドを使った処理
====================

関数 "getcontext()" は、スレッド毎に別々の "Context" オブジェクトにア
クセスします。別のスレッドコンテキストを持つということは、複数のスレッ
ドが互いに影響を及ぼさずに ("getcontext().prec=10" のような) 変更を適
用できるということです。

同様に、"setcontext()" 関数は自動的に引数のコンテキストを現在のスレッ
ドのコンテキストに設定します。

"setcontext()" を呼ばずに "getcontext()" を呼ぶと、"getcontext()" は現
在のスレッドで使う新しいコンテキストを自動的に作成します。 新しいコン
テキストオブジェクトのデフォルト値は "decimal.DefaultContext" オブジェ
クトから設定されます。

"sys.flags.thread_inherit_context" フラグは、新しいスレッドのコンテキ
ストに影響します。 フラグが偽なら、新しいスレッドは空のコンテキストで
開始します。 この場合、"getcontext()" を呼ぶと新しいコンテキストオブジ
ェクトを作成し、*DefaultContext* のデフォルト値を使います。 フラグが真
なら、新しいスレッドは "threading.Thread.start()" の呼び出し元のコンテ
キストのコピーで開始します。

アプリケーション全体で各スレッドが同じデフォルト値を使うようにするには
、*DefaultContext* オブジェクトを直接変更してください。 スレッド間で
"getcontext()" の呼び出しが競合しないように、どのスレッドも開始する *
前に* 変更してください。 例えば次のようにします。

   # これから起動する全スレッドに対するアプリケーション共通のデフォルト値を設定します
   DefaultContext.prec = 12
   DefaultContext.rounding = ROUND_DOWN
   DefaultContext.traps = ExtendedContext.traps.copy()
   DefaultContext.traps[InvalidOperation] = 1
   setcontext(DefaultContext)

   # その後、スレッドを開始できます
   t1.start()
   t2.start()
   t3.start()
    . . .


レシピ
======

"Decimal" クラスの利用を実演している例をいくつか示します。これらはユー
ティリティ関数としても利用できます:

   def moneyfmt(value, places=2, curr='', sep=',', dp='.',
                pos='', neg='-', trailneg=''):
       """Convert Decimal to a money formatted string.

       places:  required number of places after the decimal point
       curr:    optional currency symbol before the sign (may be blank)
       sep:     optional grouping separator (comma, period, space, or blank)
       dp:      decimal point indicator (comma or period)
                only specify as blank when places is zero
       pos:     optional sign for positive numbers: '+', space or blank
       neg:     optional sign for negative numbers: '-', '(', space or blank
       trailneg:optional trailing minus indicator:  '-', ')', space or blank

       >>> d = Decimal('-1234567.8901')
       >>> moneyfmt(d, curr='$')
       '-$1,234,567.89'
       >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')
       '1.234.568-'
       >>> moneyfmt(d, curr='$', neg='(', trailneg=')')
       '($1,234,567.89)'
       >>> moneyfmt(Decimal(123456789), sep=' ')
       '123 456 789.00'
       >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')
       '<0.02>'

       """
       q = Decimal(10) ** -places      # 2 places --> '0.01'
       sign, digits, exp = value.quantize(q).as_tuple()
       result = []
       digits = list(map(str, digits))
       build, next = result.append, digits.pop
       if sign:
           build(trailneg)
       for i in range(places):
           build(next() if digits else '0')
       if places:
           build(dp)
       if not digits:
           build('0')
       i = 0
       while digits:
           build(next())
           i += 1
           if i == 3 and digits:
               i = 0
               build(sep)
       build(curr)
       build(neg if sign else pos)
       return ''.join(reversed(result))

   def pi():
       """Compute Pi to the current precision.

       >>> print(pi())
       3.141592653589793238462643383

       """
       getcontext().prec += 2  # extra digits for intermediate steps
       three = Decimal(3)      # substitute "three=3.0" for regular floats
       lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24
       while s != lasts:
           lasts = s
           n, na = n+na, na+8
           d, da = d+da, da+32
           t = (t * n) / d
           s += t
       getcontext().prec -= 2
       return +s               # unary plus applies the new precision

   def exp(x):
       """Return e raised to the power of x.  Result type matches input type.

       >>> print(exp(Decimal(1)))
       2.718281828459045235360287471
       >>> print(exp(Decimal(2)))
       7.389056098930650227230427461
       >>> print(exp(2.0))
       7.38905609893
       >>> print(exp(2+0j))
       (7.38905609893+0j)

       """
       getcontext().prec += 2
       i, lasts, s, fact, num = 0, 0, 1, 1, 1
       while s != lasts:
           lasts = s
           i += 1
           fact *= i
           num *= x
           s += num / fact
       getcontext().prec -= 2
       return +s

   def cos(x):
       """Return the cosine of x as measured in radians.

       The Taylor series approximation works best for a small value of x.
       For larger values, first compute x = x % (2 * pi).

       >>> print(cos(Decimal('0.5')))
       0.8775825618903727161162815826
       >>> print(cos(0.5))
       0.87758256189
       >>> print(cos(0.5+0j))
       (0.87758256189+0j)

       """
       getcontext().prec += 2
       i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1
       while s != lasts:
           lasts = s
           i += 2
           fact *= i * (i-1)
           num *= x * x
           sign *= -1
           s += num / fact * sign
       getcontext().prec -= 2
       return +s

   def sin(x):
       """Return the sine of x as measured in radians.

       The Taylor series approximation works best for a small value of x.
       For larger values, first compute x = x % (2 * pi).

       >>> print(sin(Decimal('0.5')))
       0.4794255386042030002732879352
       >>> print(sin(0.5))
       0.479425538604
       >>> print(sin(0.5+0j))
       (0.479425538604+0j)

       """
       getcontext().prec += 2
       i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1
       while s != lasts:
           lasts = s
           i += 2
           fact *= i * (i-1)
           num *= x * x
           sign *= -1
           s += num / fact * sign
       getcontext().prec -= 2
       return +s


Decimal FAQ
===========

Q: "decimal.Decimal('1234.5')" と入力するのは面倒です。 対話型インター
プリタを使うときに入力を減らす方法はありますか?

A: コンストラクタを 1 文字に省略して使う人もいます:

>>> D = decimal.Decimal
>>> D('1.23') + D('3.45')
Decimal('4.68')

Q: 小数点以下 2 桁を扱う固定小数点のアプリケーションで、桁数が多くて丸
める必要がある入力があります。 一方、余分な桁がないはずなので検証が必
要な入力もあります。 どのメソッドを使えばよいですか?

A: "quantize()" メソッドは小数点以下の桁数を固定して丸めます。
"Inexact" トラップを設定すれば、検証にも使えます:

>>> TWOPLACES = Decimal(10) ** -2       # same as Decimal('0.01')

>>> # Round to two places
>>> Decimal('3.214').quantize(TWOPLACES)
Decimal('3.21')

>>> # Validate that a number does not exceed two places
>>> Decimal('3.21').quantize(TWOPLACES, context=Context(traps=[Inexact]))
Decimal('3.21')

>>> Decimal('3.214').quantize(TWOPLACES, context=Context(traps=[Inexact]))
Traceback (most recent call last):
   ...
Inexact: None

Q: 小数点以下 2 桁の有効な入力を得た後、アプリケーション全体でこの条件
を保つにはどうすればよいですか?

A: 加算、減算、整数との乗算などは、自動的に小数点の位置を保ちます。 除
算や整数以外との乗算などは小数点以下の桁数を変えるので、その後に
"quantize()" を適用する必要があります:

>>> a = Decimal('102.72')           # Initial fixed-point values
>>> b = Decimal('3.17')
>>> a + b                           # Addition preserves fixed-point
Decimal('105.89')
>>> a - b
Decimal('99.55')
>>> a * 42                          # So does integer multiplication
Decimal('4314.24')
>>> (a * b).quantize(TWOPLACES)     # Must quantize non-integer multiplication
Decimal('325.62')
>>> (b / a).quantize(TWOPLACES)     # And quantize division
Decimal('0.03')

固定小数点のアプリケーションを開発する際は、 "quantize()" の段階を扱う
関数を定義しておくと便利です:

>>> def mul(x, y, fp=TWOPLACES):
...     return (x * y).quantize(fp)
...
>>> def div(x, y, fp=TWOPLACES):
...     return (x / y).quantize(fp)

>>> mul(a, b)                       # Automatically preserve fixed-point
Decimal('325.62')
>>> div(b, a)
Decimal('0.03')

Q: 同じ値を表す方法がたくさんあります。 "200"、"200.000"、"2E2"、
".02E+4" はすべて、精度は異なりますが同じ値です。 これらを 1 つの分か
りやすい標準形に変換する方法はありますか?

A: "normalize()" メソッドは、等しい値をすべて 1 つの代表値に変換します
:

>>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
>>> [v.normalize() for v in values]
[Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')]

Q: 計算のどの段階で丸めが行われますか?

A: 計算の *後に* 行われます。 十進演算仕様の考え方では、数値は正確なも
のとみなし、現在のコンテキストとは無関係に作成します。 現在のコンテキ
ストより高い精度を持つこともあります。 計算はこれらの正確な入力を使っ
て行い、その *結果* に丸めなどのコンテキストの操作を適用します。

   >>> getcontext().prec = 5
   >>> pi = Decimal('3.1415926535')   # More than 5 digits
   >>> pi                             # All digits are retained
   Decimal('3.1415926535')
   >>> pi + 0                         # Rounded after an addition
   Decimal('3.1416')
   >>> pi - Decimal('0.00005')        # Subtract unrounded numbers, then round
   Decimal('3.1415')
   >>> pi + 0 - Decimal('0.00005')    # Intermediate values are rounded
   Decimal('3.1416')

Q: 10 進数の中には常に指数表記で表示される値があります。 指数を使わな
い表現にする方法はありますか?

A: 値によっては、係数の有効桁数を表現するには指数表記が必要です。 例え
ば "5.0E+3" を "5000" と表しても値は変わりませんが、元の数値の有効桁数
が 2 桁であることは示せません。

もしアプリケーションが有効数字の追跡を等閑視するならば、指数部や末尾の
ゼロを取り除き、有効数字を忘れ、しかし値を変えずにおくことは容易です:

>>> def remove_exponent(d):
...     return d.quantize(Decimal(1)) if d == d.to_integral() else d.normalize()

>>> remove_exponent(Decimal('5E+3'))
Decimal('5000')

Q: 通常の float を "Decimal" に変換する方法はありますか?

A: はい。 どの 2 進浮動小数点数も Decimal で正確に表現できます。 ただ
し、正確な変換には直感的に思う以上の精度が必要になることがあります:

   >>> Decimal(math.pi)
   Decimal('3.141592653589793115997963468544185161590576171875')

Q: 複雑な計算で、精度不足や丸めの異常によって誤った結果が出ていないか
を確認するにはどうすればよいですか?

A: decimal モジュールを使うと、結果を簡単に検証できます。 より高い精度
とさまざまな丸めモードで再計算するのがよい方法です。 結果が大きく異な
る場合は、精度の不足、丸めモードの問題、条件の悪い入力、または数値的に
不安定なアルゴリズムが疑われます。

Q: コンテキストの精度は演算結果に適用され、入力には適用されないことが
分かりました。 精度の異なる値を混ぜて使うときに、注意することはありま
すか?

A: はい。 原則としてすべての値は正確なものとみなし、それらに対する算術
演算も正確に行います。 丸めるのは結果だけです。 入力については、入力し
たとおりの値が得られるという利点があります。 一方、入力が丸められてい
ないことを忘れると、結果が奇妙に見えるという欠点があります:

   >>> getcontext().prec = 3
   >>> Decimal('3.104') + Decimal('2.104')
   Decimal('5.21')
   >>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104')
   Decimal('5.20')

解決策は、精度を増やすか、単項プラス演算子を使って入力の丸めを強制する
ことです:

   >>> getcontext().prec = 3
   >>> +Decimal('1.23456789')      # 単項プラスで丸めます
   Decimal('1.23')

もしくは、入力を "Context.create_decimal()" を使って生成時に丸めてしま
うこともできます:

>>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
Decimal('1.2345')

Q: CPython の実装は大きな数でも高速ですか?

A: はい。 CPython と PyPy3 の実装では、decimal モジュールの C/CFFI 版
に、任意精度で正しく丸められる 10 進浮動小数点演算の高速ライブラリ
libmpdec を組み込んでいます [1]。 "libmpdec" は中程度の大きさの数に
Karatsuba 法による乗算 を、非常に大きな数に 数論変換 を使います。

正確な任意精度演算を行うには、コンテキストを調整する必要があります。
"Emin" と "Emax" は常に範囲が最大になる値に設定し、"clamp" は常に 0 (
デフォルト) にしてください。 "prec" の設定には少し注意が必要です。

多倍長整数の演算を試す最も簡単な方法は、"prec" にも最大値を使うことで
す [2]。

   >>> setcontext(Context(prec=MAX_PREC, Emax=MAX_EMAX, Emin=MIN_EMIN))
   >>> x = Decimal(2) ** 256
   >>> x / 128
   Decimal('904625697166532776746648320380374280103671755200316906558262375061821325312')

結果が不正確な場合、64 ビットプラットフォームでは "MAX_PREC" が大きす
ぎるため、利用可能なメモリが足りなくなります。

   >>> Decimal(1) / 3
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   MemoryError

メモリの過剰割り当てを行うシステム (Linux など) では、利用可能な RAM
の容量に合わせて "prec" を調整する方が適切です。 RAM が 8 GB あり、そ
れぞれ最大 500 MB の演算対象を同時に 10 個使うことを想定しているとしま
す。

   >>> import sys
   >>>
   >>> # 1 つの演算対象が 8 バイトのワード単位で 500 MB を使う場合の最大桁数
   >>> # 1 ワードは 19 桁 (32 ビットビルドでは 4 バイトで 9 桁):
   >>> maxdigits = 19 * ((500 * 1024**2) // 8)
   >>>
   >>> # 動作を確認します:
   >>> c = Context(prec=maxdigits, Emax=MAX_EMAX, Emin=MIN_EMIN)
   >>> c.traps[Inexact] = True
   >>> setcontext(c)
   >>>
   >>> # 利用可能な精度を 9 で埋めます:
   >>> x = Decimal(0).logical_invert() * 9
   >>> sys.getsizeof(x)
   524288112
   >>> x + 2
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
     decimal.Inexact: [<class 'decimal.Inexact'>]

すべての計算が正確になるはずなら、一般に (特に過剰割り当てを行わないシ
ステムでは)、さらに厳密な上限を見積もり、"Inexact" トラップを設定する
ことを推奨します。

[1] Added in version 3.3.

[2] バージョン 3.9 で変更: この方法は、指数が整数でないべき乗を除くす
    べての正確な結果で使えるようになりました。
