# 整数型オブジェクト (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.

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

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

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

long PyLong_AsLong(PyObject *obj)
  Part of the 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_AsLongAndOverflow(PyObject *obj, int *overflow)
  Part of the 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)
  Part of the 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)
  Part of the 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)
  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.

  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)
  Part of the 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)
  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()` を使ってください。

int PyUnstable_Long_IsCompact(const PyLongObject *op)
  This is Unstable API. It may change without warning in minor releases.

  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.

Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)
  This is Unstable API. It may change without warning in minor releases.

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

  Otherwise, the return value is undefined.