"decimal" — Arithmétique décimale en virgule fixe et flottante
**************************************************************

**Code source :** Lib/decimal.py

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

Le module "decimal" fournit une arithmétique en virgule flottante
rapide et produisant des arrondis mathématiquement corrects. Il
possède plusieurs avantages par rapport au type "float" :

* Le module "decimal" « est basé sur un modèle en virgule flottante
  conçu pour les humains, qui suit ce principe directeur :
  l'ordinateur doit fournir un modèle de calcul qui fonctionne de la
  même manière que le calcul qu'on apprend à l'école » – extrait
  (traduit) de la spécification de l'arithmétique décimale.

* Les nombres décimaux peuvent être représentés exactement en base
  décimale flottante. En revanche, des nombres tels que "1.1" ou "1.2"
  n'ont pas de représentation exacte en base binaire flottante.
  L'utilisateur final ne s'attend typiquement pas à obtenir
  "3.3000000000000003" lorsqu'il saisit "1.1 + 2.2", ce qui se passe
  en arithmétique binaire à virgule flottante.

* Ces inexactitudes ont des conséquences en arithmétique. En base
  décimale à virgule flottante, "0.1 + 0.1 + 0.1 - 0.3" est exactement
  égal à zéro. En virgule flottante binaire, l'ordinateur l'évalue à
  "5.5511151231257827e-017". Bien que très proche de zéro, cette
  différence induit des erreurs lors des tests d'égalité, erreurs qui
  peuvent s'accumuler. Pour ces raisons "decimal" est le module
  utilisé pour des applications comptables ayant des contraintes
  strictes de fiabilité.

* Le module "decimal" incorpore la notion de chiffres significatifs,
  de façon à ce que "1.30 + 1.20" égale "2.50". Le dernier zéro est
  conservé pour respecter le nombre de chiffres significatifs. C'est
  l'affichage préféré pour représenter des sommes d'argent. Pour la
  multiplication, l'approche « scolaire » utilise tous les chiffres
  présents dans les facteurs. Par exemple, "1.3 * 1.2" donne "1.56"
  tandis que "1.30 * 1.20" donne "1.5600".

* Contrairement à l'arithmétique en virgule flottante binaire, le
  module "decimal" possède un paramètre de précision ajustable (par
  défaut à 28 chiffres significatifs) qui peut être aussi élevée que
  nécessaire pour un problème donné :

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

* L'arithmétique binaire et décimale en virgule flottante sont
  implémentées selon des standards publiés. Alors que le type "float"
  n'expose qu'une faible portion de ses capacités, le module "decimal"
  expose tous les composants nécessaires du standard. Lorsque
  nécessaire, le développeur a un contrôle total de la gestion des
  signaux et de l'arrondi. Cela inclut la possibilité de forcer une
  arithmétique exacte en utilisant des exceptions pour bloquer toute
  opération inexacte.

* Le module "decimal" a été conçu pour gérer « sans préjugé, à la fois
  une arithmétique décimale non-arrondie (aussi appelée arithmétique
  en virgule fixe) et à la fois une arithmétique en virgule flottante
  » (extrait traduit de la spécification de l'arithmétique décimale).

Le module est conçu autour de trois concepts : le nombre décimal, le
contexte arithmétique et les signaux.

Un "Decimal" est immuable. Il a un signe, une mantisse et un exposant.
Pour préserver le nombre de chiffres significatifs, les zéros en fin
de chaîne ne sont pas tronqués. Les décimaux incluent aussi des
valeurs spéciales telles que "Infinity", "-Infinity" et "NaN". Le
standard fait également la différence entre "-0" et "+0".

Le contexte de l'arithmétique est un environnement qui permet de
configurer une précision, une règle pour l'arrondi, des limites sur
l'exposant, des options indiquant le résultat des opérations et si les
signaux (remontés lors d'opérations illégales) sont traités comme des
exceptions Python. Les options d'arrondi incluent "ROUND_CEILING",
"ROUND_DOWN", "ROUND_FLOOR", "ROUND_HALF_DOWN", "ROUND_HALF_EVEN",
"ROUND_HALF_UP", "ROUND_UP" et "ROUND_05UP".

Les signaux correspondent à des états exceptionnels qui surviennent
durant le calcul. Selon les besoins de l'application, les signaux
peuvent être ignorés, considérés comme de l'information, ou bien
traités comme des exceptions. Les signaux dans le module "decimal"
sont : "Clamped", "InvalidOperation", "DivisionByZero", "Inexact",
"Rounded", "Subnormal", "Overflow", "Underflow" et "FloatOperation".

Chaque signal est configurable indépendamment, à travers un drapeau
(ou option) et une surveillance. Quand une opération illégale
survient, le drapeau du signal est mis à "1" puis, s'il est surveillé,
une exception est levée. La mise à "1" du drapeau est persistante,
l'utilisateur doit donc remettre les drapeaux à zéro avant de
commencer un calcul qu'il souhaite surveiller.

Voir aussi:

  * Spécification d'IBM sur l'arithmétique décimale : The General
    Decimal Arithmetic Specification (article en anglais).


Introduction pratique
=====================

Commençons par importer le module, regarder le contexte actuel avec
"getcontext()" et, si nécessaire, configurer la précision, l'arrondi
et la gestion des signaux :

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

Les instances de "Decimal" peuvent être construites avec des entiers,
des chaînes de caractères, des "floats" ou des *n*-uplets. La
construction depuis un entier ou un "float" effectue la conversion
exacte de cet entier ou de ce "float". Les nombres décimaux incluent
des valeurs spéciales telles que "NaN" qui signifie en anglais « *Not
a number* », en français « pas un nombre », des "Infinity" positifs ou
négatifs et "-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')

Si le signal "FloatOperation" est surveillé, un mélange accidentel
d'objets "Decimal" et de "float" dans les constructeurs ou des
opérations de comparaison lève une exception :

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

Nouveau dans la version 3.3.

Le nombre de chiffres significatifs d'un nouvel objet "Decimal" est
déterminé entièrement par le nombre de chiffres saisis. La précision
et les règles d'arrondis n'interviennent que lors d'opérations
arithmétiques.

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

Si les limites internes de la version en C sont dépassées, la
construction d'un objet décimal lève l'exception "InvalidOperation" :

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

Modifié dans la version 3.3.

Les objets "Decimal" interagissent très bien avec le reste de Python.
Voici quelques exemples d'opérations avec des décimaux :

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

Et certaines fonctions mathématiques sont également disponibles sur
des instances de "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')

La méthode "quantize()" arrondit un nombre à un exposant déterminé.
Cette méthode est utile pour des applications monétaires qui
arrondissent souvent un résultat à un nombre déterminé de chiffres
après la virgule :

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

Comme montré plus haut, la fonction "getcontext()" accède au contexte
actuel et permet de modifier les paramètres. Cette approche répond aux
besoins de la plupart des applications.

Pour un travail plus avancé, il peut être utile de créer des contextes
alternatifs en utilisant le constructeur de "Context". Pour activer
cet objet "Context", utilisez la fonction "setcontext()".

En accord avec le standard, le module "decimal" fournit des objets
*Context* standards, "BasicContext" et "ExtendedContext". Le premier
est particulièrement utile pour le débogage car beaucoup des signaux
sont surveillés :

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

Les objets "Context" ont aussi des options pour détecter des
opérations illégales lors des calculs. Ces options restent activées
jusqu'à ce qu'elles soit remises à zéro de manière explicite. Il
convient donc de remettre à zéro ces options avant chaque inspection
de chaque calcul, avec la méthode "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=[])

Les options montrent que l'approximation de π par une fraction a été
arrondie (les chiffres au-delà de la précision spécifiée par l'objet
*Context* ont été tronqués) et que le résultat est différent (certains
des chiffres tronqués étaient différents de zéro).

La surveillance est activée en utilisant un dictionnaire dans
l'attribut "traps" du contexte :

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

La plupart des applications n'ajustent l'objet "Context" qu'une seule
fois, au démarrage. Et, dans beaucoup d'applications, les données sont
converties une fois pour toutes en "Decimal". Une fois le "Context"
initialisé et les objets "Decimal" créés, la majeure partie du
programme manipule les données de la même manière qu'avec d'autres
types numériques Python.


Les objets "Decimal"
====================

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

   Construit un nouvel objet "Decimal" à partir de *value*.

   *value* peut être un entier, une chaîne de caractères, un
   *n*-uplet, un "float" ou une autre instance de "Decimal". Si
   *value* n'est pas fourni, le constructeur renvoie "Decimal('0')".
   Si *value* est une chaîne de caractères, elle doit correspondre à
   la syntaxe décimale en dehors des espaces de début et de fin, ou
   des tirets bas, qui sont enlevés :

      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

   Les chiffres codés en Unicode sont aussi autorisés, dans les
   emplacements "digit" ci-dessus. Cela inclut des chiffres décimaux
   venant d'autres alphabets (par exemple les chiffres indo-arabes ou
   Devanagari) ainsi que les chiffres de pleine largeur "'\uff10'"
   jusqu'à "'\uff19'".

   Si *value* est un "n-uplet", il doit avoir trois éléments, le signe
   ("0" pour positif ou "1" pour négatif), un "n-uplet" de chiffres et
   un entier représentant l'exposant. Par exemple, "Decimal((0, (1, 4,
   1, 4), -3))" construit l'objet "Decimal('1.414')".

   Si *value* est un "float", la valeur en binaire flottant est
   convertie exactement à son équivalent décimal. Cette conversion
   peut parfois nécessiter 53 chiffres significatifs ou plus. Par
   exemple, "Decimal(float('1.1'))" devient
   "Decimal('1.100000000000000088817841970012523233890533447265625')".

   La précision spécifiée dans le contexte n'affecte pas le nombre de
   chiffres stockés. Cette valeur est déterminée exclusivement par le
   nombre de chiffres dans *value*. Par exemple, "Decimal('3.00000')"
   enregistre les 5 zéros même si la précision du contexte est de 3.

   L'objectif de l'argument *context* est de déterminer ce que Python
   doit faire si *value* est une chaîne avec un mauvais format. Si
   "InvalidOperation" est surveillé, une exception est levée, sinon le
   constructeur renvoie un objet "Decimal" de valeur "NaN".

   Une fois construit, un objet "Decimal" est immuable.

   Modifié dans la version 3.2: l'argument du constructeur peut
   désormais être un objet "float".

   Modifié dans la version 3.3: un argument "float" lève une exception
   si "FloatOperation" est surveillé. Par défaut la surveillance n'est
   pas activée.

   Modifié dans la version 3.6: les tirets bas sont autorisés pour
   grouper des chiffres, tout comme pour l'arithmétique en virgule
   fixe et flottante.

   Les objets "Decimal" partagent beaucoup de propriétés avec les
   autres types numériques natifs tels que "float" et "int". Toutes
   les opérations mathématiques et méthodes sont conservées. De même
   les objets "Decimal" peuvent être copiés, sérialisés via le module
   "pickle", affichés, utilisés comme clé de dictionnaire, éléments
   d'ensembles, comparés, classés et convertis vers un autre type (tel
   que "float" ou "int").

   Il existe quelques différences mineures entre l'arithmétique entre
   les objets décimaux et l'arithmétique avec les entiers et les
   "float". Quand l'opérateur modulo "%" est appliqué sur des objets
   décimaux, le signe du résultat est le signe du *dividende* plutôt
   que le signe du diviseur :

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

   L'opérateur division entière ("//") se comporte de la même manière,
   renvoyant la partie entière du quotient plutôt que son arrondi, de
   manière à préserver l'identité d'Euclide "x == (x // y) * y + x %
   y" :

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

   Les opérateurs "//" et "%" implémentent la division entière et le
   reste (ou modulo), respectivement, tels que décrits dans la
   spécification.

   Les objets "Decimal" ne peuvent généralement pas être combinés avec
   des "float" ou des objets "fractions.Fraction" lors d'opérations
   arithmétiques : toute addition entre un "Decimal" et un "float",
   par exemple, lève une exception "TypeError". Cependant, il est
   possible d'utiliser les opérateurs de comparaison entre instances
   de "Decimal" et les autres types numériques. Cela évite d'avoir des
   résultats absurdes lors des tests d'égalité entre différents types.

   Modifié dans la version 3.2: les comparaisons inter-types entre
   "Decimal" et les autres types numériques sont désormais
   intégralement gérées.

   En plus des propriétés numériques standard, les objets décimaux à
   virgule flottante ont également un certain nombre de méthodes
   spécialisées :

   adjusted()

      Renvoie l'exposant ajusté après avoir décalé les chiffres les
      plus à droite de la mantisse jusqu'à ce qu'il ne reste que le
      premier chiffre : "Decimal('321e+5').adjusted()" renvoie sept.
      Utilisée pour déterminer la position du chiffre le plus
      significatif par rapport à la virgule.

   as_integer_ratio()

      Renvoie un couple d'entiers "(n, d)" qui représentent l'instance
      "Decimal" donnée sous la forme d'une fraction, avec les termes
      les plus petits possibles et avec un dénominateur positif :

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

      La conversion est exacte. Lève une "OverflowError" sur l'infini
      et "ValueError" sur les *Nan*.

   Nouveau dans la version 3.6.

   as_tuple()

      Renvoie une représentation sous la forme d'un *n-uplet nommé* du
      nombre "DecimalTuple(sign, digits, exponent)".

   canonical()

      Renvoie la forme canonique de l'argument. Actuellement, la forme
      d'une instance "Decimal" est toujours canonique, donc cette
      opération renvoie son argument inchangé.

   compare(other, context=None)

      Compare les valeurs de deux instances "Decimal". "compare()"
      renvoie une instance "Decimal" et, si l'un des opérandes est un
      *NaN*, alors le résultat est un *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)

      Cette opération est identique à la méthode "compare()", sauf que
      tous les *NaN* sont surveillés. Autrement dit, si aucun des
      opérandes n'est un *NaN* de signalisation, alors tout opérande
      *NaN* silencieux est traité comme s'il s'agissait d'un *NaN* de
      signalisation.

   compare_total(other, context=None)

      Compare deux opérandes en utilisant leur représentation
      abstraite plutôt que leur valeur numérique. Similaire à la
      méthode "compare()", mais le résultat donne un ordre total sur
      les instances "Decimal". Deux instances de "Decimal" avec la
      même valeur numérique mais des représentations différentes se
      comparent de manière inégale dans cet ordre :

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

      Les *NaN* silencieux et de signalisation sont également inclus
      dans l'ordre total. Le résultat de cette fonction est
      "Decimal('0')" si les deux opérandes ont la même représentation,
      "Decimal('-1')" si le premier opérande est inférieur au second,
      et "Decimal('1')" si le premier opérande est supérieur au
      deuxième opérande. Voir les spécifications pour les détails de
      l'ordre total.

      Cette opération ne dépend pas du contexte et est silencieuse :
      aucun indicateur n'est modifié et aucun arrondi n'est effectué.
      Exceptionnellement, la version C peut lever une
      *InvalidOperation* si le deuxième opérande ne peut pas être
      converti exactement.

   compare_total_mag(other, context=None)

      Compare deux opérandes en utilisant leur représentation
      abstraite plutôt que leur valeur comme dans "compare_total()",
      mais en ignorant le signe de chaque opérande.
      "x.compare_total_mag(y)" est équivalent à
      "x.copy_abs().compare_total(y.copy_abs())".

      Cette opération ne dépend pas du contexte et est silencieuse :
      aucun indicateur n'est modifié et aucun arrondi n'est effectué.
      Exceptionnellement, la version C peut lever une
      *InvalidOperation* si le deuxième opérande ne peut pas être
      converti exactement.

   conjugate()

      Ne fait que renvoyer self ; cette méthode existe uniquement pour
      se conformer à la spécification.

   copy_abs()

      Renvoie la valeur absolue de l'argument. Cette opération ne
      dépend pas du contexte et est silencieuse : aucun drapeau n'est
      modifié et aucun arrondi n'est effectué.

   copy_negate()

      Renvoie l'opposé de l'argument. Cette opération ne dépend pas du
      contexte et est silencieuse : aucun drapeau n'est modifié et
      aucun arrondi n'est effectué.

   copy_sign(other, context=None)

      Renvoie une copie du premier opérande mais avec le même signe
      que celui du deuxième opérande. Par exemple :

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

      Cette opération ne dépend pas du contexte et est silencieuse :
      aucun indicateur n'est modifié et aucun arrondi n'est effectué.
      Exceptionnellement, la version C peut lever une
      *InvalidOperation* si le deuxième opérande ne peut pas être
      converti exactement.

   exp(context=None)

      Renvoie la valeur "e**x" (fonction exponentielle) du nombre
      donné. Le résultat est correctement arrondi en utilisant le mode
      d'arrondi "ROUND_HALF_EVEN".

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

   classmethod from_float(f)

      Constructeur alternatif qui n'accepte que les instances de
      "float" ou "int".

      Remarquez que "Decimal.from_float(0.1)" est différent de
      "Decimal('0.1')". Puisque 0.1 n'est pas exactement représentable
      en virgule flottante binaire, la valeur est stockée comme la
      valeur représentable la plus proche qui est
      "0x1.999999999999ap-4". La valeur équivalente en décimal est
      "0.1000000000000000055511151231257827021181583404541015625".

      Note:

        depuis Python 3.2, une instance "Decimal" peut également être
        construite directement à partir d'un "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')

      Nouveau dans la version 3.1.

   fma(other, third, context=None)

      Multiplier-ajouter fusionné. Renvoie "self*other+third" sans
      arrondir le produit intermédiaire "self*other".

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

   is_canonical()

      Renvoie "True" si l'argument est sous forme canonique et "False"
      sinon. Actuellement, une instance "Decimal" est toujours
      canonique, donc cette opération renvoie toujours "True".

   is_finite()

      Renvoie "True" si l'argument est un nombre fini et "False" si
      l'argument est un infini ou un *NaN*.

   is_infinite()

      Renvoie "True" si l'argument est un infini positif ou négatif,
      "False" sinon.

   is_nan()

      Renvoie "True" si l'argument est un *NaN* (signalisé ou
      silencieux), "False" sinon.

   is_normal(context=None)

      Renvoie "True" si l'argument est un nombre fini *normal*.
      Renvoie "False" si l'argument est zéro, infini, un nombre
      dénormalisé ou un *NaN*.

   is_qnan()

      Renvoie "True" si l'argument est un *NaN* silencieux, "False"
      sinon.

   is_signed()

      Renvoie "True" si l'argument est négatif, "False" sinon.
      Remarquez que les zéros et les *NaN* peuvent être signés.

   is_snan()

      Renvoie "True" si l'argument est un *NaN* signalisé, "False"
      sinon.

   is_subnormal(context=None)

      Renvoie "True" si l'argument est le résultat d'un dépassement
      par valeur inférieure, "False" sinon.

   is_zero()

      Renvoie "True" si l'argument est un zéro (positif ou négatif),
      "False" sinon.

   ln(context=None)

      Renvoie le logarithme naturel (base e) de l'opérande. Le
      résultat est arrondi avec le mode "ROUND_HALF_EVEN".

   log10(context=None)

      Renvoie le logarithme en base 10 de l'opérande. Le résultat est
      arrondi avec le mode "ROUND_HALF_EVEN".

   logb(context=None)

      Pour un nombre non nul, renvoie l'exposant ajusté de son
      opérande en tant qu'instance "Decimal". Si l'opérande est un
      zéro alors "Decimal('-Infinity')" est renvoyé et le drapeau
      "DivisionByZero" est levé. Si l'opérande est un infini alors
      "Decimal('Infinity')" est renvoyé.

   logical_and(other, context=None)

      "logical_and()" est une opération logique qui prend deux
      *opérandes logiques* (voir Opérandes logiques). Le résultat est
      le *ET* des chiffres des deux opérandes.

   logical_invert(context=None)

      "logical_invert()" est une opération logique. Le résultat est
      l'inversion de chacun des chiffres de l'opérande.

   logical_or(other, context=None)

      "logical_or()" est une opération logique qui prend deux
      *opérandes logiques* (voir Opérandes logiques). Le résultat est
      le *OU* des chiffres des deux opérandes.

   logical_xor(other, context=None)

      "logical_xor()" est une opération logique qui prend deux
      *opérandes logiques* (voir Opérandes logiques). Le résultat est
      le *OU EXCLUSIF* des chiffres des deux opérandes.

   max(other, context=None)

      Comme "max(self, other)" sauf que la règle d'arrondi de
      *context* est appliquée avant le retour et les valeurs "NaN"
      sont signalées ou ignorées (selon le contexte et suivant
      qu'elles sont signalisées ou silencieuses).

   max_mag(other, context=None)

      Semblable à la méthode "max()", mais la comparaison est
      effectuée en utilisant les valeurs absolues des opérandes.

   min(other, context=None)

      Comme "min(self, other)" sauf que la règle d'arrondi de
      *context* est appliquée avant le retour et les valeurs "NaN"
      sont signalées ou ignorées (selon le contexte et suivant
      qu'elles sont signalisées ou silencieuses).

   min_mag(other, context=None)

      Semblable à la méthode "min()", mais la comparaison est
      effectuée en utilisant les valeurs absolues des opérandes.

   next_minus(context=None)

      Renvoie le plus grand nombre représentable dans le *context*
      donné (ou dans le contexte du fil d'exécution actuel si aucun
      contexte n'est donné) qui est plus petit que l'opérande donné.

   next_plus(context=None)

      Renvoie le plus petit nombre représentable dans le *context*
      donné (ou dans le contexte du fil d'exécution actuel si aucun
      contexte n'est donné) qui est supérieur à l'opérande donné.

   next_toward(other, context=None)

      Si les deux opérandes ne sont pas égaux, renvoie le nombre le
      plus proche du premier opérande dans la direction du deuxième
      opérande. Si les deux opérandes sont numériquement égaux,
      renvoie une copie du premier opérande avec le signe défini comme
      étant le même que le signe du second opérande.

   normalize(context=None)

      Utilisé pour produire des valeurs canoniques d'une classe
      d'équivalence dans le contexte actuel ou dans le contexte
      spécifié.

      C'est la même sémantique que l'opération unaire plus, sauf que
      si le résultat final est fini, il est réduit à sa forme la plus
      simple, avec tous les zéros à droite supprimés et son signe
      conservé. Autrement dit, tant que la mantisse est différente de
      zéro et est un multiple de dix, elle est divisée par dix et
      l'exposant est incrémenté de 1. Sinon (la mantisse est nulle),
      l'exposant est mis à 0. Dans tous les cas, le signe est
      inchangé.

      Par exemple, "Decimal('32.100')" et "Decimal('0.321000e+2')" se
      normalisent tous deux à la valeur équivalente "Decimal('32.1')".

      Notez que l'arrondi est appliqué *avant* la réduction à la forme
      la plus simple.

      Dans les dernières versions de la spécification, cette opération
      est également connue sous le nom de "reduce".

   number_class(context=None)

      Renvoie une chaîne décrivant la *classe* de l'opérande. La
      valeur renvoyée est l'une des dix chaînes suivantes.

      * ""-Infinity"", indiquant que l'opérande est l'infini négatif ;

      * ""-Normal"", indiquant que l'opérande est un nombre négatif
        normal ;

      * ""-Subnormal"", indiquant que l'opérande est négatif et qu'il
        est dénormalisé ;

      * ""-Zero"", indiquant que l'opérande est un zéro négatif ;

      * ""+Zero"", indiquant que l'opérande est un zéro positif ;

      * ""+Subnormal"", indiquant que l'opérande est positif et qu'il
        est dénormalisé ;

      * ""+Normal"", indiquant que l'opérande est un nombre positif
        normal ;

      * ""+Infinity"", indiquant que l'opérande est l'infini positif ;

      * ""NaN"", indiquant que l'opérande est un *NaN* (*Not a
        Number*, pas un nombre) silencieux ;

      * ""sNaN"", indiquant que l'opérande est un *NaN* (*Not a
        Number*, pas un nombre) signalisé.

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

      Renvoie une valeur égale au premier opérande après arrondi et
      ayant l'exposant du second opérande.

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

      Contrairement aux autres opérations, si la longueur de la
      mantisse après l'opération de quantification est supérieure à la
      précision, alors une "InvalidOperation" est signalée. Ceci
      garantit que, sauf condition d'erreur, l'exposant quantifié est
      toujours égal à celui de l'opérande de droite.

      Contrairement aux autres opérations, la quantification ne
      signale jamais de dépassement par valeur inférieure, même si le
      résultat est inférieur à la valeur minimale représentable et est
      inexact.

      Si l'exposant du deuxième opérande est supérieur à celui du
      premier, un arrondi peut être nécessaire. Dans ce cas, le mode
      d'arrondi est déterminé par l'argument "rounding" s'il est
      donné, sinon par l'argument "context" donné ; si aucun argument
      n'est donné, le mode d'arrondi du contexte du fil d'exécution
      courant est utilisé.

      Une erreur est renvoyée chaque fois que l'exposant résultant est
      supérieur à "Emax" ou inférieur à "Etiny()".

   radix()

      Renvoie "Decimal(10)", la base (base) dans laquelle la classe
      "Decimal" fait toute son arithmétique. Inclus pour la
      compatibilité avec la spécification.

   remainder_near(other, context=None)

      Renvoie le reste de la division de *self* par *other*. La
      différence avec "self % other" réside dans le signe du reste,
      qui est choisi de manière à minimiser sa valeur absolue. Plus
      précisément, la valeur de retour est "self - n * other" où "n"
      est l'entier le plus proche de la valeur exacte de "self /
      other" et, si deux entiers sont également proches, alors
      l'entier pair est choisi.

      Si le résultat est zéro, alors son signe est le signe de *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)

      Renvoie le résultat de la rotation des chiffres du premier
      opérande d'une quantité spécifiée par le deuxième opérande. Le
      deuxième opérande doit être un entier compris dans la plage
      -précision à précision. La valeur absolue du deuxième opérande
      donne le nombre de rotations unitaires à faire. Si le deuxième
      opérande est positif alors la rotation se fait vers la gauche ;
      sinon la rotation se fait vers la droite. La mantisse du premier
      opérande est complétée à gauche avec des zéros à la précision de
      la longueur si nécessaire. Le signe et l'exposant du premier
      opérande sont inchangés.

   same_quantum(other, context=None)

      Teste si *self* et *other* ont le même exposant ou si les deux
      sont "NaN".

      Cette opération ne dépend pas du contexte et est silencieuse :
      aucun indicateur n'est modifié et aucun arrondi n'est effectué.
      Exceptionnellement, la version C peut lever une
      *InvalidOperation* si le deuxième opérande ne peut pas être
      converti exactement.

   scaleb(other, context=None)

      Renvoie le premier opérande avec l'exposant ajusté par le
      second. De manière équivalente, renvoie le premier opérande
      multiplié par "10**other". Le deuxième opérande doit être
      entier.

   shift(other, context=None)

      Renvoie le résultat du décalage des chiffres du premier opérande
      d'une quantité spécifiée par le deuxième opérande. Le deuxième
      opérande doit être un entier compris dans la plage -précision à
      précision. La valeur absolue du deuxième opérande donne le
      nombre de décalages unitaires à effectuer. Si le deuxième
      opérande est positif alors le décalage est vers la gauche ;
      sinon le décalage est vers la droite. Les chiffres insérés dans
      le nombre par le décalage sont des zéros. Le signe et l'exposant
      du premier opérande sont inchangés.

   sqrt(context=None)

      Renvoie la racine carrée de l'argument avec une précision
      maximale.

   to_eng_string(context=None)

      Convertit en chaîne, en utilisant la notation ingénieur si un
      exposant est nécessaire.

      La notation ingénieur possède un exposant qui est un multiple de
      3. Cela peut laisser jusqu'à 3 chiffres à gauche de la décimale
      et peut nécessiter l'ajout d'un ou de deux zéros en fin de
      mantisse.

      Par exemple, "Decimal('123E+1')" est converti en
      "Decimal('1.23E+3')".

   to_integral(rounding=None, context=None)

      Identique à la méthode "to_integral_value()". Le nom
      "to_integral" a été conservé pour la compatibilité avec les
      anciennes versions.

   to_integral_exact(rounding=None, context=None)

      Arrondit à l'entier le plus proche, en signalant "Inexact" ou
      "Rounded" selon le cas si l'arrondi se produit. Le mode
      d'arrondi est déterminé par le paramètre "rounding" s'il est
      donné, sinon par le "context" donné. Si aucun paramètre n'est
      donné, le mode d'arrondi du contexte courant est utilisé.

   to_integral_value(rounding=None, context=None)

      Arrondit à l'entier le plus proche sans signaler "Inexact" ou
      "Rounded". Si donné, applique *rounding* ; sinon, utilise la
      méthode d'arrondi dans le *context* fourni ou dans le contexte
      actuel.


Opérandes logiques
------------------

Les méthodes "logical_and()", "logical_invert()", "logical_or()" et
"logical_xor()" s'attendent à ce que leurs arguments soient des
*opérandes logiques*. Un *opérande logique* est une instance "Decimal"
dont l'exposant et le signe sont tous les deux zéro et dont les
chiffres sont tous "0" ou "1".


Objets de contexte
==================

Les contextes sont des environnements pour les opérations
arithmétiques. Ils régissent la précision, établissent des règles
d'arrondi, déterminent quels signaux sont traités comme des exceptions
et limitent la plage des exposants.

Chaque fil d'exécution a son propre contexte actuel qui est accessible
ou modifié à l'aide des fonctions "getcontext()" et "setcontext()" :

decimal.getcontext()

   Renvoie le contexte actuel du fil d'exécution courant.

decimal.setcontext(c)

   Définit le contexte du fil d'exécution courant à *c*.

Vous pouvez également utiliser l'instruction "with" et la fonction
"localcontext()" pour modifier temporairement le contexte actif.

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

   Renvoie un gestionnaire de contexte qui définira le contexte actuel
   du fil d'exécution actif sur une copie de *ctx* à l'entrée de
   l'instruction *with* et restaurera le contexte précédent lors de la
   sortie de l'instruction *with*. Si aucun contexte n'est spécifié,
   une copie du contexte actuel est utilisée. L'argument *kwargs* est
   utilisé pour définir les attributs du nouveau contexte.

   Par exemple, le code suivant définit la précision décimale actuelle
   à 42 chiffres, effectue un calcul, puis restaure automatiquement le
   contexte précédent :

      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

   En utilisant des arguments nommés, le code serait le suivant :

      from decimal import localcontext

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

   Lève "TypeError" si *kwargs* fournit un attribut que "Context" ne
   prend pas en charge. Lève soit "TypeError" ou "ValueError" si
   *kwargs* fournit une valeur invalide pour un attribut.

   Modifié dans la version 3.11: "localcontext()" prend désormais en
   charge la définition des attributs de contexte grâce à
   l'utilisation d'arguments nommés.

De nouveaux contextes peuvent également être créés à l'aide du
constructeur "Context" décrit ci-dessous. De plus, le module fournit
trois contextes prédéfinis :

class decimal.BasicContext

   Il s'agit d'un contexte standard défini par la *General Decimal
   Arithmetic Specification*. La précision est fixée à neuf. L'arrondi
   est défini sur "ROUND_HALF_UP". Tous les drapeaux sont effacés.
   Tous les signaux sont surveillés (ils lèvent des exceptions) sauf
   "Inexact", "Rounded" et "Subnormal".

   Étant donné que de nombreuses options sont surveillées, ce contexte
   est utile pour le débogage.

class decimal.ExtendedContext

   Il s'agit d'un contexte standard défini par la *General Decimal
   Arithmetic Specification*. La précision est fixée à neuf. L'arrondi
   est défini sur "ROUND_HALF_EVEN". Aucun signal n'est surveillé
   (afin que les exceptions ne soient pas levées pendant les calculs).

   Comme les interruptions sont désactivées, ce contexte est utile
   pour les applications qui préfèrent avoir une valeur de résultat
   "NaN" ou "Infinity" au lieu de lever des exceptions. Cela permet à
   une application de terminer une exécution en présence de conditions
   qui, autrement, arrêteraient le programme.

class decimal.DefaultContext

   Ce contexte est utilisé par le constructeur "Context" comme
   prototype pour de nouveaux contextes. Changer un champ (par exemple
   la précision) a pour effet de changer la valeur par défaut pour les
   nouveaux contextes créés par le constructeur "Context".

   Ce contexte est particulièrement utile dans les environnements à
   plusieurs fils d'exécution. La modification de l'un des champs
   avant le démarrage des fils a pour effet de définir des valeurs par
   défaut à l'échelle du système. La modification des champs après le
   démarrage des fils d'exécution n'est pas recommandée car cela
   nécessiterait une synchronisation des fils d'exécution pour éviter
   des situations de concurrence.

   Dans les environnements à fil d'exécution unique, il est préférable
   de ne pas utiliser ce contexte du tout. Créez plutôt simplement des
   contextes explicitement comme décrit ci-dessous.

   Les valeurs par défaut sont "Context.prec"="28",
   "Context.rounding"="ROUND_HALF_EVEN" et les interruptions sont
   activées pour "Overflow", "InvalidOperation" et "DivisionByZero".

En plus des trois contextes fournis, de nouveaux contextes peuvent
être créés avec le constructeur "Context".

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

   Crée un nouveau contexte. Si un champ n'est pas spécifié ou est
   "None", les valeurs par défaut sont copiées à partir du
   "DefaultContext". Si le champ *flags* n'est pas spécifié ou est
   "None", tous les indicateurs sont effacés.

   *prec* est un entier compris dans la plage ["1", "MAX_PREC"] qui
   définit la précision des opérations arithmétiques dans le contexte.

   L'option *rounding* est l'une des constantes répertoriées dans la
   section Modes d'arrondi.

   Les champs *traps* et *flags* répertorient tous les signaux à
   définir. En général, les nouveaux contextes ne doivent qu'activer
   des surveillances et laisser les drapeaux baissés.

   Les champs *Emin* et *Emax* sont des entiers spécifiant les valeurs
   limites autorisées pour les exposants. *Emin* doit être dans
   ["MIN_EMIN", "0"], *Emax* dans la plage ["0", "MAX_EMAX"].

   Le champ *capitals* est soit "0" soit "1" (la valeur par défaut).
   S'il est défini à "1", les exposants sont imprimés avec un "E"
   majuscule ; sinon, un "e" minuscule est utilisé :
   "Decimal('6.02e+23')".

   Le champ *clamp* est soit "0" (la valeur par défaut), soit "1".
   S'il est défini à "1", l'exposant "e" d'une instance "Decimal"
   représentable dans ce contexte est strictement limité à la plage
   "Emin - prec + 1 <= e <= Emax - prec + 1". Si *clamp* est "0" alors
   une condition plus faible est vraie : l'exposant ajusté de
   l'instance "Decimal" est au plus "Emax". Lorsque *clamp* vaut "1",
   un grand nombre normal voit, si possible, son exposant réduit et un
   nombre correspondant de zéros ajouté à sa mantisse, afin de
   s'adapter aux contraintes d'exposant ; cela préserve la valeur du
   nombre mais perd des informations sur les zéros significatifs. Par
   exemple :

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

   Une valeur *clamp* de "1" permet la compatibilité avec les formats
   d'échange décimaux à largeur fixe spécifiés dans la norme IEEE 754.

   La classe "Context" définit plusieurs méthodes à usage général
   ainsi qu'un grand nombre de méthodes permettant de faire de
   l'arithmétique directement dans un contexte donné. De plus, pour
   chacune des méthodes "Decimal" décrites ci-dessus (à l'exception
   des méthodes "adjusted()" et "as_tuple()"), il existe une méthode
   "Context" correspondante. Par exemple, pour une instance "Context"
   "C" et une instance "Decimal" "x", "C.exp(x)" est équivalent à
   "x.exp(context=C)". Chaque méthode "Context" accepte un entier
   Python (une instance de "int") partout où une instance Decimal est
   acceptée.

   clear_flags()

      Réinitialise tous les drapeaux à "0".

   clear_traps()

      Réinitialise toutes les surveillances à "0".

      Nouveau dans la version 3.3.

   copy()

      Renvoie une copie du contexte.

   copy_decimal(num)

      Renvoie une copie de l'instance "Decimal" *num*.

   create_decimal(num)

      Crée une nouvelle instance Decimal à partir de *num* mais en
      utilisant *self* comme contexte. Contrairement au constructeur
      "Decimal", la précision du contexte, la méthode d'arrondi, les
      drapeaux et leurs surveillances sont appliqués à la conversion.

      C'est utile car les constantes sont souvent données avec une
      précision supérieure à celle requise par l'application. Un autre
      avantage est que l’arrondi élimine immédiatement les effets
      involontaires des chiffres au-delà de la précision actuelle.
      Dans l'exemple suivant, l'utilisation d'entrées non arrondies
      signifie que l'ajout de zéro à une somme peut modifier le
      résultat :

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

      Cette méthode implémente l'opération *to-number* de la
      spécification IBM. Si l’argument est une chaîne, aucun espace ou
      trait de soulignement de début ou de fin n’est autorisé.

   create_decimal_from_float(f)

      Crée une nouvelle instance Decimal à partir d'un *float* *f*
      mais en arrondissant en utilisant *self* comme contexte.
      Contrairement à la méthode de classe "Decimal.from_float()", la
      précision du contexte, la méthode d'arrondi, les drapeaux et
      leurs surveillances sont appliqués à la conversion.

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

      Nouveau dans la version 3.1.

   Etiny()

      Renvoie une valeur égale à "Emin - prec + 1" qui est la valeur
      minimale de l'exposant pour les résultats avec dépassement
      inférieur. Lorsqu'un dépassement inférieur se produit,
      l'exposant est défini sur "Etiny".

   Etop()

      Renvoie une valeur égale à "Emax - prec + 1".

   L'approche habituelle pour travailler avec des décimaux consiste à
   créer des instances "Decimal", puis à appliquer des opérations
   arithmétiques qui ont lieu dans le contexte actuel du fil
   d'exécution actif. Une approche alternative consiste à utiliser des
   méthodes contextuelles pour calculer dans un contexte spécifique.
   Les méthodes sont similaires à celles de la classe "Decimal" et ne
   sont décrites que brièvement ici.

   abs(x)

      Renvoie la valeur absolue de *x*.

   add(x, y)

      Renvoie la somme de *x* et *y*.

   canonical(x)

      Renvoie l'objet Decimal *x* lui-même.

   compare(x, y)

      Compare *x* et *y* numériquement.

   compare_signal(x, y)

      Compare numériquement les valeurs des deux opérandes.

   compare_total(x, y)

      Compare deux opérandes en utilisant leur représentation
      abstraite.

   compare_total_mag(x, y)

      Compare deux opérandes en utilisant leur représentation
      abstraite, en ignorant le signe.

   copy_abs(x)

      Renvoie une copie de *x* avec le signe à 0 (c.-à-d. positif).

   copy_negate(x)

      Renvoie une copie de *x* mais de signe opposé.

   copy_sign(x, y)

      Copie le signe de *y* vers *x*.

   divide(x, y)

      Renvoie *x* divisé par *y*.

   divide_int(x, y)

      Renvoie *x* divisé par *y*, tronqué comme entier.

   divmod(x, y)

      Renvoie la partie entière de la division entre deux nombres.

   exp(x)

      Renvoie "e ** x".

   fma(x, y, z)

      Renvoie *x* multiplié par *y*, plus *z*.

   is_canonical(x)

      Renvoie "True" si *x* est canonique ; "False" sinon.

   is_finite(x)

      Renvoie "True" si *x* est fini ; "False" sinon.

   is_infinite(x)

      Renvoie "True" si *x* est infini et "False" sinon.

   is_nan(x)

      Renvoie "True" si *x* est un *NaN* (silencieux ou signalisé),
      "False" sinon.

   is_normal(x)

      Renvoie "True" si *x* est un nombre normal ; "False" sinon.

   is_qnan(x)

      Renvoie "True" si *x* est un *NaN* silencieux, "False" sinon.

   is_signed(x)

      Renvoie "True" si *x* est négatif et "False" sinon.

   is_snan(x)

      Renvoie "True" si *x* est un *NaN* signalisé, "False" sinon.

   is_subnormal(x)

      Renvoie "True" si *x* est est inférieur à la valeur minimale
      représentable ; sinon, renvoie "False".

   is_zero(x)

      Renvoie "True" si *x* est un zéro et "False" sinon.

   ln(x)

      Renvoie le logarithme naturel (en base e) de *x*.

   log10(x)

      Renvoie le logarithme en base 10 de *x*.

   logb(x)

      Renvoie l'exposant correspondant du chiffre de poids fort de la
      mantisse de l'opérande.

   logical_and(x, y)

      Applique l'opération logique *ET* entre les chiffres de chaque
      opérande.

   logical_invert(x)

      Inverse tous les chiffres de *x*.

   logical_or(x, y)

      Applique l'opération logique *OU* entre les chiffres de chaque
      opérande.

   logical_xor(x, y)

      Applique l'opération logique *OU EXCLUSIF* entre les chiffres de
      chaque opérande.

   max(x, y)

      Renvoie le maximum entre les deux valeurs numériques.

   max_mag(x, y)

      Compare les valeurs numériquement en ignorant leur signe.

   min(x, y)

      Compare numériquement deux valeurs et renvoie le minimum.

   min_mag(x, y)

      Compare les valeurs numériquement en ignorant leur signe.

   minus(x)

      Correspond à l’opérateur unaire préfixé « moins » en Python.

   multiply(x, y)

      Renvoie la multiplication de *x* avec *y*.

   next_minus(x)

      Renvoie le plus grand nombre représentable inférieur à *x*.

   next_plus(x)

      Renvoie le plus petit nombre représentable supérieur à *x*.

   next_toward(x, y)

      Renvoie le nombre le plus proche de *x*, en direction de *y*.

   normalize(x)

      Réduit *x* à sa forme la plus simple.

   number_class(x)

      Renvoie une indication de la classe de *x*.

   plus(x)

      Correspond à l'opérateur unaire préfixé « plus » en Python.
      Cette opération applique la précision du contexte et l'arrondi,
      ce n'est donc *pas* une opération d'identité.

   power(x, y, modulo=None)

      Renvoie "x" à la puissance "y", réduit modulo "modulo" si celui-
      ci est donné.

      Avec deux arguments, calcule "x**y". Si "x" est négatif alors
      "y" doit être entier. Le résultat est inexact à moins que "y"
      soit entier et que le résultat soit fini et puisse être exprimé
      exactement en "precision" chiffres. Le mode d'arrondi du
      contexte est utilisé. Les résultats sont toujours correctement
      arrondis à la manière de Python.

      "Decimal(0) ** Decimal(0)" donne "InvalidOperation" et, si
      "InvalidOperation" n'est pas surveillé, cela donne
      "Decimal('NaN')".

      Modifié dans la version 3.3: le module C calcule "power()" en
      termes de fonctions "exp()" et "ln()" correctement arrondies. Le
      résultat est bien défini mais seulement « presque toujours
      correctement arrondi ».

      Avec trois arguments, calcule "(x**y) % modulo". Pour la forme à
      trois arguments, les restrictions suivantes sur les arguments
      s'appliquent :

      * les trois arguments doivent être entiers ;

      * "y" ne doit pas être négatif ;

      * au moins l'un de "x" ou "y" doit être différent de zéro ;

      * "modulo" doit être différent de zéro et avoir au plus
        "precision" chiffres.

      La valeur résultant de "Context.power(x, y, modulo)" est égale à
      la valeur qui serait obtenue en calculant "(x**y) % modulo" avec
      une précision illimitée, mais est calculée plus efficacement.
      L'exposant du résultat est zéro, quels que soient les exposants
      de "x", "y" et "modulo". Le résultat est toujours exact.

   quantize(x, y)

      Renvoie une valeur égale à *x* (arrondie), ayant l'exposant de
      *y*.

   radix()

      Renvoie 10 car c'est "Decimal", :)

   remainder(x, y)

      Renvoie le reste de la division entière.

      Le signe du résultat, s'il est différent de zéro, est le même
      que celui du dividende initial.

   remainder_near(x, y)

      Renvoie "x - y * n", où *n* est l'entier le plus proche de la
      valeur exacte de "x / y" (si le résultat est 0 alors son signe
      est le signe de *x*).

   rotate(x, y)

      Renvoie une copie pivotée de *x*, *y* fois.

   same_quantum(x, y)

      Renvoie "True" si les deux opérandes ont le même exposant.

   scaleb(x, y)

      Renvoie le premier opérande après avoir ajouté la deuxième
      valeur à son *exp*.

   shift(x, y)

      Renvoie une copie décalée de *x*, *y* fois.

   sqrt(x)

      Renvoie la racine carrée d'un nombre non négatif avec la
      précision donnée par le contexte.

   subtract(x, y)

      Renvoie la différence entre *x* et *y*.

   to_eng_string(x)

      Convertit en chaîne, en utilisant la notation ingénieur si un
      exposant est nécessaire.

      La notation ingénieur possède un exposant qui est un multiple de
      3. Cela peut laisser jusqu'à 3 chiffres à gauche de la décimale
      et peut nécessiter l'ajout d'un ou de deux zéros en fin de
      mantisse.

   to_integral_exact(x)

      Arrondit à un entier.

   to_sci_string(x)

      Convertit un nombre en chaîne en utilisant la notation
      scientifique.


Constantes
==========

Les constantes de cette section ne sont pertinentes que pour le module
implémenté en C. Elles sont incluses dans la version en Python pur
pour raison de compatibilité .

+-----------------------+-----------------------+---------------------------------+
|                       | 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.HAVE_THREADS

   La valeur est "True". C'est obsolète, car maintenant Python gère
   toujours les fils d'exécution.

Obsolète depuis la version 3.9.

decimal.HAVE_CONTEXTVAR

   La valeur par défaut est "True". Si Python est "configuré à l'aide
   de l'option --without-decimal-contextvar", la version C utilise un
   contexte lié au fil d'exécution plutôt qu'un contexte lié à la
   coroutine et la valeur est "False". Ceci est légèrement plus rapide
   dans certains scénarios où les contextes sont imbriqués.

Nouveau dans la version 3.8.3.


Modes d'arrondi
===============

decimal.ROUND_CEILING

   Arrondit vers "Infinity".

decimal.ROUND_DOWN

   Arrondit vers zéro.

decimal.ROUND_FLOOR

   Arrondit vers "-Infinity".

decimal.ROUND_HALF_DOWN

   Arrondit au plus proche, en allant vers zéro si l'on est au milieu.

decimal.ROUND_HALF_EVEN

   Arrondit au plus proche, en allant à l'entier pair le plus proche
   si l'on est au milieu.

decimal.ROUND_HALF_UP

   Arrondit au plus proche, en s'éloignant de zéro si l'on est au
   milieu.

decimal.ROUND_UP

   Arrondit en s'éloignant de zéro.

decimal.ROUND_05UP

   Arrondit en s'éloignant de zéro si le dernier chiffre après
   l'arrondi vers zéro aurait été 0 ou 5 ; sinon arrondit en se
   rapprochant de zéro.


Signaux
=======

Les signaux représentent les états différents pendant le calcul.
Chacun de ces états est associé à un drapeau (*flag*) du contexte
courant et peut être surveillé (via un *trap*) dans le contexte
courant.

L'indicateur de contexte est levé chaque fois que l'on rentre dans
l'état. Après le calcul, les indicateurs peuvent être vérifiés à des
fins d'information (par exemple, pour déterminer si un calcul était
exact). Après avoir vérifié les indicateurs, assurez-vous de tous les
effacer avant de commencer le calcul suivant.

Si le signal est surveillé dans le contexte, l'entrée dans l'état
provoque le déclenchement d'une exception Python. Par exemple, si
"DivisionByZero" est surveillé, alors une exception "DivisionByZero"
est levée lorsque cette condition est remplie.

class decimal.Clamped

   Modification d'un exposant pour l'adapter aux contraintes de
   représentation.

   En règle générale, cela se produit lorsqu'un exposant se situe en
   dehors des limites "Emin" et "Emax" du contexte. Si possible,
   l'exposant est réduit pour s'adapter en ajoutant des zéros à la
   mantisse.

class decimal.DecimalException

   Classe mère pour d'autres signaux et une sous-classe de
   "ArithmeticError".

class decimal.DivisionByZero

   Signale la division d'un nombre non infini par zéro.

   Peut se produire lors d’une division, d’une division modulo ou lors
   de l’élévation d’un nombre à une puissance négative. Si ce signal
   n'est pas surveillé, renvoie "Infinity" ou "-Infinity" avec le
   signe déterminé par les entrées du calcul.

class decimal.Inexact

   Indique qu'un arrondi a eu lieu et que le résultat n'est pas exact.

   Se produit lorsque des chiffres non nuls ont été supprimés lors de
   l'arrondi. Le résultat arrondi est renvoyé. Le drapeau de
   signalisation ou la surveillance sont utilisés pour détecter
   lorsque les résultats sont inexacts.

class decimal.InvalidOperation

   Une opération non valide a été effectuée.

   Indique qu'une opération demandée n'a aucun sens. S'il n'est pas
   surveillé, renvoie "NaN". Les causes possibles incluent :

      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

   Débordement numérique.

   Indique que l'exposant est supérieur à "Context.Emax" après
   l'arrondi. S'il n'est pas surveillé, le résultat dépend du mode
   d'arrondi, soit en tirant vers l'intérieur jusqu'au plus grand
   nombre fini représentable, soit en arrondissant vers l'extérieur à
   "Infinity". Dans les deux cas, "Inexact" et "Rounded" sont
   également signalés.

class decimal.Rounded

   Des arrondis ont eu lieu, même s'il est possible qu'aucune
   information n'ait été perdue.

   Signalé chaque fois que l'arrondi supprime des chiffres ; même si
   ces chiffres sont nuls (par exemple en arrondissant "5.00" à
   "5.0"). S'il n'est pas surveillé, renvoie le résultat inchangé. Ce
   signal est utilisé pour détecter la perte de chiffres
   significatifs.

class decimal.Subnormal

   L'exposant était inférieur à "Emin" avant l'arrondi.

   Se produit lorsque le résultat d'une opération est dénormalisé
   (l'exposant est trop petit). S'il n'est pas surveillé, renvoie le
   résultat inchangé.

class decimal.Underflow

   Sous-dépassement numérique avec résultat arrondi à zéro.

   Se produit lorsqu'un résultat dénormalisé est ramené à zéro par
   arrondi. "Inexact" et "Subnormal" sont également signalés.

class decimal.FloatOperation

   Active une sémantique plus stricte prévenant le mélange non
   souhaité de flottants et de décimaux.

   Si le signal n'est pas surveillé (par défaut), le mélange de
   flottants et de décimaux est autorisé dans le constructeur
   "Decimal", "create_decimal()" et tous les opérateurs de
   comparaison. La conversion et les comparaisons sont exactes. Toute
   occurrence d'une opération mixte est enregistrée silencieusement en
   levant "FloatOperation" dans les indicateurs de contexte. Les
   conversions explicites avec "from_float()" ou
   "create_decimal_from_float()" ne lèvent pas l'indicateur.

   Sinon (le signal est surveillé), seules les comparaisons d'égalité
   et les conversions explicites sont silencieuses. Toutes les autres
   opérations mixtes lèvent "FloatOperation".

Le tableau suivant résume la hiérarchie des signaux :

   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)


Notes pour les nombres à virgule flottante
==========================================


Atténuation des erreurs d'arrondi avec une précision accrue
-----------------------------------------------------------

L'utilisation de la virgule flottante décimale élimine l'erreur de
représentation décimale (ce qui permet de représenter "0.1"
exactement) ; cependant, certaines opérations peuvent toujours
entraîner une erreur d'arrondi lorsque des chiffres non nuls dépassent
la précision fixée.

Les effets de l’erreur d’arrondi peuvent être amplifiés par l’ajout ou
la soustraction de quantités proches de la limite d'arrondi,
entraînant une perte de précision. Knuth fournit deux exemples
instructifs où l'arithmétique à virgule flottante arrondie avec une
précision insuffisante provoque la rupture des propriétés associatives
et distributives de l'addition :

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

Le module "decimal" permet de rétablir les identités en étendant
suffisamment la précision pour éviter la perte de précision :

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


Valeurs spéciales
-----------------

La représentation des nombres du module "decimal" fournit des valeurs
spéciales, notamment "NaN", "sNaN", "-Infinity", "Infinity" et deux
zéros, "+0" et "-0".

Les infinis peuvent être construits directement avec
"Decimal('Infinity')". En outre, ils peuvent résulter d'une division
par zéro lorsque le signal "DivisionByZero" n'est pas surveillé. De
même, lorsque le signal "Overflow" n'est pas surveillé, l'infini peut
résulter d'un arrondi au-delà des limites du plus grand nombre
représentable.

Les infinis sont signés (« points à l'infini ») et peuvent être
utilisés dans des opérations arithmétiques où ils sont traités comme
de très grands nombres indéterminés. Par exemple, ajouter une
constante à l’infini donne un autre résultat infini.

Certaines opérations sont indéterminées et renvoient "NaN" ou, si le
signal "InvalidOperation" est surveillé, déclenchent une exception.
Par exemple, "0/0" renvoie "NaN" qui signifie « pas un nombre » (*not
a number* en anglais). Cette espèce de "NaN" est silencieuse et, une
fois créée, elle peut intervenir dans d'autres calculs, aboutissant
toujours à un autre "NaN". Ce comportement peut être utile pour une
série de calculs qui comportent parfois des entrées manquantes : il
permet au calcul de se poursuivre tout en indiquant que les résultats
ne sont pas valides.

Une variante est "sNaN" qui lève un signal plutôt que de rester
silencieux après chaque opération. Il s'agit d'une valeur de retour
utile lorsqu'un résultat non valide doit interrompre un calcul pour
effectuer un traitement spécial.

Le comportement des opérateurs de comparaison de Python peut être un
peu surprenant lorsqu'un "NaN" est impliqué. Un test d'égalité où l'un
des opérandes est un "NaN" silencieux ou de signalisation renvoie
toujours "False" (même en faisant "Decimal('NaN')==Decimal('NaN')") ,
tandis qu'un test d'inégalité renvoie toujours "True". Une tentative
de comparaison de deux *Decimals* en utilisant l'un des opérateurs
"<", "<=", ">" ou ">=" lève une "InvalidOperation" si l'un ou l'autre
des opérandes est un "NaN", et renvoie "False" si ce signal n'est pas
surveillé. Notez que la spécification General Decimal Arithmetic ne
spécifie pas le comportement des comparaisons directes ; ces règles de
comparaison impliquant un "NaN" sont tirées de la norme IEEE 854 (voir
tableau 3 dans la section 5.7). Pour garantir une stricte conformité
aux normes, utilisez plutôt les méthodes "compare()" et
"compare_signal()".

Les zéros signés peuvent résulter de calculs qui débordent. Ils
gardent le signe qui aurait résulté si le calcul avait été effectué
avec plus de précision. Puisque leur grandeur est nulle, les zéros
positifs et négatifs sont traités comme égaux et leur signe est
informatif.

En plus des deux zéros signés, distincts mais égaux, il existe
diverses représentations du zéro avec des précisions différentes mais
de valeur équivalente. Cela prend un peu de temps pour s’y habituer.
Pour un œil habitué aux représentations normalisées à virgule
flottante, il n’est pas immédiatement évident que le calcul suivant
renvoie une valeur égale à zéro :

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


Travailler avec plusieurs fils d'exécution
==========================================

La fonction "getcontext()" accède à un objet "Context" différent pour
chaque fil d'exécution. Avoir des contextes de fil d'exécution séparés
signifie que les fils peuvent apporter des modifications (telles que
"getcontext().prec=10") sans interférer avec les autres fils.

De même, la fonction "setcontext()" assigne automatiquement sa cible
au fil d'exécution actuel.

Si "setcontext()" n'a pas été appelé avant "getcontext()", alors
"getcontext()" crée automatiquement un nouveau contexte à utiliser
dans le fil actuel.

Le nouveau contexte est copié à partir d'un contexte prototype appelé
*DefaultContext*. Pour contrôler les valeurs par défaut afin que
chaque fil utilise les mêmes valeurs dans toute l'application,
modifiez directement l'objet *DefaultContext*. Cela doit être fait
*avant* que les fil d'exécution ne soient démarrés afin qu'il n'y ait
pas de situation de concurrence entre les fils appelant
"getcontext()". Par exemple :

   # 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()
    . . .


Cas pratiques
=============

Voici quelques exemples de fonctions utilitaires qui montrent comment
travailler avec la classe "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


FAQ *decimal*
=============

Q. Il est fastidieux de taper "decimal.Decimal('1234.5')". Y a-t-il un
moyen de réduire la frappe quand on utilise l'interpréteur interactif
?

R. Certains utilisateurs abrègent le constructeur en une seule lettre
:

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

Q. Dans une application à virgule fixe avec deux décimales, certaines
entrées comportent plusieurs chiffres excédentaires et doivent être
arrondies. D'autres ne sont pas censées avoir de chiffres
excédentaires et doivent être validées. Quelles méthodes utiliser ?

R. La méthode "quantize()" arrondit à un nombre fixe de décimales. Si
"Inexact" est surveillé, elle est aussi utile pour la validation :

>>> 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. Une fois que mes entrées sont à deux décimales valides, comment
maintenir cet invariant dans l'application ?

R. Certaines opérations comme l'addition, la soustraction et la
multiplication par un entier préservent automatiquement la virgule
fixe. D'autres opérations, comme la division et la multiplication par
des non-entiers, changent le nombre de décimales et doivent être
suivies d'une étape "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')

Lors du développement d'applications en virgule fixe, il est pratique
de définir des fonctions pour gérer cette étape de quantification par
"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. Il existe de nombreuses façons d’exprimer la même valeur. Les
nombres "200", "200.000", "2E2" et ".02E+4" ont tous la même valeur à
différentes précisions. Existe-t-il un moyen de les transformer en une
seule valeur canonique reconnaissable ?

R. La méthode "normalize()" transforme toutes les valeurs équivalentes
en un seul représentant :

>>> 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. Quand l’arrondi se produit-il dans un calcul ?

R. Il se produit *après* le calcul. La philosophie de la spécification
décimale est que les nombres sont considérés comme exacts et sont
créés indépendamment du contexte actuel. Ils peuvent même avoir une
plus grande précision que le contexte actuel. Le processus effectue
les calculs avec ces entrées exactes, puis l'arrondi (ou d'autres
opérations contextuelles) est appliqué au *résultat* du calcul :

   >>> 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. Certaines valeurs décimales s'affichent toujours en notation
scientifique. Existe-t-il un moyen d'obtenir une représentation sans
exposant ?

R. Pour certaines valeurs, la notation scientifique est la seule façon
d'exprimer le nombre de chiffres significatifs dans la mantisse. Par
exemple, exprimer "5.0E+3" par "5000" maintient la valeur constante
mais ne peut pas montrer les deux chiffres significatifs de
l'original.

Si une application ne se soucie pas du maintien du nombre de chiffres
significatifs, il est facile de supprimer l'exposant et les zéros de
fin, ce qui modifie le nombre de chiffres significatifs, mais garde la
valeur inchangée :

>>> 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. Existe-t-il un moyen de convertir un *float* normal en "Decimal" ?

R. Oui, tout nombre à virgule flottante *float* peut être exprimé
exactement sous forme décimale, bien qu'une conversion exacte puisse
nécessiter plus de précision que ne le suggère l'intuition :

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

Q. Dans un calcul complexe, comment puis-je m'assurer que je n'ai pas
obtenu de résultat erroné en raison d'un manque de précision ou
d'anomalies d'arrondi.

R. Le module *decimal* facilite le test des résultats. Une bonne
pratique consiste à refaire les calculs avec une plus grande précision
et avec différents modes d'arrondi. Des résultats très différents
indiquent une précision insuffisante, des problèmes de mode d'arrondi,
des entrées mal conditionnées ou un algorithme numériquement instable.

Q. J'ai remarqué que la précision du contexte est appliquée aux
résultats des opérations mais pas aux entrées. Y a-t-il quelque chose
à surveiller lors du mélange de valeurs de précisions différentes ?

R. Oui. Le principe est que toutes les valeurs sont considérées comme
exactes, tout comme l’arithmétique sur ces valeurs. Seuls les
résultats sont arrondis. L'avantage des entrées est que « ce que vous
tapez est ce que vous obtenez ». Un inconvénient est que les résultats
peuvent paraître étranges si vous oubliez que les entrées n'ont pas
été arrondies :

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

La solution consiste soit à augmenter la précision, soit à forcer
l'arrondi des entrées à l'aide de l'opération unaire plus :

   >>> getcontext().prec = 3
   >>> +Decimal('1.23456789')      # unary plus triggers rounding
   Decimal('1.23')

Autrement, les entrées peuvent être arrondies lors de la création à
l'aide de la méthode "Context.create_decimal()" :

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

Q. L'implémentation de CPython est-elle rapide pour les grands nombres
?

R. Oui. Dans les implémentations CPython et PyPy3, les versions C/CFFI
du module décimal intègrent correctement la bibliothèque haute vitesse
libmpdec  pour une précision arbitraire en arithmétique à virgule
flottante décimale arrondie [1]. "libmpdec" utilise la multiplication
Karatsuba pour les nombres de taille moyenne et la transformation de
Fourier discrète pour les très grands nombres.

Le contexte doit être adapté pour une arithmétique de précision
arbitraire exacte. "Emin" et "Emax" doivent toujours être définis sur
les valeurs maximales, "clamp" doit toujours être 0 (valeur par
défaut). Le réglage de "prec" nécessite une certaine prudence.

L'approche la plus simple pour essayer l'arithmétique sur les grands
nombres est d'utiliser également la valeur maximale pour "prec" [2] :

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

Pour des résultats inexacts, "MAX_PREC" est beaucoup trop volumineux
sur les plateformes 64 bits et la mémoire disponible sera insuffisante
:

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

Sur les systèmes avec mémoire virtuelle (par exemple Linux), une
approche plus sophistiquée consiste à ajuster "prec" à la quantité de
RAM disponible. Supposons que vous disposiez de 8 Go de RAM et que
vous voulez traiter 10 opérandes simultanés utilisant un maximum de
500 Mo chacun :

   >>> import sys
   >>>
   >>> # Maximum number of digits for a single operand using 500MB in 8-byte words
   >>> # with 19 digits per word (4-byte and 9 digits for the 32-bit build):
   >>> maxdigits = 19 * ((500 * 1024**2) // 8)
   >>>
   >>> # Check that this works:
   >>> c = Context(prec=maxdigits, Emax=MAX_EMAX, Emin=MIN_EMIN)
   >>> c.traps[Inexact] = True
   >>> setcontext(c)
   >>>
   >>> # Fill the available precision with nines:
   >>> 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'>]

En général (et en particulier sur les systèmes sans mémoire
virtuelle), il est recommandé d'estimer des limites encore plus
strictes et de surveiller "Inexact" si l'on veut que tous les calculs
soient exacts.

[1] Nouveau dans la version 3.3.

[2] Modifié dans la version 3.9: Cette approche fonctionne désormais
    pour tous les résultats exacts, à l'exception des puissances non
    entières.
