整数型オブジェクト (integer object)
***********************************

すべての整数は任意の長さをもつ "long" 整数として実装されます。

エラーが起きると、ほとんどの "PyLong_As*" API は "(return type)-1" を
返しますが、これは数値と見分けが付きません。 見分けを付けるためには
"PyErr_Occurred()" を使ってください。

type PyLongObject
    * 次に属します: Limited API (不透明な構造体として).*

   この "PyObject" のサブタイプは整数型を表現します。

PyTypeObject PyLong_Type
    * 次に属します: Stable ABI.*

   この "PyTypeObject" のインスタンスは Python 整数型を表現します。こ
   れは Python レイヤにおける "int" と同じオブジェクトです。

int PyLong_Check(PyObject *p)

   引数が "PyLongObject" か "PyLongObject" のサブタイプであるときに真
   を返します。この関数は常に成功します。

int PyLong_CheckExact(PyObject *p)

   引数が "PyLongObject" であるが "PyLongObject" のサブタイプでないと
   きに真を返します。この関数は常に成功します。

PyObject *PyLong_FromLong(long v)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   *v* から新たな "PyLongObject" オブジェクトを生成して返します。失敗
   のときには "NULL" を返します。

   現在の実装では、"-5" から "256" までの全ての整数に対する整数オブジ
   ェクトの配列を保持します。この範囲の数を生成すると、実際には既存の
   オブジェクトに対する参照が返るようになっています。

PyObject *PyLong_FromUnsignedLong(unsigned long v)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   Cの unsigned long から新たな "PyLongObject" オブジェクトを生成して
   返します。失敗した際には "NULL" を返します。

PyObject *PyLong_FromSsize_t(Py_ssize_t v)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   C の "Py_ssize_t" 型から新たな "PyLongObject" オブジェクトを生成し
   て返します。 失敗のときには "NULL" を返します。

PyObject *PyLong_FromSize_t(size_t v)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   C の "size_t" 型から新たな "PyLongObject" オブジェクトを生成して返
   します。 失敗のときには "NULL" を返します。

PyObject *PyLong_FromLongLong(long long v)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   C の long long 型から新たな "PyLongObject" オブジェクトを生成して返
   します。失敗のときには "NULL" を返します。

PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   C の unsigned long long 型から新たな "PyLongObject" オブジェクトを
   生成して返します。失敗のときには "NULL" を返します。

PyObject *PyLong_FromDouble(double v)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   *v* の整数部から新たな "PyLongObject" オブジェクトを生成して返しま
   す。失敗のときには "NULL" を返します。

PyObject *PyLong_FromString(const char *str, char **pend, int base)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   Return a new "PyLongObject" based on the string value in *str*,
   which is interpreted according to the radix in *base*, or "NULL" on
   failure.  If *pend* is non-"NULL", **pend* will point to the end of
   *str* on success or to the first character that could not be
   processed on error.  If *base* is "0", *str* is interpreted using
   the 整数リテラル definition; in this case, leading zeros in a non-
   zero decimal number raises a "ValueError".  If *base* is not "0",
   it must be between "2" and "36", inclusive.  Leading and trailing
   whitespace and single underscores after a base specifier and
   between digits are ignored.  If there are no digits or *str* is not
   NULL-terminated following the digits and trailing whitespace,
   "ValueError" will be raised.

   参考:

     Python methods "int.to_bytes()" and "int.from_bytes()" to convert
     a "PyLongObject" to/from an array of bytes in base "256". You can
     call those from C using "PyObject_CallMethod()".

PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)
    *戻り値: 新しい参照。*

   Convert a sequence of Unicode digits in the string *u* to a Python
   integer value.

   Added in version 3.3.

PyObject *PyLong_FromVoidPtr(void *p)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   ポインタ *p* から Python 整数値を生成します。ポインタの値は
   "PyLong_AsVoidPtr()" を適用した結果から取得されます。

long PyLong_AsLong(PyObject *obj)
    * 次に属します: Stable ABI.*

   Return a C long representation of *obj*.  If *obj* is not an
   instance of "PyLongObject", first call its "__index__()" method (if
   present) to convert it to a "PyLongObject".

   もし *obj* の値が long の範囲外であれば、 "OverflowError" を送出し
   ます。

   エラーが起きたときに "-1" を返します。 見分けを付けるためには
   "PyErr_Occurred()" を使ってください。

   バージョン 3.8 で変更: 可能であれば "__index__()" を使うようになり
   ました。

   バージョン 3.10 で変更: This function will no longer use
   "__int__()".

   long PyLong_AS_LONG(PyObject *obj)

      A *soft deprecated* alias. Exactly equivalent to the preferred
      "PyLong_AsLong". In particular, it can fail with "OverflowError"
      or another exception.

      バージョン 3.14 で非推奨: The function is soft deprecated.

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
    * 次に属します: Stable ABI.*

   Return a C long representation of *obj*.  If *obj* is not an
   instance of "PyLongObject", first call its "__index__()" method (if
   present) to convert it to a "PyLongObject".

   If the value of *obj* is greater than "LONG_MAX" or less than
   "LONG_MIN", set **overflow* to "1" or "-1", respectively, and
   return "-1"; otherwise, set **overflow* to "0".  If any other
   exception occurs set **overflow* to "0" and return "-1" as usual.

   エラーが起きたときに "-1" を返します。 見分けを付けるためには
   "PyErr_Occurred()" を使ってください。

   バージョン 3.8 で変更: 可能であれば "__index__()" を使うようになり
   ました。

   バージョン 3.10 で変更: This function will no longer use
   "__int__()".

long long PyLong_AsLongLong(PyObject *obj)
    * 次に属します: Stable ABI.*

   Return a C long long representation of *obj*.  If *obj* is not an
   instance of "PyLongObject", first call its "__index__()" method (if
   present) to convert it to a "PyLongObject".

   もし *obj* の値が long long の範囲外であれば、 "OverflowError" を送
   出します。

   エラーが起きたときに "-1" を返します。 見分けを付けるためには
   "PyErr_Occurred()" を使ってください。

   バージョン 3.8 で変更: 可能であれば "__index__()" を使うようになり
   ました。

   バージョン 3.10 で変更: This function will no longer use
   "__int__()".

long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
    * 次に属します: Stable ABI.*

   Return a C long long representation of *obj*.  If *obj* is not an
   instance of "PyLongObject", first call its "__index__()" method (if
   present) to convert it to a "PyLongObject".

   If the value of *obj* is greater than "LLONG_MAX" or less than
   "LLONG_MIN", set **overflow* to "1" or "-1", respectively, and
   return "-1"; otherwise, set **overflow* to "0".  If any other
   exception occurs set **overflow* to "0" and return "-1" as usual.

   エラーが起きたときに "-1" を返します。 見分けを付けるためには
   "PyErr_Occurred()" を使ってください。

   Added in version 3.2.

   バージョン 3.8 で変更: 可能であれば "__index__()" を使うようになり
   ました。

   バージョン 3.10 で変更: This function will no longer use
   "__int__()".

Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
    * 次に属します: Stable ABI.*

   *pylong* を表す C の "Py_ssize_t" を返します。 *pylong* は
   "PyLongObject" のインスタンスでなければなりません。

   もし *pylong* の値が "Py_ssize_t" の範囲外であれば、
   "OverflowError" を送出します。

   エラーが起きたときに "-1" を返します。 見分けを付けるためには
   "PyErr_Occurred()" を使ってください。

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
    * 次に属します: Stable ABI.*

   *pylong* を表す C の unsigned long を返します。 *pylong* は
   "PyLongObject" のインスタンスでなければなりません。

   もし *pylong* の値が unsigned long の範囲外であれば、
   "OverflowError" を送出します。

   エラーが起きたときに "(unsigned long)-1" を返します。 見分けを付け
   るためには  "PyErr_Occurred()" を使ってください。

size_t PyLong_AsSize_t(PyObject *pylong)
    * 次に属します: Stable ABI.*

   *pylong* を表す C の "size_t" を返します。 *pylong* は
   "PyLongObject" のインスタンスでなければなりません。

   もし *pylong* の値が "size_t" の範囲外であれば、 "OverflowError" を
   送出します。

   エラーが起きたときに "(size_t)-1" を返します。 見分けを付けるために
   は  "PyErr_Occurred()" を使ってください。

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)
    * 次に属します: Stable ABI.*

   *pylong* を表す C の unsigned long long を返します。 *pylong* は
   "PyLongObject" のインスタンスでなければなりません。

   もし *pylong* の値が unsigned long long の範囲外であれば、
   "OverflowError" を送出します。

   エラーが起きたときに "(unsigned long long)-1" を返します。 見分けを
   付けるためには  "PyErr_Occurred()" を使ってください。

   バージョン 3.1 で変更: 負 *pylong* を指定した際に "TypeError" では
   なく、 "OverflowError" を送出するようになりました。

unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
    * 次に属します: Stable ABI.*

   Return a C unsigned long representation of *obj*.  If *obj* is not
   an instance of "PyLongObject", first call its "__index__()" method
   (if present) to convert it to a "PyLongObject".

   *obj* の値が unsigned long の範囲から外れていた場合は、 "ULONG_MAX
   + 1" を法とした剰余を返します。

   エラーが起きたときに "(unsigned long)-1" を返します。 見分けを付け
   るためには  "PyErr_Occurred()" を使ってください。

   バージョン 3.8 で変更: 可能であれば "__index__()" を使うようになり
   ました。

   バージョン 3.10 で変更: This function will no longer use
   "__int__()".

unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)
    * 次に属します: Stable ABI.*

   Return a C unsigned long long representation of *obj*.  If *obj* is
   not an instance of "PyLongObject", first call its "__index__()"
   method (if present) to convert it to a "PyLongObject".

   *obj* の値が unsigned long long の範囲から外れていた場合は、
   "ULLONG_MAX + 1" を法とした剰余を返します。

   エラーが起きたときに "(unsigned long long)-1" を返します。 見分けを
   付けるためには  "PyErr_Occurred()" を使ってください。

   バージョン 3.8 で変更: 可能であれば "__index__()" を使うようになり
   ました。

   バージョン 3.10 で変更: This function will no longer use
   "__int__()".

double PyLong_AsDouble(PyObject *pylong)
    * 次に属します: Stable ABI.*

   *pylong* を表す C の double を返します。 *pylong* は "PyLongObject"
   のインスタンスでなければなりません。

   もし *pylong* の値が double の範囲外であれば、 "OverflowError" を送
   出します。

   エラーが起きたときに "-1.0" を返します。 見分けを付けるためには
   "PyErr_Occurred()" を使ってください。

void *PyLong_AsVoidPtr(PyObject *pylong)
    * 次に属します: Stable ABI.*

   Python の整数型を指す *pylong* を、 C の void ポインタに変換します
   。 *pylong* を変換できなければ、 "OverflowError" を送出します。この
   関数は "PyLong_FromVoidPtr()" で値を生成するときに使うような void
   ポインタ型を生成できるだけです。

   エラーが起きたときに "NULL" を返します。 見分けを付けるためには
   "PyErr_Occurred()" を使ってください。

PyObject *PyLong_GetInfo(void)
    * 次に属します: Stable ABI.*

   On success, return a read only *named tuple*, that holds
   information about Python's internal representation of integers. See
   "sys.int_info" for description of individual fields.

   On failure, return "NULL" with an exception set.

   Added in version 3.1.

int PyUnstable_Long_IsCompact(const PyLongObject *op)

   *これは Unstable APIです。マイナーリリースで予告なく変更されること
   があります。*

   Return 1 if *op* is compact, 0 otherwise.

   This function makes it possible for performance-critical code to
   implement a “fast path” for small integers. For compact values use
   "PyUnstable_Long_CompactValue()"; for others fall back to a
   "PyLong_As*" function or "calling" "int.to_bytes()".

   The speedup is expected to be negligible for most users.

   Exactly what values are considered compact is an implementation
   detail and is subject to change.

   Added in version 3.12.

Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)

   *これは Unstable APIです。マイナーリリースで予告なく変更されること
   があります。*

   If *op* is compact, as determined by "PyUnstable_Long_IsCompact()",
   return its value.

   Otherwise, the return value is undefined.

   Added in version 3.12.
