Decimal capsule API
*******************

Capsule API functions can be used in the same manner as regular
library functions, provided that the API has been initialized.


Initialize
==========

Typically, a C extension module that uses the decimal API will do
these steps in its init function:

   #include "pydecimal.h"

   static int decimal_initialized = 0;
   if (!decimal_initialized) {
       if (import_decimal() < 0) {
           return NULL;
       }

       decimal_initialized = 1;
   }


Type checking, predicates, accessors
====================================

int PyDec_TypeCheck(const PyObject *dec)

   Return 1 if "dec" is a Decimal, 0 otherwise.  This function does
   not set any exceptions.

int PyDec_IsSpecial(const PyObject *dec)

   Return 1 if "dec" is "NaN", "sNaN" or "Infinity", 0 otherwise.

   Set TypeError and return -1 if "dec" is not a Decimal.  It is
   guaranteed that this is the only failure mode, so if "dec" has
   already been type-checked, no errors can occur and the function can
   be treated as a simple predicate.

int PyDec_IsNaN(const PyObject *dec)

   Return 1 if "dec" is "NaN" or "sNaN", 0 otherwise.

   Set TypeError and return -1 if "dec" is not a Decimal.  It is
   guaranteed that this is the only failure mode, so if "dec" has
   already been type-checked, no errors can occur and the function can
   be treated as a simple predicate.

int PyDec_IsInfinite(const PyObject *dec)

   Return 1 if "dec" is "Infinity", 0 otherwise.

   Set TypeError and return -1 if "dec" is not a Decimal.  It is
   guaranteed that this is the only failure mode, so if "dec" has
   already been type-checked, no errors can occur and the function can
   be treated as a simple predicate.

int64_t PyDec_GetDigits(const PyObject *dec)

   Return the number of digits in the coefficient.  For "Infinity",
   the number of digits is always zero.  Typically, the same applies
   to "NaN" and "sNaN", but both of these can have a payload that is
   equivalent to a coefficient.  Therefore, "NaNs" can have a nonzero
   return value.

   Set TypeError and return -1 if "dec" is not a Decimal.  It is
   guaranteed that this is the only failure mode, so if "dec" has
   already been type-checked, no errors can occur and the function can
   be treated as a simple accessor.


Exact conversions between decimals and primitive C types
========================================================

This API supports conversions for decimals with a coefficient up to 38
digits.


Data structures
---------------

The conversion functions use the following status codes and data
structures:

   /* status cases for getting a triple */
   enum mpd_triple_class {
     MPD_TRIPLE_NORMAL,
     MPD_TRIPLE_INF,
     MPD_TRIPLE_QNAN,
     MPD_TRIPLE_SNAN,
     MPD_TRIPLE_ERROR,
   };

   typedef struct {
     enum mpd_triple_class tag;
     uint8_t sign;
     uint64_t hi;
     uint64_t lo;
     int64_t exp;
   } mpd_uint128_triple_t;

The status cases are explained below.  "sign" is 0 for positive and 1
for negative. "((uint128_t)hi << 64) + lo" is the coefficient, "exp"
is the exponent.

The data structure is called "triple" because the decimal triple
(sign, coeff, exp) is an established term and ("hi", "lo") represents
a single "uint128_t" coefficient.


Functions
---------

mpd_uint128_triple_t PyDec_AsUint128Triple(const PyObject *dec)

   Convert a decimal to a triple.  As above, it is guaranteed that the
   only Python failure mode is a TypeError, checks can be omitted if
   the type is known.

   For simplicity, the usage of the function and all special cases are
   explained in code form and comments:

   triple = PyDec_AsUint128Triple(dec);
   switch (triple.tag) {
   case MPD_TRIPLE_QNAN:
       /*
        * Success: handle a quiet NaN.
        *   1) triple.sign is 0 or 1.
        *   2) triple.exp is always 0.
        *   3) If triple.hi or triple.lo are nonzero, the NaN has a payload.
        */
       break;

   case MPD_TRIPLE_SNAN:
       /*
        * Success: handle a signaling NaN.
        *   1) triple.sign is 0 or 1.
        *   2) triple.exp is always 0.
        *   3) If triple.hi or triple.lo are nonzero, the sNaN has a payload.
        */
       break;

   case MPD_TRIPLE_INF:
       /*
        * Success: handle Infinity.
        *   1) triple.sign is 0 or 1.
        *   2) triple.exp is always 0.
        *   3) triple.hi and triple.lo are always zero.
        */
       break;

   case MPD_TRIPLE_NORMAL:
       /* Success: handle a finite value. */
       break;

   case MPD_TRIPLE_ERROR:
       /* TypeError check: can be omitted if the type of dec is known. */
       if (PyErr_Occurred()) {
           return NULL;
       }

       /* Too large for conversion.  PyDec_AsUint128Triple() does not set an
          exception so applications can choose themselves.  Typically this
          would be a ValueError. */
       PyErr_SetString(PyExc_ValueError,
           "value out of bounds for a uint128 triple");
       return NULL;
   }

PyObject *PyDec_FromUint128Triple(const mpd_uint128_triple_t *triple)

   Create a decimal from a triple.  The following rules must be
   observed for initializing the triple:

   1. "triple.sign" must always be 0 (for positive) or 1 (for
      negative).

   2. "MPD_TRIPLE_QNAN": "triple.exp" must be 0.  If "triple.hi" or
      "triple.lo" are nonzero,  create a "NaN" with a payload.

   3. "MPD_TRIPLE_SNAN": "triple.exp" must be 0. If "triple.hi" or
      "triple.lo" are nonzero,  create an "sNaN" with a payload.

   4. "MPD_TRIPLE_INF": "triple.exp", "triple.hi" and "triple.lo" must
      be zero.

   5. "MPD_TRIPLE_NORMAL": "MPD_MIN_ETINY + 38 < triple.exp <
      MPD_MAX_EMAX - 38". "triple.hi" and "triple.lo" can be chosen
      freely.

   6. "MPD_TRIPLE_ERROR": It is always an error to set this tag.

   If one of the above conditions is not met, the function returns
   "NaN" if the "InvalidOperation" trap is not set in the thread local
   context.  Otherwise, it sets the "InvalidOperation" exception and
   returns NULL.

   Additionally, though extremely unlikely give the small allocation
   sizes, the function can set "MemoryError" and return "NULL".


Advanced API
============

This API enables the use of "libmpdec" functions.  Since Python is
compiled with hidden symbols, the API requires an external libmpdec
and the "mpdecimal.h" header.


Functions
---------

PyObject *PyDec_Alloc(void)

   Return a new decimal that can be used in the "result" position of
   "libmpdec" functions.

mpd_t *PyDec_Get(PyObject *v)

   Get a pointer to the internal "mpd_t" of the decimal.  Decimals are
   immutable, so this function must only be used on a new Decimal that
   has been created by PyDec_Alloc().

const mpd_t *PyDec_GetConst(const PyObject *v)

   Get a pointer to the constant internal "mpd_t" of the decimal.
