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

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

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

PyLongObject

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

PyTypeObject PyLong_Type

   この "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.*

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

   現在の実装では、"-5" から "256" までの全ての整数に対する整数オブジ
   ェクトの配列を保持するようにしており、この範囲の数を生成すると、実
   際には既存のオブジェクトに対する参照が返るようになっています。従っ
   て、"1" の値を変えることすら可能です。変えてしまった場合の Python
   の挙動は未定義です :-)

PyObject* PyLong_FromUnsignedLong(unsigned long v)
    *Return value: New reference.*

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

PyObject* PyLong_FromSsize_t(Py_ssize_t v)
    *Return value: New reference.*

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

PyObject* PyLong_FromSize_t(size_t v)
    *Return value: New reference.*

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

PyObject* PyLong_FromLongLong(long long v)
    *Return value: New reference.*

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

PyObject* PyLong_FromUnsignedLongLong(unsigned long long v)
    *Return value: New reference.*

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

PyObject* PyLong_FromDouble(double v)
    *Return value: New reference.*

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

PyObject* PyLong_FromString(const char *str, char **pend, int base)
    *Return value: New reference.*

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

PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
    *Return value: New reference.*

   Convert a sequence of Unicode digits to a Python integer value.

   Deprecated since version 3.3, will be removed in version 3.10: 古い
   スタイルの "Py_UNICODE" APIの一部です; "PyLong_FromUnicodeObject()"
   を使用するように移行してください。

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

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

long PyLong_AsLong(PyObject *obj)

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

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

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

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

   バージョン 3.8 で非推奨: "__int__()" の使用は非推奨です。

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)

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

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

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

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

   バージョン 3.8 で非推奨: "__int__()" の使用は非推奨です。

long long PyLong_AsLongLong(PyObject *obj)

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

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

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

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

   バージョン 3.8 で非推奨: "__int__()" の使用は非推奨です。

long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)

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

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

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

   バージョン 3.2 で追加.

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

   バージョン 3.8 で非推奨: "__int__()" の使用は非推奨です。

Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)

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

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

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

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)

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

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

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

size_t PyLong_AsSize_t(PyObject *pylong)

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

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

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

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)

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

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

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

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

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

   バージョン 3.8 で非推奨: "__int__()" の使用は非推奨です。

unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)

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

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

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

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

   バージョン 3.8 で非推奨: "__int__()" の使用は非推奨です。

double PyLong_AsDouble(PyObject *pylong)

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

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

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

void* PyLong_AsVoidPtr(PyObject *pylong)

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

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