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

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

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

type PyLongObject¶: 次に属します: Limited API (不透明な構造体として).
この PyObject のサブタイプは Python の整数オブジェクトを表します。

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 を返します。

CPython 実装の詳細: CPython keeps an array of integer objects for all integers between -5 and 256. When you create an int in that range you actually just get back a reference to the existing object.

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.
str 内の文字列を base の基数で解釈し、新しい PyLongObject を作成して返します。失敗すると NULL を返します。 pend が NULL でなければ、成功時には *pend が str の末尾を、エラー時には処理できなかった最初の文字を指します。 base が 0 の場合、str は整数リテラルの定義に従って解釈します。この場合、ゼロでない 10 進数の先頭にゼロがあると ValueError を送出します。 base が 0 でない場合は、2 以上 36 以下でなければなりません。先頭と末尾の空白、および基数指定子の後や数字の間にある単独のアンダースコアは無視します。数字がない場合や、数字と末尾の空白の後で str が NULL 終端されていない場合は、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)¶: 戻り値: 新しい参照。
文字列 u 内の Unicode 数字の列を Python の整数値に変換します。

Added in version 3.3.

PyObject *PyLong_FromVoidPtr(void *p)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
ポインタ p から Python 整数値を生成します。ポインタの値は PyLong_AsVoidPtr() を適用した結果から取得されます。

PyObject *PyLong_FromNativeBytes(const void *buffer, size_t n_bytes, int flags)¶

buffer の先頭 n_bytes バイトに格納された値を、2 の補数表現の符号付き数値として解釈し、Python の整数を作成します。

flags は PyLong_AsNativeBytes() と同じです。 -1 を渡すと、CPython のコンパイル時のネイティブなエンディアンを選び、最上位ビットを符号ビットとみなします。 Py_ASNATIVEBYTES_UNSIGNED_BUFFER を渡すと、PyLong_FromUnsignedNativeBytes() の呼び出しと同じ結果になります。他のフラグは無視します。

Added in version 3.13.

PyObject *PyLong_FromUnsignedNativeBytes(const void *buffer, size_t n_bytes, int flags)¶

buffer の先頭 n_bytes バイトに格納された値を符号なし数値として解釈し、Python の整数を作成します。

flags は PyLong_AsNativeBytes() と同じです。 -1 を渡すと、CPython のコンパイル時のネイティブなエンディアンを選び、最上位ビットを符号ビットではないとみなします。エンディアン以外のフラグは無視します。

Added in version 3.13.

PyLong_FromPid(pid)¶

Macro for creating a Python integer from a process identifier.

This can be defined as an alias to PyLong_FromLong() or PyLong_FromLongLong(), depending on the size of the system's PID type.

Added in version 3.2.

long PyLong_AsLong(PyObject *obj)¶

次に属します: Stable ABI.

obj を表す C の long を返します。 obj が PyLongObject のインスタンスでない場合、まず __index__() メソッド (存在する場合) を呼び出して PyLongObject に変換します。

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

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

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

バージョン 3.10 で変更: この関数は __int__() を使わなくなりました。

long PyLong_AS_LONG(PyObject *obj)¶: Exactly equivalent to the preferred PyLong_AsLong. In particular, it can fail with OverflowError or another exception.

Soft deprecated since version 3.14.

int PyLong_AsInt(PyObject *obj)¶: 次に属します: Stable ABI (バージョン 3.13 より).
PyLong_AsLong() と同様ですが、結果を C の long ではなく int に格納します。

Added in version 3.13.

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)¶

次に属します: Stable ABI.

obj を表す C の long を返します。 obj が PyLongObject のインスタンスでない場合、まず __index__() メソッド (存在する場合) を呼び出して PyLongObject に変換します。

obj の値が LONG_MAX より大きい場合は *overflow に 1、LONG_MIN より小さい場合は -1 を設定し、-1 を返します。それ以外の場合は *overflow に 0 を設定します。他の例外が発生した場合は、*overflow に 0 を設定し、通常どおり -1 を返します。

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

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

バージョン 3.10 で変更: この関数は __int__() を使わなくなりました。

long long PyLong_AsLongLong(PyObject *obj)¶

次に属します: Stable ABI.

obj を表す C の long long を返します。 obj が PyLongObject のインスタンスでない場合、まず __index__() メソッド (存在する場合) を呼び出して PyLongObject に変換します。

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

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

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

バージョン 3.10 で変更: この関数は __int__() を使わなくなりました。

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

次に属します: Stable ABI.

obj を表す C の long long を返します。 obj が PyLongObject のインスタンスでない場合、まず __index__() メソッド (存在する場合) を呼び出して PyLongObject に変換します。

obj の値が LLONG_MAX より大きい場合は *overflow に 1、LLONG_MIN より小さい場合は -1 を設定し、-1 を返します。それ以外の場合は *overflow に 0 を設定します。他の例外が発生した場合は、*overflow に 0 を設定し、通常どおり -1 を返します。

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

Added in version 3.2.

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

バージョン 3.10 で変更: この関数は __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.

obj を表す C の unsigned long を返します。 obj が PyLongObject のインスタンスでない場合、まず __index__() メソッド (存在する場合) を呼び出して PyLongObject に変換します。

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

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

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

バージョン 3.10 で変更: この関数は __int__() を使わなくなりました。

unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)¶

次に属します: 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 で変更: この関数は __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 を送出します。利用可能な void ポインタが得られることを保証するのは、PyLong_FromVoidPtr() で作成した値に対してだけです。

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

PyLong_AsPid(pid)¶

Macro for converting a Python integer into a process identifier.

This can be defined as an alias to PyLong_AsLong(), PyLong_FromLongLong(), or PyLong_AsInt(), depending on the size of the system's PID type.

Added in version 3.2.

Py_ssize_t PyLong_AsNativeBytes(PyObject *pylong, void *buffer, Py_ssize_t n_bytes, int flags)¶

Python の整数値 pylong を、サイズ n_bytes のネイティブな buffer にコピーします。 flags に -1 を指定すると C のキャストと同様に動作し、後述する値を指定すると動作を制御できます。

エラー時には例外を送出して -1 を返します。 pylong を整数として解釈できない場合や、Py_ASNATIVEBYTES_REJECT_NEGATIVE フラグが設定されているときに pylong が負である場合に、エラーが発生する可能性があります。

Otherwise, returns the number of bytes required to store the value. If this is equal to or less than n_bytes, the entire value was copied. All n_bytes of the buffer are written: remaining bytes filled by copies of the sign bit.

If the returned value is greater than n_bytes, the value was truncated: as many of the lowest bits of the value as could fit are written, and the higher bits are ignored. This matches the typical behavior of a C-style downcast.

注釈

オーバーフローはエラーとはみなしません。戻り値が n_bytes より大きい場合、上位ビットは破棄されています。

0 を返すことはありません。

値は常に 2 の補数表現でコピーします。

使用例です。

int32_t value;
Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, &value, sizeof(value), -1);
if (bytes < 0) {
    // 失敗。理由を示す Python の例外が設定されています。
    return NULL;
}
else if (bytes <= (Py_ssize_t)sizeof(value)) {
    // 成功。
}
else {
    // オーバーフローしましたが、'value' には切り詰めた
    // pylong の下位ビットが格納されています。
}

n_bytes にゼロを渡すと、値を格納するのに十分なバッファサイズを返します。厳密に必要なサイズより大きい場合がありますが、不合理に大きくなることはありません。 n_bytes=0 の場合、buffer は NULL でも構いません。

注釈

この関数に n_bytes=0 を渡しても、値の正確なビット長は求められません。

サイズが不明な Python の値全体を取得するには、この関数を 2 回呼び出せます。最初にバッファサイズを調べ、次にバッファを埋めます。

// 必要な領域のサイズを調べます。
Py_ssize_t expected = PyLong_AsNativeBytes(pylong, NULL, 0, -1);
if (expected < 0) {
    // 失敗。理由を示す Python の例外が設定されています。
    return NULL;
}
assert(expected != 0);  // API の定義上、ゼロにはなりません。
uint8_t *bignum = malloc(expected);
if (!bignum) {
    PyErr_SetString(PyExc_MemoryError, "bignum malloc failed.");
    return NULL;
}
// 値全体を安全に取得します。
Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, bignum, expected, -1);
if (bytes < 0) {  // 例外が設定されています。
    free(bignum);
    return NULL;
}
else if (bytes > expected) {  // この状況は起きないはずです。
    PyErr_SetString(PyExc_RuntimeError,
        "Unexpected bignum truncation after a size check.");
    free(bignum);
    return NULL;
}
// 上の事前チェックから期待される成功です。
// ... bignum を使います ...
free(bignum);

flags には、C のキャストに最も近い動作をするデフォルトを選ぶ -1 (Py_ASNATIVEBYTES_DEFAULTS)、または以下の表にある他のフラグの組み合わせを指定します。 -1 は他のフラグと組み合わせられないことに注意してください。

現在、-1 は Py_ASNATIVEBYTES_NATIVE_ENDIAN | Py_ASNATIVEBYTES_UNSIGNED_BUFFER に相当します。

Flag	値
Py_ASNATIVEBYTES_DEFAULTS¶	`-1`
Py_ASNATIVEBYTES_BIG_ENDIAN¶	`0`
Py_ASNATIVEBYTES_LITTLE_ENDIAN¶	`1`
Py_ASNATIVEBYTES_NATIVE_ENDIAN¶	`3`
Py_ASNATIVEBYTES_UNSIGNED_BUFFER¶	`4`
Py_ASNATIVEBYTES_REJECT_NEGATIVE¶	`8`
Py_ASNATIVEBYTES_ALLOW_INDEX¶	`16`

Py_ASNATIVEBYTES_NATIVE_ENDIAN を指定すると、他のエンディアンのフラグより優先されます。値 2 は予約されています。

By default, sufficient buffer will be requested to include a sign bit. For example, when converting 128 with n_bytes=1, the function will return 2 (or more) in order to store a zero sign bit.

Py_ASNATIVEBYTES_UNSIGNED_BUFFER を指定すると、サイズの計算からゼロの符号ビットを除外します。これにより、例えば 128 を 1 バイトのバッファに収めることができます。コピー先のバッファを後で符号付きとして扱うと、正の入力値が負になる場合があります。このフラグは負の値の扱いには影響せず、負の値には常に符号ビットのための領域が要求されることに注意してください。

Py_ASNATIVEBYTES_REJECT_NEGATIVE を指定すると、pylong が負の場合に例外を設定します。このフラグを指定しない場合は、Py_ASNATIVEBYTES_UNSIGNED_BUFFER の指定の有無にかかわらず、少なくとも符号ビット 1 つ分の領域があれば負の値をコピーします。

Py_ASNATIVEBYTES_ALLOW_INDEX を指定して整数以外の値を渡すと、最初にその値の __index__() メソッドを呼び出します。その結果 Python コードが実行され、他のスレッドも実行できるようになる場合があり、使用中の他のオブジェクトや値が変化する可能性があります。 flags が -1 の場合、このオプションは設定されず、整数以外の値は TypeError を引き起こします。

注釈

デフォルトの flags (-1、または REJECT_NEGATIVE を指定しない UNSIGNED_BUFFER) では、複数の Python の整数が、オーバーフローせずに同じ 1 つの値に対応することがあります。例えば 255 と -1 はどちらも 1 バイトのバッファに収まり、すべてのビットを立てます。これは C のキャストの典型的な動作と同じです。

Added in version 3.13.

PyObject *PyLong_GetInfo(void)¶

次に属します: Stable ABI.

成功すると、Python の整数の内部表現に関する情報を格納した、読み出し専用の名前付きタプルを返します。各フィールドの説明は sys.int_info を参照してください。

失敗すると例外を設定して NULL を返します。

Added in version 3.1.

int PyUnstable_Long_IsCompact(const PyLongObject *op)¶

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

op がコンパクトであれば 1、それ以外なら 0 を返します。

この関数を使うと、性能が重要なコードで小さい整数向けの「高速な処理経路」を実装できます。コンパクトな値には PyUnstable_Long_CompactValue() を使い、それ以外の値には PyLong_As* 関数または PyLong_AsNativeBytes() にフォールバックしてください。

ほとんどの利用者にとって、速度の向上はごくわずかと考えられます。

どの値をコンパクトとみなすかは実装の詳細であり、変更される可能性があります。

Added in version 3.12.

Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)¶

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

PyUnstable_Long_IsCompact() で判定して op がコンパクトであれば、その値を返します。

それ以外の場合、戻り値は未定義です。

Added in version 3.12.

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

前のトピックへ

次のトピックへ

このページ