Skip to main content

9.4. decimal —十进制定点和浮点运算

源代码: Lib/decimal.py


decimal 模块支持快速正确舍入的十进制浮点运算。它相对于 float 数据类型提供了几个优点:

  • 十进制“是基于一个浮点模型,它是为人们设计的,并且必须有一个最重要的指导原则 - 计算机必须提供一个算法,与人们在学校学习的算法一样。 - 摘自十进制算术规范。

  • 十进制数可以精确表示。相反,诸如 1.12.2 的数字在二进制浮点中没有精确表示。最终用户通常不会期望 1.1 + 2.2 显示为 3.3000000000000003,因为它与二进制浮点一样。

  • 精确性转化为算术。在十进制浮点中,0.1 + 0.1 + 0.1 - 0.3 正好等于零。在二进制浮点中,结果为 5.5511151231257827e-017。当接近零时,差异阻止可靠的相等测试,并且差异可累积。因此,在具有严格相等不变量的会计应用程序中,十进制是首选。

  • 十进制模块包含重要位置的概念,因此 1.30 + 1.202.50。尾随零被保留以指示重要性。这是货币应用的习惯表述。对于乘法,“教科书”方法使用被乘数中的所有数字。例如,1.3 * 1.2 给出 1.56,而 1.30 * 1.20 给出 1.5600

  • 与基于硬件的二进制浮点不同,十进制模块具有用户可改变的精度(默认为28个位置),其可以与给定问题所需的一样大:

    >>> from decimal import *
    >>> getcontext().prec = 6
    >>> Decimal(1) / Decimal(7)
    Decimal('0.142857')
    >>> getcontext().prec = 28
    >>> Decimal(1) / Decimal(7)
    Decimal('0.1428571428571428571428571429')
    
  • 二进制和十进制浮点都是按照已发布的标准来实现的。虽然内置浮点类型只暴露其一小部分功能,但十进制模块公开了标准的所有必需部分。当需要时,程序员可以完全控制舍入和信号处理。这包括通过使用异常来阻止任何不精确操作来强制执行精确算术的选项。

  • 十进制模块被设计为支持“没有偏见,精确的非舍入十进制运算(有时称为定点运算)和舍入浮点运算。 - 摘自十进制算术规范。

模块设计围绕三个概念:十进制数,算术上下文和信号。

十进制数是不可变的。它具有符号,系数数字和指数。为了保留重要性,系数数字不会截断尾随零。小数还包括特殊值,例如 Infinity-InfinityNaN。该标准还区分 -0+0

算术的上下文是指定精度,舍入规则,指数限制,指示操作结果的标志以及确定信号是否被视为异常的陷阱使能器的环境。舍入选项包括 ROUND_CEILINGROUND_DOWNROUND_FLOORROUND_HALF_DOWNROUND_HALF_EVENROUND_HALF_UPROUND_UPROUND_05UP

信号是在计算过程中出现的一组异常条件。根据应用程序的需要,信号可能会被忽略,被视为信息,或被视为异常。十进制模块中的信号是:ClampedInvalidOperationDivisionByZeroInexactRoundedSubnormalOverflowUnderflowFloatOperation

对于每个信号,有一个标志和一个陷阱使能器。当遇到信号时,其标志设置为1,然后,如果陷阱使能器设置为1,则引发异常。标志是粘性的,因此用户需要在监视计算之前重置它们。

参见

9.4.1. 快速入门教程

通常开始使用小数是导入模块,使用 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       # Set a new precision

小数实例可以从整数,字符串,浮点或元组构造。从整数或浮点构造将执行该整数或浮点值的精确转换。小数包括特殊值,例如 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 信号被捕获,构造函数中的小数和浮点数的意外混合或排序比较引发异常:

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

3.3 新版功能.

新十进制的重要性仅由输入的位数决定。上下文精度和舍入仅在算术运算期间起作用。

>>> 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版本的内部限制,构造一个小数将提高 InvalidOperation:

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

在 3.3 版更改.

小数与Python的其余大部分交互良好。这里是一个小十进制浮点飞马戏:

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

并且一些数学函数也可用于十进制:

>>> 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 模块提供两个即用标准上下文,BasicContextExtendedContext。前者对于调试特别有用,因为许多陷阱已启用:

>>> 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。使用上下文集和小数创建,大部分程序操作数据没有不同于其他Python数值类型。

9.4.2. 小数对象

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

基于 value 构造新的 Decimal 对象。

value 可以是整数,字符串,元组,float 或另一个 Decimal 对象。如果没有给出 value,则返回 Decimal('0')。如果 value 是一个字符串,它应该符合十进制数字字符串语法,前导和尾随的空白字符,以及下划线,删除:

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十进制数字。这些包括来自各种其他字母的十进制数字(例如,Arabic-Indic和Devanāgarī数字)以及全宽数字 '\uff10''\uff19'

如果 valuetuple,它应该有三个分量,一个符号(0 为正或 1 为负),tuple 的数字和整数指数。例如,Decimal((0, (1, 4, 1, 4), -3)) 返回 Decimal('1.414')

如果 valuefloat,则二进制浮点值被无损地转换为其确切的十进制等效值。此转换通常需要53位或更多位数的精度。例如,Decimal(float('1.1')) 转化为 Decimal('1.100000000000000088817841970012523233890533447265625')

context 精度不影响存储多少位数。这完全由 value 中的数字位数决定。例如,Decimal('3.00000') 记录所有五个零,即使上下文精度只有三个。

context 参数的目的是确定如果 value 是一个格式错误的字符串,该怎么办。如果上下文陷阱 InvalidOperation,则引发异常;否则,构造函数返回值为 NaN 的新十进制。

一旦构造,Decimal 对象是不可变的。

在 3.2 版更改: 现在允许构造函数的参数是 float 实例。

在 3.3 版更改: 如果设置了 FloatOperation 陷阱,则 float 参数引发异常。默认情况下,陷阱关闭。

在 3.6 版更改: 允许使用下划线进行分组,如在代码中使用积分和浮点文本。

十进制浮点对象与其他内置数字类型(如 floatint)共享许多属性。所有通常的数学运算和特殊方法都适用。同样,小数对象可以被复制,腌制,打印,用作字典键,用作集元素,比较,排序和强制转换为另一种类型(如 floatint)。

在十进制对象上的算术和整数和浮点上的算术之间存在一些小的差异。当余数运算符 % 应用于十进制对象时,结果的符号是 dividend 的符号,而不是除数的符号:

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

整数除法运算符 // 类似地运行,返回真实商的整数部分(截断到零)而不是其底部,以便保持通常的身份 x == (x // y) * y + x % y:

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

%// 操作符分别实现在说明书中描述的 remainderdivide-integer 操作。

十进制对象通常不能与浮点或 fractions.Fraction 的实例在算术运算中组合:例如,向 float 添加 Decimal 的尝试将产生 TypeError。但是,可以使用Python的比较运算符来比较 Decimal 实例 x 和另一个 y。这避免了在不同类型的数字之间进行等式比较时的混淆结果。

在 3.2 版更改: 现在完全支持 Decimal 实例和其他数字类型之间的混合类型比较。

除了标准的数字属性,十进制浮点对象还有一些专门的方法:

adjusted()

在移出系数的最右边数字后,返回调整后的指数,直到只剩下前导数字:Decimal('321e+5').adjusted() 返回7。用于确定相对于小数点的最高有效位的位置。

as_integer_ratio()

将代表给定 Decimal 实例的整数对 (n, d) 返回为分数,以最低项和正分母:

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

转换是确切的。在NaN上提高无穷大和ValueError上的OverflowError。

3.6 新版功能.

as_tuple()

返回 named tuple 表示的数字:DecimalTuple(sign, digits, exponent)

canonical()

返回参数的规范编码。目前,Decimal 实例的编码始终是规范的,因此此操作将不变地返回其参数。

compare(other, context=None)

比较两个小数实例的值。 compare() 返回一个十进制实例,如果任一操作数是NaN,则结果是NaN:

a or b is a NaN  ==> Decimal('NaN')
a < b            ==> Decimal('-1')
a == b           ==> Decimal('0')
a > b            ==> Decimal('1')
compare_signal(other, context=None)

该操作与 compare() 方法相同,除了所有NaNs信号。也就是说,如果两个操作数都不是信令NaN,则任何安静的NaN操作数被视为是信令NaN。

compare_total(other, context=None)

使用它们的抽象表示而不是它们的数值比较两个操作数。与 compare() 方法类似,但结果给出了 Decimal 实例的总排序。具有相同数值但不同表示的两个 Decimal 实例在此排序中比较不等:

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

安静和信令NaN也包括在总排序中。如果两个操作数具有相同的表示,则该函数的结果是 Decimal('0');如果第一操作数在总顺序中比第二操作数低则是 Decimal('-1');如果第一操作数在总顺序中高于第二操作数,则是 Decimal('1')。有关总订单的详细信息,请参阅规格。

该操作不受上下文的影响,并且是安静的:没有标志被改变并且不执行舍入。作为例外,如果第二个操作数无法完全转换,C版本可能会引发InvalidOperation。

compare_total_mag(other, context=None)

使用它们的抽象表示比较两个操作数,而不是像在 compare_total() 中那样使用它们的值,但是忽略每个操作数的符号。 x.compare_total_mag(y) 相当于 x.copy_abs().compare_total(y.copy_abs())

该操作不受上下文的影响,并且是安静的:没有标志被改变并且不执行舍入。作为例外,如果第二个操作数无法完全转换,C版本可能会引发InvalidOperation。

conjugate()

只是返回self,这个方法只是符合十进制规范。

copy_abs()

返回参数的绝对值。此操作不受上下文的影响,并且是安静的:没有标志被改变并且不执行舍入。

copy_negate()

返回参数的否定。此操作不受上下文的影响,并且是安静的:没有标志被改变并且不执行舍入。

copy_sign(other, context=None)

返回第一个操作数的副本,其符号设置为与第二个操作数的符号相同。例如:

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

该操作不受上下文的影响,并且是安静的:没有标志被改变并且不执行舍入。作为例外,如果第二个操作数无法完全转换,C版本可能会引发InvalidOperation。

exp(context=None)

返回给定数字处的(自然)指数函数 e**x 的值。使用 ROUND_HALF_EVEN 舍入模式正确舍入结果。

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

将float转换为十进制数的类方法。

注意 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')

3.1 新版功能.

fma(other, third, context=None)

融合乘法。返回self*other+third,没有舍入的中间乘积self*other。

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

如果参数是规范的,则返回 True,否则返回 False。目前,Decimal 实例始终是规范的,因此此操作总是返回 True

is_finite()

如果参数是有限数则返回 True,如果参数是无穷大或NaN,则返回 False

is_infinite()

如果参数是正或负无穷大,则返回 True,否则返回 False

is_nan()

返回 True 如果参数是(安静或信令)NaN和 False 否则。

is_normal(context=None)

如果参数是 normal 有限数,则返回 True。如果参数为零,子正常,无限或NaN,则返回 False

is_qnan()

如果参数是安静的NaN,则返回 True,否则返回 False

is_signed()

如果参数具有负号,则返回 True,否则返回 False。注意零和NaN都可以携带迹象。

is_snan()

如果参数是信令NaN,则返回 True,否则返回 False

is_subnormal(context=None)

如果参数是低于正常,则返回 True,否则返回 False

is_zero()

如果参数为(正或负)零,则返回 True,否则返回 False

ln(context=None)

返回操作数的自然(基本e)对数。使用 ROUND_HALF_EVEN 舍入模式对结果进行正确舍入。

log10(context=None)

返回操作数的十进制对数。使用 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)

通过剥离最右边的后零并将任何等于 Decimal('0') 的结果转换为 Decimal('0e0') 来标准化数字。用于为等价类的属性生成规范值。例如,Decimal('32.100')Decimal('0.321000e+2') 都归一化为等效值 Decimal('32.1')

number_class(context=None)

返回描述操作数的 class 的字符串。返回的值是以下十个字符串之一。

  • "-Infinity",表示操作数是负无穷大。

  • "-Normal",表示操作数是负正常数。

  • "-Subnormal",表示操作数为负和低于正常。

  • "-Zero",表示操作数为负零。

  • "+Zero",表示操作数是正零。

  • "+Subnormal",表示操作数为正和亚正常。

  • "+Normal",表示操作数是正的正数。

  • "+Infinity",表示操作数是正无穷大。

  • "NaN",表示操作数是一个安静的NaN(不是数字)。

  • "sNaN",表示操作数是信令NaN。

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

舍入后返回等于第一个操作数的值,并具有第二个操作数的指数。

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

与其他操作不同,如果量化操作之后的系数的长度将大于精度,则用信号通知 InvalidOperation。这保证,除非有错误条件,量化指数总是等于右手操作数的指数。

也不像其他操作,量化从来没有信号下溢,即使结果是低于正常和不精确。

如果第二操作数的指数大于第一操作数的指数,则舍入可能是必要的。在这种情况下,舍入模式由给定的 rounding 参数确定,否则由给定的 context 参数确定;如果没有给出参数,则使用当前线程的上下文的舍入模式。

当生成的指数大于 Emax 或小于 Etiny 时,将返回错误。

radix()

返回 Decimal(10),其中 Decimal 类执行其所有算术的基数(基数)。包括与规格的兼容性。

remainder_near(other, context=None)

返回剩余部分由 self 除以 other。这与 self % other 的不同之处在于,选择余数的符号以使其绝对值最小。更精确地,返回值是 self - n * other,其中 n 是最接近 self / other 的精确值的整数,并且如果两个整数同样接近,则选择偶数。

如果结果为零,那么其符号将是 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)

返回将第一个操作数的数字旋转由第二个操作数指定的量的结果。第二个操作数必须是“精度到精度”范围内的整数。第二个操作数的绝对值给出了要旋转的位数。如果第二个操作数为正,那么向左旋转;否则旋转向右。如果需要,第一个操作数的系数在左侧用零和长度精度填充。第一个操作数的符号和指数不变。

same_quantum(other, context=None)

测试自我和其他人是否具有相同的指数或两者是否都是 NaN

该操作不受上下文的影响,并且是安静的:没有标志被改变并且不执行舍入。作为例外,如果第二个操作数无法完全转换,C版本可能会引发InvalidOperation。

scaleb(other, context=None)

返回由第二个调整的指数的第一个操作数。等同地,返回乘以 10**other 的第一个操作数。第二个操作数必须是整数。

shift(other, context=None)

返回将第一个操作数的数字移动由第二个操作数指定的量的结果。第二个操作数必须是“精度到精度”范围内的整数。第二个操作数的绝对值给出了要移位的位数。如果第二个操作数为正,则向左移位;否则转移到右边。移位到系数中的数字是零。第一个操作数的符号和指数不变。

sqrt(context=None)

将参数的平方根返回到全精度。

to_eng_string(context=None)

如果需要指数,则使用工程符号转换为字符串。

工程符号具有为3的倍数的指数。这可以在小数位的左边留下最多3位数字,并且可能需要添加一个或两个尾随零。

例如,这将 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)

舍入到最接近的整数,如果发生舍入,则适当地发信号通知 InexactRounded。舍入模式由给定的 rounding 参数确定,否则由给定的 context 确定。如果没有给出参数,则使用当前上下文的舍入模式。

to_integral_value(rounding=None, context=None)

四舍五入到最接近的整数,而不用信令 InexactRounded。如果给出,应用 rounding;否则,在提供的 context 或当前上下文中使用舍入方法。

9.4.2.1. 逻辑操作数

logical_and()logical_invert()logical_or()logical_xor() 方法期望它们的参数是 逻辑操作数逻辑操作数 是其指数和符号都为零并且其数字都是 01Decimal 实例。

9.4.3. 上下文对象

上下文是算术运算的环境。它们管理精度,设置舍入规则,确定哪些信号被视为异常,并限制指数的范围。

每个线程都有自己的当前上下文,可以使用 getcontext()setcontext() 函数访问或更改它们:

decimal.getcontext()

返回活动线程的当前上下文。

decimal.setcontext(c)

将活动线程的当前上下文设置为 c

您还可以使用 with 语句和 localcontext() 函数临时更改活动上下文。

decimal.localcontext(ctx=None)

返回上下文管理器,它将在活动线程的当前上下文设置为with语句的入口处的 ctx 的副本,并在退出with语句时恢复先前的上下文。如果没有指定上下文,则使用当前上下文的副本。

例如,以下代码将当前小数精度设置为42个位置,执行计算,然后自动恢复上一个上下文:

from decimal import localcontext

with localcontext() as ctx:
    ctx.prec = 42   # Perform a high precision calculation
    s = calculate_something()
s = +s  # Round the final result back to the default precision

新的上下文也可以使用下面描述的 Context 构造函数来创建。此外,该模块提供了三个预先设置的上下文:

class decimal.BasicContext

这是由通用小数算术规范定义的标准上下文。精度设置为9。舍入设置为 ROUND_HALF_UP。所有标志被清除。除 InexactRoundedSubnormal 之外,所有陷阱都被启用(作为异常处理)。

因为许多陷阱都已启用,所以此上下文对于调试非常有用。

class decimal.ExtendedContext

这是由通用小数算术规范定义的标准上下文。精度设置为9。舍入设置为 ROUND_HALF_EVEN。所有标志被清除。不启用陷阱(以便在计算期间不会引发异常)。

因为陷阱已禁用,所以此上下文对于喜欢使用 NaNInfinity 的结果值而不是引发异常的应用程序非常有用。这允许应用程序在存在否则将停止程序的条件的情况下完成运行。

class decimal.DefaultContext

此上下文由 Context 构造函数用作新上下文的原型。更改字段(如精度)具有更改由 Context 构造函数创建的新上下文的默认值的效果。

此上下文在多线程环境中最有用。在线程启动之前更改其中一个字段具有设置系统范围默认值的效果。不建议在线程启动后更改字段,因为它需要线程同步以防止竞争条件。

在单线程环境中,最好不要使用这个上下文。相反,只需如下所述显式创建上下文。

默认值为 prec = 28rounding = ROUND_HALF_EVEN,并为 OverflowInvalidOperationDivisionByZero 启用陷阱。

除了三个提供的上下文之外,可以使用 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 是在范围[1MAX_PREC]中的整数,设置上下文中算术运算的精度。

rounding 选项是 Rounding Modes 部分中列出的常量之一。

trapsflags 字段列出了要设置的任何信号。通常,新的上下文应该只设置陷阱并保持标志清楚。

EminEmax 字段是指定指数可允许的外部限制的整数。 Emin 必须在[MIN_EMIN0]范围内,Emax 在[0MAX_EMAX]范围内。

capitals 字段为 01 (默认值)。如果设置为 1,指数打印为大写 E;否则,使用小写 eDecimal('6.02e+23')

clamp 字段为 0 (默认值)或 1。如果设置为 1,则在该上下文中可表示的 Decimal 实例的指数 e 严格地限于范围 Emin - prec + 1 <= e <= Emax - prec + 1。如果 clamp0,则较弱条件成立:经调整的 Decimal 实例的指数最多为 Emax。当 clamp1 时,为了拟合指数约束,在可能的情况下,大的正常数将使其指数减小并且将相应数量的零添加到其系数;这保留了数字的值,但丢失了关于显着尾随零的信息。例如:

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

1clamp 值允许与IEEE 754中规定的固定宽度十进制交换格式兼容。

Context 类定义了几个通用方法以及在给定上下文中直接进行算术的大量方法。此外,对于上述 Decimal 方法(除了 adjusted()as_tuple() 方法之外),存在相应的 Context 方法。例如,对于 Context 实例 CDecimal 实例 xC.exp(x) 等价于 x.exp(context=C)。每个 Context 方法在接受十进制实例的任何地方接受Python整数(int 的实例)。

clear_flags()

将所有标志重置为 0

clear_traps()

将所有陷阱重置为 0

3.3 新版功能.

copy()

返回上下文的副本。

copy_decimal(num)

返回小数实例num的副本。

create_decimal(num)

num 创建一个新的十进制实例,但使用 self 作为上下文。与 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 创建一个新的十进制实例,但使用 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

3.1 新版功能.

Etiny()

返回等于 Emin - prec + 1 的值,该值是子标准结果的最小指数值。当发生下溢时,指数设置为 Etiny

Etop()

返回等于 Emax - prec + 1 的值。

使用小数的通常方法是创建 Decimal 实例,然后应用发生在活动线程的当前上下文中的算术运算。另一种方法是使用上下文方法在特定上下文中进行计算。这些方法类似于 Decimal 类的方法,这里只简单地叙述。

abs(x)

返回 x 的绝对值。

add(x, y)

返回 xy 的总和。

canonical(x)

返回相同的小数对象 x

compare(x, y)

以数字方式比较 xy

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 是规范的,返回 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)

返回 xy 的产品。

next_minus(x)

返回小于 x 的最大可表示数。

next_plus(x)

返回大于 x 的最小可表示数。

next_toward(x, y)

返回最接近 x 的数字,以 y 的方向。

normalize(x)

x 缩减为最简单的形式。

number_class(x)

返回 x 类的指示。

plus(x)

Plus对应于Python中的一元前缀加运算符。此操作应用上下文精度和舍入,因此它是 not 的身份操作。

power(x, y, modulo=None)

x 返回给 y 的权重,如果给定,则减少模 modulo

有两个参数,计算 x**y。如果 x 为负,那么 y 必须是积分的。除非 y 是积分的,并且结果是有限的,并且可以精确地以“精确”数字表示,否则结果将是不精确的。使用上下文的舍入模式。在Python版本中,结果总是正确四舍五入。

在 3.3 版更改: C模块根据正确圆整的 exp()ln() 函数计算 power()。结果是明确的,但只有“几乎总是正确圆润”。

有三个参数,计算 (x**y) % modulo。对于三个参数形式,对参数的以下限制:

  • 所有三个参数必须是整数

  • y 必须是非负的

  • xy 中的至少一个必须是非零的

  • modulo 必须非零,并且至多有“精度”数字

Context.power(x, y, modulo) 产生的值等于通过以无界精度计算 (x**y) % modulo 而获得的值,但是更有效地计算。结果的指数为零,不管 xymodulo 的指数如何。结果总是准确的。

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)

如果两个操作数具有相同的指数,则返回 True

scaleb(x, y)

在添加第二个值exp后返回第一个操作数。

shift(x, y)

返回 x 的移位副本,y 次。

sqrt(x)

非负数的平方根与上下文精度。

subtract(x, y)

返回 xy 之间的差异。

to_eng_string(x)

如果需要指数,则使用工程符号转换为字符串。

工程符号具有为3的倍数的指数。这可以在小数位的左边留下最多3位数字,并且可能需要添加一个或两个尾随零。

to_integral_exact(x)

舍入为整数。

to_sci_string(x)

使用科学记数法将数字转换为字符串。

9.4.4. 常量

本节中的常量仅与C模块相关。为了兼容性,它们也包括在纯Python版本中。

 

32位

64位

decimal.MAX_PREC

425000000

999999999999999999

decimal.MAX_EMAX

425000000

999999999999999999

decimal.MIN_EMIN

-425000000

-999999999999999999

decimal.MIN_ETINY

-849999999

-1999999999999999997

decimal.HAVE_THREADS

默认值为 True。如果Python编译没有线程,C版本自动禁用昂贵的线程本地上下文机制。在这种情况下,值为 False

9.4.5. 舍入模式

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;否则舍入到零。

9.4.6. 信号

信号表示计算期间出现的条件。每个对应于一个上下文标志和一个上下文陷阱使能器。

只要遇到条件,就设置上下文标志。在计算之后,可以检查标志用于信息目的(例如,以确定计算是否精确)。检查标志后,请务必在开始下一个计算之前清除所有标志。

如果为信号设置了上下文的陷阱启用程序,那么该条件将导致引发Python异常。例如,如果设置了 DivisionByZero 陷阱,则在遇到该条件时引发 DivisionByZero 异常。

class decimal.Clamped

改变指数以适合表示约束。

通常,当指数落在上下文的 EminEmax 限制之外时,发生钳位。如果可能,通过向系数添加零来减小指数以适应。

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

数字溢出。

表示发生舍入后指数大于 Emax。如果没有被捕获,结果取决于舍入模式,或者向内拉到最大的可表示的有限数,或者向外舍入到 Infinity。在任一情况下,也用信号通知 InexactRounded

class decimal.Rounded

发生舍入,尽管可能没有丢失信息。

四舍五入丢弃数字时发出信号;即使这些数字为零(例如将 5.00 舍入到 5.0)。如果没有被捕获,则返回结果不变。此信号用于检测有效数字的丢失。

class decimal.Subnormal

在舍入之前指数低于 Emin

当操作结果低于正常(指数太小)时发生。如果没有被捕获,则返回结果不变。

class decimal.Underflow

数值下溢,结果四舍五入为零。

当次正常结果通过四舍五入推为零时发生。 InexactSubnormal 也被用信号通知。

class decimal.FloatOperation

为混合浮点和小数使用更严格的语义。

如果信号未被捕获(默认),则允许在 Decimal 构造函数,create_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)

9.4.7. 浮点注释

9.4.7.1. 减少舍入误差,精度提高

使用十进制浮点消除了十进制表示错误(使得有可能精确地表示 0.1);然而,当非零数字超过固定精度时,一些操作仍然可能导致四舍五入误差。

舍入误差的影响可以通过加或减几乎偏移量来放大,导致重要性的损失。 Knuth提供了两个指导性示例,其中精确度不足的圆角浮点运算导致加法的关联和分布属性的分解:

# Examples from Seminumerical Algorithms, Section 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')

9.4.7.2. 特殊值

decimal 模块的数字系统提供特殊值,包括 NaNsNaN-InfinityInfinity 和两个零,+0-0

无限可以直接用:Decimal('Infinity')。此外,当 DivisionByZero 信号未被捕获时,它们可以由于除以零而产生。同样,当 Overflow 信号未被捕获时,由于舍入超过最大可表示数的极限,可以导致无穷大。

无穷大是有符号的(仿射),可以在算术运算中使用,它们被视为非常大的不确定数。例如,将常数添加到无穷大给出了另一个无限结果。

一些操作是不确定的并返回 NaN,或者如果捕获了 InvalidOperation 信号,则引发异常。例如,0/0 返回 NaN,这意味着“不是数字”。这种多样的 NaN 是安静的,一旦创建,将流经其他计算总是导致另一个 NaN。此行为对于偶尔缺少输入的一系列计算很有用,它允许在将特定结果标记为无效时继续计算。

一种变体是 sNaN,其在每次操作之后发信号而不是保持安静。当无效结果需要中断特殊处理的计算时,这是一个有用的返回值。

Python的比较运算符的行为可能有点令人惊讶,其中涉及 NaN。其中一个操作数是安静的或信令 NaN 的测试总是返回 False (即使在执行 Decimal('NaN')==Decimal('NaN') 时),而不等式的测试总是返回 True。如果任一操作数是 NaN,尝试使用任何 <<=>>= 运算符比较两个小数的尝试将提高 InvalidOperation 信号,并且如果该信号未被捕获则返回 False。注意,一般小数算术规范没有规定直接比较的行为;这些涉及 NaN 的比较规则取自IEEE 854标准(参见5.7节中的表3)。为了确保严格的标准合规,请改用 compare()compare-signal() 方法。

带符号的零可以由下溢的计算产生。它们保留了如果计算已经进行得更精确将导致的符号。由于它们的大小为零,正和负零都被视为相等,它们的符号是信息性的。

除了具有不同但相等的两个有符号零之外,存在具有不同精度但值等效的零的各种表示。这需要一点习惯。对于习惯于归一化浮点表示的眼睛,以下计算返回等于零的值不是显而易见的:

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

9.4.8. 使用线程

getcontext() 函数访问每个线程的不同 Context 对象。具有单独的线程上下文意味着线程可以进行改变(例如 getcontext().prec=10)而不干扰其他线程。

同样,setcontext() 函数自动将其目标分配给当前线程。

如果 setcontext()getcontext() 之前未被调用,则 getcontext() 将自动创建一个新的上下文以供在当前线程中使用。

新上下文从称为 DefaultContext 的原型上下文复制。要控制默认值,以便每个线程在整个应用程序中使用相同的值,请直接修改 DefaultContext 对象。这应该做 before 任何线程启动,以便在调用 getcontext() 的线程之间不会有竞争条件。例如:

# Set applicationwide defaults for all threads about to be launched
DefaultContext.prec = 12
DefaultContext.rounding = ROUND_DOWN
DefaultContext.traps = ExtendedContext.traps.copy()
DefaultContext.traps[InvalidOperation] = 1
setcontext(DefaultContext)

# Afterwards, the threads can be started
t1.start()
t2.start()
t3.start()
 . . .

9.4.9. 食谱

这里有一些食谱作为效用函数,并演示了如何使用 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

9.4.10. 十进制常见问题

Q. 输入 decimal.Decimal('1234.5') 是很麻烦的。有使用交互式解释器时最小化输入的方法吗?

A. 一些用户将构造函数缩写为一个字母:

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

Q. 在具有两个小数位的定点应用程序中,一些输入有很多位置,需要舍入。其他人不应该有多余的数字,需要验证。应该使用什么方法?

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. 一旦我有有效的两个地方输入,我如何在整个应用程序中保持不变量?

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. 有很多方法来表达相同的价值。数字 200200.0002E202E+4 在各种精度上都具有相同的值。有没有办法将它们转换为一个可识别的规范价值?

A. normalize() 方法将所有等效值映射到单个代表:

>>> 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. 对于一些值,指数符号是表达系数中的有效位置的数量的唯一方式。例如,将 5.0E+3 表示为 5000 会使值保持不变,但不能显示原始值的两位含义。

如果应用程序不关心跟踪重要性,则很容易删除指数和尾随零,失去重要性,但保持值不变:

>>> 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. 有没有办法将普通浮点转换为 Decimal

A. 是的,任何二进制浮点数可以精确表示为十进制,虽然精确的转换可能需要比直觉的建议更精确:

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

Q. 在复杂的计算中,我如何确保我没有得到一个虚假的结果,因为精度不足或舍入异常。

A. 十进制模块可以方便地测试结果。最佳实践是使用更高精度和各种舍入模式重新运行计算。广泛不同的结果表明精度不足,舍入模式问题,病态输入或数值不稳定算法。

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')      # unary plus triggers rounding
Decimal('1.23')

或者,可以使用 Context.create_decimal() 方法创建后对输入进行四舍五入:

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