Сообщить об ошибке.

Методы десятичного объекта Decimal()

Объекты типа decimal.Decimal() обладают множеством специализированных методов.

Содержание:

  • Скорректированный показатель степени числа Decimal.adjusted(),
  • Десятичное число в виде именованного кортежа Decimal.as_tuple(),
  • Десятичное число в канонической форме Decimal.canonical(),
  • Сравнение двух десятичных чисел Decimal.compare(),
  • Сравнение двух десятичных чисел с сигналом Decimal.compare_signal(),
  • Сравнение двух чисел на основе абстрактного представления Decimal.compare_total(),
  • Сравнение абсолютных значений десятичных чисел Decimal.compare_total_mag(),
  • Возвращает исходный объект без изменений Decimal.conjugate(),
  • Абсолютное значение десятичного числа Decimal.copy_abs(),
  • Десятичное число с измененным знаком Decimal.copy_negate(),
  • Десятичное число с тем же знаком Decimal.copy_sign(),
  • Экспонента десятичного числа Decimal.exp(),
  • Преобразует nип float в Decimal Decimal.from_float(),
  • Умножает число на other и прибавляет к произведению число Decimal.fma(),
  • True если десятичное число находится в канонической форме Decimal.is_canonical(),
  • True если аргумент является конечным числом Decimal.is_finite(),
  • True если аргумент является бесконечностью Decimal.is_infinite(),
  • True если аргумент является NaN или sNaN Decimal.is_nan(),
  • True если десятичное число является нормальным Decimal.is_normal(),
  • True если аргумент является обычным NaN Decimal.is_qnan(),
  • True если аргумент имеет отрицательный знак Decimal.is_signed(),
  • True если аргумент является sNaN Decimal.is_snan(),
  • True если числом является маленьким для текущей точности Decimal.is_subnormal(),
  • True если аргумент является нулем Decimal.is_zero(),
  • Натуральный логарифм десятичного числа Decimal.ln(),
  • Десятичный логарифм десятичного числа Decimal.log10(),
  • Показатель величины порядка десятичного числа Decimal.logb(),
  • Логические операции:
  • Операции сравнения:
    • Наибольшее десятичное число Decimal.max(),
    • Наименьшее десятичное число Decimal.min(),
    • Наибольшее абсолютное значение десятичного числа Decimal.max_mag(),
    • Наименьшее абсолютное значение десятичного числа Decimal.min_mag(),
  • Приращение аргументов:
    • Наибольшее десятичное число в указанном контексте Decimal.next_minus(),
    • Наименьшее десятичное число в указанном контексте Decimal.next_plus(),
    • Минимально возможное число в указанном контексте Decimal.next_toward(),
  • Десятичное число к канонической форме Decimal.normalize(),
  • Строка описывающая класс операнда Decimal.number_class(),
  • Округленное значение первого операнда с показателем степени второго операнда Decimal.quantize(),
  • Остаток от деления Decimal.radix(),
  • Поворот цифр первого операнда на величину второго операнда Decimal.rotate(),
  • True если оба операнда имеют одинаковый показатель степени Decimal.same_quantum(),
  • Устанавливает степень первого операнда в значение второго операнда Decimal.scaleb(),
  • Аналогичен функции Decimal.rotate() Decimal.shift(),
  • Квадратный корень десятичного числа Decimal.sqrt(),
  • Строковое представление числа в инженерной форме Decimal.to_eng_string(),
  • Округление до ближайшего целого числа Decimal.to_integral_exact(),
  • Аналогичен Decimal.to_integral_exact() Decimal.to_integral_value().

Decimal.adjusted():

Возвращает скорректированный показатель степени числа, при котором слева от десятичной точки остается только одна цифра. Полезен для определения самой значимой цифры числа.

>>> from decimal import *
>>> Decimal('0.0231').adjusted()
# -2
>>> Decimal('2.31').adjusted()
# 0
>>> Decimal('231').adjusted()
# 2

Decimal.as_tuple():

Возвращает число в виде именованного кортежа DecimalTuple(sign, digits, exponent).

>>> from decimal import *
>>> num = Decimal('0.0231').as_tuple()
>>> num
# DecimalTuple(sign=0, digits=(2, 3, 1), exponent=-4)

#  Кортеж является именованным
#  обращение к элементу по его индексу
>>> num[1]
# (2, 3, 1)

#  обращение к элементу по его имени
>>> num.digits
# (2, 3, 1)

Decimal.canonical():

Возвращает число в канонической форме. Учитывая, что Decimal() и так возвращает число в канонической форме, то применение данного метода не приведет к другим изменениям аргумента.

>>> from decimal import *
>>> Decimal('0.0231')
# Decimal('0.0231')
>>> Decimal('0.0231').canonical()
# Decimal('0.0231')

Decimal.compare(other, context=None):

Команда Decimal(a).compare(Decimal(other = b)) позволяет выполнить сравнение двух чисел и возвращает Decimal('-1') если a < b, Decimal('0') если a == b и Decimal('1') если a > b. Если a или b равно Decimal('NaN'), то будет возвращено Decimal('NaN').

>>> from decimal import *
>>> Decimal('0.0231').compare(Decimal('0.0232'))
# Decimal('-1')
>>> Decimal('0.0231').compare(Decimal('NaN'))
# Decimal('NaN')

Параметр context может принимать объект любого контекста вычислений.

Decimal.compare_signal(other, context=None):

Метод абсолютно аналогичный методу Decimal.compare() лишь с тем отличием, что имеет установленные сигналы, перехватывающие сравнение числа с значением NaN или если оба сравниваемых значения NaN равно как и для sNaN и вызывающий исключение InvalidOperation.

>>> from decimal import *
>>> Decimal('0.0231').compare_signal(Decimal('NaN'))
# Traceback (most recent call last):
#   File "<stdin>", line 1, in <module<
# decimal.InvalidOperation: [<class 'decimal.InvalidOperation'<]
>>> Decimal('NaN').compare_signal(Decimal('NaN'))
# Traceback (most recent call last):
#   File "<stdin>", line 1, in <module<
# decimal.InvalidOperation: [<class 'decimal.InvalidOperation'<]
>>> Decimal('0.0231').compare_signal(Decimal('0.1'))
# Decimal('-1')
>>> Decimal('0.0231').compare_signal(Decimal('0.001'))
# Decimal('1')

Параметр context может принимать объект любого контекста вычислений.

Decimal.compare_total(other, context=None):

Аналогичен методу Decimal.compare() но позволяет выполнять сравнение не на основе значения чисел, а на основе их абстрактного представления.

>>> from decimal import *
>>> Decimal('1').compare_total(Decimal('1.0'))
# Decimal('1')
>>> Decimal('1.0').compare_total(Decimal('1'))
# Decimal('-1')
>>> Decimal('1.0').compare_total(Decimal('NaN'))
# Decimal('-1')
>>> Decimal('NaN').compare_total(Decimal('NaN'))
# Decimal('0')

Эта операция не зависит от контекста, т.к. значения NaN включены в общий порядок сравнения. Но если второй операнд не может быть точно представлен то Python реализованный на языке C может вызвать исключение InvalidOperation.

Decimal.compare_total_mag(other, context=None):

Метод аналогичен Decimal.compare_total()](#compare_total), но игнорирует знак операндов и по сути аналогичен команде Decimal(a).copy_abs().compare_total(Decimal(b).copy_abs()).

>>> from decimal import *
>>> Decimal('1.0').compare_total(Decimal('-1'))
# Decimal('1')
>>> Decimal('1.0').compare_total_mag(Decimal('-1'))
# Decimal('-1')

Эта операция не зависит от контекста, т.к. значения NaN включены в общий порядок сравнения. Но если второй операнд не может быть точно представлен то Python реализованный на языке C может вызвать исключение InvalidOperation.

Decimal.conjugate():

Возвращает исходный объект без каких-либо изменений, как есть. Данный метод реализован только для соответствия спецификации.

Decimal.copy_abs():

Возвращает абсолютное значение числа. Данная операция не зависит от контекста, не изменяет флаги, не выполняет округления.

>>> from decimal import *
>>> Decimal('-0.1200').copy_abs()
# Decimal('0.1200')

Decimal.copy_negate():

Возвращает число с измененным знаком, схожа с унарным оператором '-'. Данная операция не зависит от контекста, не изменяет флаги, не выполняет округления.

>>> from decimal import *
>>> Decimal('-0.1200').copy_negate()
# Decimal('0.1200')
>>> Decimal('0.1200').copy_negate()
# Decimal('-0.1200')

Decimal.copy_sign(other, context=None):

Возвращает число с тем же знаком, что и у числа other.

>>> from decimal import *
>>> Decimal('-0.1200').copy_sign(Decimal('1.1'))
# Decimal('0.1200')
>>> Decimal('0.1200').copy_sign(Decimal('-1.1'))
# Decimal('-0.1200')
>>> Decimal('-0.1200').copy_sign(Decimal('-1.1'))
# Decimal('-0.1200')

Decimal.exp(context=None):

Возвращает экспоненту указанного числа x как e**x. Округление результата происходит в режиме decimal.ROUND_HALF_EVEN`.

>>> from decimal import *
>>> Decimal(0).exp()
# Decimal('1')
>>> Decimal(1).exp()
# Decimal('2.718281828459045235360287471')
>>> Decimal(100).exp()
# Decimal('2.688117141816135448412625552E+43')

Параметр context может принимать объект любого контекста вычислений.

Decimal.from_float(f):

Преобразует число типа float в число типа decimal.Decimal() как есть, т.е. так как оно представлено в памяти компьютера.

Некоторые числа float, не имеют точного представления в двоичной системе - являются бесконечными дробями, поэтому в памяти компьютера они всегда хранятся с некоторой погрешностью:

>>> from decimal import *
>>> Decimal.from_float(0.24)
# Decimal('0.2399999999999999911182158029987476766109466552734375')
>>> Decimal.from_float(float('inf'))
# Decimal('Infinity')

Decimal.fma(other, third, context=None):

Умножает число на other и прибавляет к произведению число third, но без выполнения промежуточного округления.

>>> from decimal import *
>>> Decimal(3).fma(4, 5)
# Decimal('17')
>>> Decimal('1.25').fma(Decimal('4'), Decimal('5.0000'))
# Decimal('10.0000')

Параметр context может принимать объект любого контекста вычислений.

Decimal.is_canonical():

Возвращает True если число находится в канонической форме, но так как числа типа Decimal всегда имеют каноническую форму то и метод всегда возвращает True.

>>> from decimal import *
>>> Decimal('0.231').is_canonical()
# True

Decimal.is_finite():

Возвращает True если аргумент является конечным числом и False если бесконечностью или NaN.

>>> from decimal import *
>>> Decimal('0.231').is_finite()
# True
>>> Decimal('NaN').is_finite()
# False

Decimal.is_infinite():

Возвращает True если аргумент является положительной или отрицательной бесконечностью и False во всех остальных случаях.

>>> from decimal import *
>>> Decimal('inf').is_infinite()
# True
>>> Decimal('0.321').is_infinite()
# False

Decimal.is_nan():

Возвращает True если аргумент является NaN или сигнальным sNaN иFalse` во всех остальных случаях.

>>> from decimal import *
>>> Decimal('0.321').is_nan()
# False
>>> Decimal('nan').is_nan()
# True
>>> Decimal('snan').is_nan()
# True

Decimal.is_normal(context=None):

Возвращает True если число является нормальным и False если число является нулем, слишком маленьким для текущей точности, бесконечностью или Nan.

>>> from decimal import *
>>> Decimal(1).is_normal()
# True
>>> Decimal('2.5').is_normal()
# True
>>> Decimal('2.5e10').is_normal()
# True
>>> Decimal('2.5E-10').is_normal()
# True
>>> Decimal(0).is_normal()
# False
>>> Decimal('0.00').is_normal()
# False
>>> Decimal('1E-9999999').is_normal()
# False
>>> Decimal('-Inf').is_normal()
# False
>>> Decimal('NaN').is_normal()
# False

Decimal.is_qnan():

Возвращает True если аргумент является обычным NaN и False во всех остальных случаях.

>>> from decimal import *
>>> Decimal('NaN').is_qnan()
# True
>>> Decimal('sNaN').is_qnan()
# False
>>> Decimal('0.1').is_qnan()
# False

Decimal.is_signed():

Возвращает True если аргумент имеет отрицательный знак и False во всех остальных случаях. Обратите внимание что ноль, NaN, sNaN и бесконечности так же могут иметь отрицательный знак.

>>> from decimal import *
>>> Decimal('-0.1').is_signed(), Decimal('0.1').is_signed()
# (True, False)
>>> Decimal('-0').is_signed(), Decimal('0').is_signed()
# (True, False)
>>> Decimal('-NaN').is_signed(), Decimal('NaN').is_signed()
# (True, False)
>>> Decimal('-sNaN').is_signed(), Decimal('sNaN').is_signed()
# (True, False)
>>> Decimal('-Inf').is_signed(), Decimal('Inf').is_signed()
# (True, False)

Decimal.is_snan():

Возвращает True если аргумент является sNaN, NaN и False во всех остальных случаях.

>>> from decimal import *
>>> Decimal('sNaN').is_snan()
# True
>>> Decimal('NaN').is_snan()
# False

Decimal.is_subnormal():

Возвращает True если аргумент является числом слишком маленьким для текущей точности и False во всех остальных случаях.

>>> from decimal import *
>>> Decimal('1E-9999999').is_subnormal()
# True
>>> Decimal('1E-999999').is_subnormal()
# False

Decimal.is_zero():

Возвращает True если аргумент является нулем положительным или отрицательным и False во всех остальных случаях.

>>> from decimal import *
>>> Decimal('0').is_zero()
# True
>>> Decimal('+0').is_zero()
# True
>>> Decimal('-0').is_zero()
# True

Decimal.ln(context=None):

Возвращает натуральный логарифм числа. Результат округляется в режиме decimal.ROUND_HALF_EVEN.

>>> from decimal import *
>>> Decimal('2.71').ln()
# Decimal('0.9969486348916095320608871638')
>>> Decimal('10').ln()
# Decimal('2.302585092994045684017991455')

Параметр context может принимать объект любого контекста вычислений.

Decimal.log10(context=None):

Возвращает десятичный логарифм числа. Результат округляется в режиме decimal.ROUND_HALF_EVEN`.

>>> from decimal import *
>>> Decimal('10').log10()
# Decimal('1')
>>> Decimal('101').log10()
# Decimal('2.004321373782642574275188178')

Параметр context может принимать объект любого контекста вычислений.

Decimal.logb(context=None):

Возвращает целое число, которое является показателем величины самой значимой цифры операнда.

>>> from decimal import *
>>> Decimal('100').logb()
# Decimal('2')
>>> Decimal('900').logb()
# Decimal('2')
>>> Decimal('999').logb()
# Decimal('2')
>>> Decimal('.01').logb()
# Decimal('-2')
>>> Decimal('.0909').logb()
# Decimal('-2')

Если операнд равен 0, то возвращается Decimal('-Infinity') и вызывается исключение DivisionByZero. Если операнд равен бесконечности, то так же возвращается бесконечность.

Параметр context может принимать объект любого контекста вычислений.

Логические операции:

Числа типа Decimal могут восприниматься как логические значения если их знак и экспонента равны 0, а все остальные цифры состоят только из0 и 1. Например, число Decimal((0, (1, 1, 0, 1), 0)) или Decimal('1101') можно спокойно считать логическими и передавать их логическим функциям.

Decimal.logical_and(other, context=None):

Логическое И двух операндов.

>>> from decimal import *
>>> Decimal('1101').logical_and(Decimal('1001'))
# Decimal('1001')

Параметр context может принимать объект любого контекста вычислений.

Decimal.logical_invert(context=None):

Логическое НЕ, поразрядное инвертирование битов.

>>> from decimal import *
#  не забываем про дополнительный код
>>> Decimal('10000').logical_invert()
# Decimal('1111111111111111111111101111')

Параметр context может принимать объект любого контекста вычислений.

Decimal.logical_or(other, context=None):

Логическое ИЛИ двух операндов.

>>> from decimal import *
>>> Decimal('1010').logical_or(Decimal('101'))
# Decimal('1111')

Параметр context может принимать объект любого контекста вычислений.

Decimal.logical_xor(other, context=None):

Логическое ИСКЛЮЧАЮЩЕЕ ИЛИ двух операндов.

>>> from decimal import *
>>> Decimal('1010').logical_xor(Decimal('1101'))
# Decimal('111')

Параметр context может принимать объект любого контекста вычислений.

Операции сравнения.

Decimal.max(other, context=None):

Возвращает наибольший аргумент. Округление указанное в контексте выполняется перед возвращением результата.

>>> from decimal import *
>>> Decimal('0.231').max(Decimal('0.2320'))
# Decimal('0.2320')

Параметр context может принимать объект любого контекста вычислений.

Decimal.min(other, context=None):

Возвращает наименьший аргумент. Округление указанное в контексте выполняется перед возвращением результата.

>>> from decimal import *
>>> Decimal('0.231').min(Decimal('0.2320'))
# Decimal('0.231')

Параметр context может принимать объект любого контекста вычислений.

Decimal.max_mag(other, context=None):

Возвращает больший аргумент, но сравниваются не сами аргументы, а их абсолютные значения. Округление указанное в контексте выполняется перед возвращением результата.

>>> from decimal import *
>>> Decimal('0.231').max_mag(Decimal('-0.2320'))
# Decimal('-0.2320')

Параметр context может принимать объект любого контекста вычислений.

Decimal.min_mag(other, context=None):

Возвращает меньший аргумент, но сравниваются не сами аргументы, а их абсолютные значения. Округление указанное в контексте выполняется перед возвращением результата.

>>> from decimal import *
>>> Decimal('0.231').min_mag(Decimal('-0.2320'))
# Decimal('0.231')

Параметр context может принимать объект любого контекста вычислений.

Приращение аргументов.

Decimal.next_minus(context=None):

Возвращает наибольшее число в указанном контексте, которое меньше чем данный операнд.

>>> from decimal import *
>>> Decimal('1').next_minus()
# Decimal('0.9999999999999999999999999999')

Decimal.next_plus(context=None):

Возвращает наименьшее число в указанном контексте, которое больше чем данный операнд.

>>> from decimal import *
>>> Decimal('1').next_plus()
# Decimal('1.000000000000000000000000001')

Decimal.next_toward(other, context=None):

Возвращает минимально возможное число в указанном контексте, которое следует за указанным операндом в сторону числа other.

>>> from decimal import *
>>> Decimal('1').next_toward(Decimal('2'))
# Decimal('1.000000000000000000000000001')
>>> Decimal('1').next_toward(Decimal('-2'))
# Decimal('0.9999999999999999999999999999')

Decimal.normalize(context=None):

Возвращает число к канонической форме.

>>> from decimal import *
>>> Decimal('.001200')
# Decimal('0.001200')
>>> Decimal('.001200').normalize()
# Decimal('0.0012')
>>> Decimal('23.100000000000').normalize()
# Decimal('23.1')
>>> Decimal('.23100000000000e2').normalize()
# Decimal('23.1')

Decimal.number_class():

Возвращает строку описывающую класс операнда.

>>> from decimal import *
>>> Decimal('+0').number_class()
# '+Zero'
>>> Decimal('-NaN').number_class()
# 'NaN'

Decimal.quantize(exp, rounding=None, context=None):

Возвращает округленное значение первого операнда с показателем степени второго операнда.

>>> from decimal import *
>>> Decimal('.0231231').quantize(Decimal('1.000'))
# Decimal('0.023')

В отличие от других операций, если длина коэффициента после операции квантования будет больше точности, тогда передается сообщение InvalidOperation. Это гарантирует, что, если нет условия ошибки, квантованный показатель степени всегда равен показателю правого операнда.

Также в отличие от других операций, квантование никогда не сигнализирует о потоке, даже если результат является ненормальным и неточным.

Если показатель второго операнда больше, чем у первого, тогда может потребоваться округление. В этом случае режим округления определяется аргументом rounding если он задан, иначе - заданным аргументом контекста context. Если ни один из аргументов не задан, используется режим округления контекста текущего потока.

Возвращается ошибка, когда результирующий показатель больше Emax или меньше Etiny.

Decimal.radix():

Возвращает Decimal('10'), основание системы счисления в которой выполняются все вычисления. Метод присутствует только для соответствия спецификации.

>>> from decimal import *
>>> Decimal('-NaN').radix()
# Decimal('10')
>>> Decimal('123').radix()
# Decimal('10')

Decimal.remainder_near():

Возвращает остаток от деления, но с таким знаком, который позволяет минимизировать его абсолютное значение.

>>> from decimal import *
>>> Decimal('10').remainder_near(Decimal('6'))
# Decimal('-2')
>>> Decimal('15').remainder_near(Decimal('4'))
# Decimal('-1')
>>> Decimal('15').remainder_near(Decimal('7'))
# Decimal('1')

Decimal.rotate(other, context=None):

Возвращает результат поворота цифр первого операнда на величину, указанную вторым операндом. Второй операнд должен быть целым числом. Абсолютное значение второго операнда дает количество смещений. Отрицательный знак второго операнда выполняет смещение вправо, положительный - влево. Смещение выполняется в пределах установленной в контексте точности. Коэффициент первого операнда дополняется слева нулями до точности длины при необходимости. Знак и показатель первого операнда не изменяются.

>>> from decimal import *
>>> Decimal('.123').rotate(Decimal('2'))
# Decimal('12.300')
>>> Decimal('.123').rotate(Decimal('-2'))
# Decimal('2300000000000000000000000.001')

Decimal.same_quantum(other, context=None):

Возвращает True если оба операнда имеют одинаковый показатель степени или если оба NaN. Данный метод не зависит от контекста, не меняет флаги и не выполняет округление. Python реализованый на языке C может вызвать исключение InvalidOperation если второй операнд не имеет точного представления.

>>> from decimal import *
>>> Decimal('2.31').same_quantum(Decimal('1.01'))
# True
>>> Decimal('2.31').same_quantum(Decimal('1.0100'))
# False
>>> Decimal('NaN').same_quantum(Decimal('NaN'))
# True

Decimal.scaleb(other, context=None):

Устанавливает показатель степени первого операнда в значение второго операнда, который должен быть целым числом.

>>> from decimal import *
>>> Decimal('2.31').scaleb(Decimal('2'))
# Decimal('231')
>>> Decimal('2.31').scaleb(Decimal('-2'))
# Decimal('0.0231')

Decimal.shift(other, context=None):

Метод аналогичен функции Decimal.rotate(), с тем лишь отличием, что смещение выполняется не циклически.

>>> from decimal import *
>>> Decimal('2.3123').shift(Decimal('-3'))
# Decimal('0.0023')
>>> Decimal('2.3123').shift(Decimal('3'))
# Decimal('2312.3000')
>>> Decimal('2.3123').shift(Decimal('5'))
# Decimal('231230.0000')
>>> Decimal('2.3123').shift(Decimal('-5'))
# Decimal('0.0000')

Decimal.sqrt(context=None):

Возвращает квадратный корень числа.

>>> from decimal import *
>>> Decimal('2').sqrt()
# Decimal('1.414213562373095048801688724')

Decimal.to_eng_string(context=None):

Возвращает строковое представление числа в инженерной форме.

>>> from decimal import *
>>> Decimal('2.31003E-3').to_eng_string()
# '0.00231003'
>>> Decimal('231003E3').to_eng_string()
# '231.003E+6'

Decimal.to_integral(rounding=None, context=None):

Эквивалентен методу Decimal.to_integral_value() и присутствует только для соответствия спецификации.

Decimal.to_integral_exact(rounding=None, context=None):

Выполняет округление до ближайшего целого числа и может выдавать сообщения о том была ли операция точной Inexact и выполнялось ли округление Rounded. Округление выполняется в режиме который можно указать в параметре rounding, если не один параметр не указан, то округление выполняется в режиме текущего контекста.

>>> from decimal import *
>>> Decimal('2.51').to_integral_exact()
# Decimal('3')
>>> Decimal('2.50').to_integral_exact()
# Decimal('2')

Decimal.to_integral_value(rounding=None, context=None):

Метод аналогичен Decimal.to_integral_exact(), с тем лишь отличием, что сообщения о неточности операции и факта округления никогда не выводятся.

>>> from decimal import *
>>> Decimal('2.50').to_integral_value()
# Decimal('2')
>>> Decimal('2.51').to_integral_value()
# Decimal('3')