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