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

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

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

type PyLongObject
    * Part of the Limited API (as an opaque struct).*

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

PyTypeObject PyLong_Type
    * Part of the 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)
    *Return value: New reference.** Part of the Stable ABI.*

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

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

PyObject *PyLong_FromUnsignedLong(unsigned long v)
    *Return value: New reference.** Part of the Stable ABI.*

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

PyObject *PyLong_FromSsize_t(Py_ssize_t v)
    *Return value: New reference.** Part of the Stable ABI.*

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

PyObject *PyLong_FromSize_t(size_t v)
    *Return value: New reference.** Part of the Stable ABI.*

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

PyObject *PyLong_FromLongLong(long long v)
    *Return value: New reference.** Part of the Stable ABI.*

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

PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)
    *Return value: New reference.** Part of the Stable ABI.*

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

PyObject *PyLong_FromDouble(double v)
    *Return value: New reference.** Part of the Stable ABI.*

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

PyObject *PyLong_FromString(const char *str, char **pend, int base)
    *Return value: New reference.** Part of the Stable ABI.*

   *str* の文字列値に基づいて、新たな "PyLongObject" を返します。 この
   とき *base* を基数として文字列を解釈します。 *pend* が "NULL" でな
   い場合は、 **pend* は *str* 中で数が表現されている部分以降の先頭文
   字のアドレスを指しています。 *base* が "0" の場合は、 *str* は 整数
   リテラル の定義を使って解釈されます; この場合では、先頭に 0 がある
   0 でない十進数は "ValueError" を送出します。 *base* が "0" でなけれ
   ば、 *base* は "2" 以上 "36" 以下の数でなければなりません。 先頭の
   空白、基数の指定の後や数字の間にある単一のアンダースコアは無視され
   ます。 数字が全くない場合、 "ValueError" が送出されます。

   参考:

     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)
    *Return value: New reference.*

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

   バージョン 3.3 で追加.

PyObject *PyLong_FromVoidPtr(void *p)
    *Return value: New reference.** Part of the Stable ABI.*

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

long PyLong_AsLong(PyObject *obj)
    * Part of the Stable ABI.*

   *obj* が表す、Cの "long" 表現を返します。もし *obj* が
   "PyLongObject" のインスタンスでなければ、まず、その "__index__()"
   メソッドを (もしあれば) 呼び出して、オブジェクトを "PyLongObject"
   に変換します。

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

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

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

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

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
    * Part of the Stable ABI.*

   *obj* が表す、Cの "long" 表現を返します。もし *obj* が
   "PyLongObject" のインスタンスでなければ、まず、その "__index__()"
   メソッドを (もしあれば) 呼び出して、オブジェクトを "PyLongObject"
   に変換します。

   もし、 *obj* の値が "LONG_MAX" より大きいか、 "LONG_MIN" より小さけ
   れば、 **overflow* は、それぞれ "1" か "-1" に設定され、 "-1" を返
   します; さもなければ  **overflow* は "0" に設定されます。もし、ほか
   の例外が発生した場合は **overflow* が "0" に設定され "-1" を返しま
   す。

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

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

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

long long PyLong_AsLongLong(PyObject *obj)
    * Part of the Stable ABI.*

   *obj* が表す、Cの "long long" 表現を返します。もし *obj* が
   "PyLongObject" のインスタンスでなければ、まず、その "__index__()"
   メソッドを (もしあれば) 呼び出して、オブジェクトを "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)
    * Part of the Stable ABI.*

   *obj* が表す、Cの "long long" 表現を返します。もし *obj* が
   "PyLongObject" のインスタンスでなければ、まず、その "__index__()"
   メソッドを (もしあれば) 呼び出して、オブジェクトを "PyLongObject"
   に変換します。

   もし、 *obj* の値が "LLONG_MAX" より大きいか、 "LLONG_MIN" より小さ
   ければ、 **overflow* は、それぞれ "1" か "-1" に設定され、 "-1" を
   返します; さもなければ  **overflow* は "0" に設定されます。もし、ほ
   かの例外が発生した場合は **overflow* が "0" に設定され "-1" を返し
   ます。

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

   バージョン 3.2 で追加.

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

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

Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
    * Part of the Stable ABI.*

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

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

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

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
    * Part of the Stable ABI.*

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

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

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

size_t PyLong_AsSize_t(PyObject *pylong)
    * Part of the Stable ABI.*

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

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

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

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)
    * Part of the 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)
    * Part of the Stable ABI.*

   *obj* が表す、C の "unsigned long" 表現を返します。もし *obj* が
   "PyLongObject" のインスタンスでなければ、まず、その "__index__()"
   メソッドを (もしあれば) 呼び出して、オブジェクトを "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)
    * Part of the Stable ABI.*

   *obj* が表す、C の "unsigned long long" 表現を返します。もし *obj*
   が "PyLongObject" のインスタンスでなければ、まず、その
   "__index__()" メソッドを (もしあれば) 呼び出して、オブジェクトを
   "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)
    * Part of the Stable ABI.*

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

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

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

void *PyLong_AsVoidPtr(PyObject *pylong)
    * Part of the Stable ABI.*

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

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