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

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

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

type PyLongObject¶: 次に属します: Stable ABI (不透明な構造体として).
この 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 は -5 から 1024 までのすべての整数について、整数オブジェクトの配列を保持しています。この範囲の int を作成すると、実際には既存のオブジェクトへの参照が返されます。

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_FromInt32(int32_t value)¶
PyObject *PyLong_FromInt64(int64_t value)¶: 次に属します: Stable ABI (バージョン 3.14 より).
符号付きの C の int32_t または int64_t から、新しい PyLongObject オブジェクトを作成して返します。失敗すると例外を設定して NULL を返します。

Added in version 3.14.

PyObject *PyLong_FromUInt32(uint32_t value)¶
PyObject *PyLong_FromUInt64(uint64_t value)¶: 次に属します: Stable ABI (バージョン 3.14 より).
符号なしの C の uint32_t または uint64_t から、新しい PyLongObject オブジェクトを作成して返します。失敗すると例外を設定して NULL を返します。

Added in version 3.14.

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

参考

PyLong_AsNativeBytes() と PyLong_FromNativeBytes() を使うと、PyLongObject と基数 256 のバイト配列を相互に変換できます。

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

次に属します: Stable ABI (バージョン 3.14 より).

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

次に属します: Stable ABI (バージョン 3.14 より).

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

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

Added in version 3.13.

PyLong_FromPid(pid)¶

プロセス識別子から Python の整数を作成するマクロです。

システムの PID 型のサイズに応じて、PyLong_FromLong() または PyLong_FromLongLong() の別名として定義されることがあります。

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)¶: 推奨される PyLong_AsLong と完全に等価です。特に、OverflowError や他の例外で失敗する場合があります。

バージョン 3.14 でソフト非推奨 <Soft deprecated>.

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__() を使わなくなりました。

int PyLong_AsInt32(PyObject *obj, int32_t *value)¶

int PyLong_AsInt64(PyObject *obj, int64_t *value)¶

次に属します: Stable ABI (バージョン 3.14 より).

*value に、obj を表す符号付きの C の int32_t または int64_t の値を設定します。

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

obj の値が範囲外の場合は OverflowError を送出します。

成功すると *value を設定して 0 を返します。エラー時には例外を設定して -1 を返します。

value は NULL であってはなりません。

Added in version 3.14.

int PyLong_AsUInt32(PyObject *obj, uint32_t *value)¶

int PyLong_AsUInt64(PyObject *obj, uint64_t *value)¶

次に属します: Stable ABI (バージョン 3.14 より).

*value に、obj を表す符号なしの C の uint32_t または uint64_t の値を設定します。

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

obj が負の場合は ValueError を送出します。
obj の値が範囲外の場合は OverflowError を送出します。

成功すると *value を設定して 0 を返します。エラー時には例外を設定して -1 を返します。

value は NULL であってはなりません。

Added in version 3.14.

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

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

次に属します: Stable ABI (バージョン 3.14 より).

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

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

それ以外の場合は、値を格納するのに必要なバイト数を返します。その値が n_bytes 以下であれば、値全体がコピーされています。バッファの n_bytes バイトすべてに書き込み、余ったバイトは符号ビットを繰り返して埋めます。

戻り値が n_bytes より大きい場合は、値が切り詰められています。収まるだけの下位ビットを書き込み、上位ビットは無視します。これは C 形式のダウンキャストの典型的な動作と同じです。

注釈

オーバーフローはエラーとはみなしません。戻り値が 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¶ 次に属します: Stable ABI (バージョン 3.14 より).	`-1`
Py_ASNATIVEBYTES_BIG_ENDIAN¶ 次に属します: Stable ABI (バージョン 3.14 より).	`0`
Py_ASNATIVEBYTES_LITTLE_ENDIAN¶ 次に属します: Stable ABI (バージョン 3.14 より).	`1`
Py_ASNATIVEBYTES_NATIVE_ENDIAN¶ 次に属します: Stable ABI (バージョン 3.14 より).	`3`
Py_ASNATIVEBYTES_UNSIGNED_BUFFER¶ 次に属します: Stable ABI (バージョン 3.14 より).	`4`
Py_ASNATIVEBYTES_REJECT_NEGATIVE¶ 次に属します: Stable ABI (バージョン 3.14 より).	`8`
Py_ASNATIVEBYTES_ALLOW_INDEX¶ 次に属します: Stable ABI (バージョン 3.14 より).	`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.

PyLong_AsPid(pid)¶

Python の整数をプロセス識別子に変換するマクロです。

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.

int PyLong_GetSign(PyObject *obj, int *sign)¶

整数オブジェクト obj の符号を取得します。

成功すると *sign に整数の符号 (ゼロ、負、正の整数に対してそれぞれ 0、-1、+1) を設定し、0 を返します。

失敗すると例外を設定して -1 を返します。 obj が PyLongObject またはそのサブタイプであれば、この関数は常に成功します。

Added in version 3.14.

int PyLong_IsPositive(PyObject *obj)¶

整数オブジェクト obj が正かどうか (obj > 0) を調べます。

obj が PyLongObject またはそのサブタイプのインスタンスである場合、正なら 1、それ以外なら 0 を返します。それらのインスタンスでない場合は例外を設定して -1 を返します。

Added in version 3.14.

int PyLong_IsNegative(PyObject *obj)¶

整数オブジェクト obj が負かどうか (obj < 0) を調べます。

obj が PyLongObject またはそのサブタイプのインスタンスである場合、負なら 1、それ以外なら 0 を返します。それらのインスタンスでない場合は例外を設定して -1 を返します。

Added in version 3.14.

int PyLong_IsZero(PyObject *obj)¶

整数オブジェクト obj がゼロかどうかを調べます。

obj が PyLongObject またはそのサブタイプのインスタンスである場合、ゼロなら 1、それ以外なら 0 を返します。それらのインスタンスでない場合は例外を設定して -1 を返します。

Added in version 3.14.

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.

ビルド設定¶

PYLONG_BITS_IN_DIGIT¶

CPython の整数のネイティブ表現で、各桁に使うビット数です。現在の値は 30 (デフォルト) または 15 で、Python のビルド時に --enable-big-digits で選択します。

整数のネイティブ表現にアクセスするには、代わりに PyLong_GetNativeLayout() と、その bits_per_digit メンバーを使ってください。

エクスポート API¶

Added in version 3.14.

type PyLongLayout¶

次に属します: Stable ABI (すべてのメンバーを含む) (バージョン 3.15 より).

任意精度の整数の絶対値を表す「桁」(GMP の用語では「limb」) の配列のレイアウトです。

PyLong_GetNativeLayout() を使うと、Python の int オブジェクトのネイティブなレイアウトを取得できます。これは、絶対値が「十分に大きい」整数に内部で使われるレイアウトです。

Python で同様の情報を提供する sys.int_info も参照してください。

uint8_t bits_per_digit¶: 1 桁あたりのビット数です。例えば 15 ビットの桁では、ビット 0–14 が意味のある情報を持ちます。

uint8_t digit_size¶: バイト単位の桁のサイズです。例えば 15 ビットの桁には少なくとも 2 バイトが必要です。

int8_t digits_order¶

桁の順序:

最上位の桁が先なら 1
最下位の桁が先なら -1

int8_t digit_endianness¶

桁のエンディアン:

最上位バイトが先 (ビッグエンディアン) なら 1
最下位バイトが先 (リトルエンディアン) なら -1

const PyLongLayout *PyLong_GetNativeLayout(void)¶

次に属します: Stable ABI (バージョン 3.15 より).

Python の int オブジェクトのネイティブなレイアウトを取得します。

PyLongLayout 構造体を参照してください。

Python の初期化前や終了処理後にこの関数を呼び出してはいけません。返されたレイアウトは Python の終了処理まで有効です。レイアウトはプロセス内のすべての Python サブインタープリタで同じなので、キャッシュできます。

type PyLongExport¶

次に属します: Stable ABI (すべてのメンバーを含む) (バージョン 3.15 より).

Python の int オブジェクトのエクスポートです。

次の 2 つの場合があります:

digits が NULL の場合は、value メンバーだけを使ってください。
digits が NULL でない場合は、negative、ndigits、digits メンバーを使ってください。

int64_t value¶: エクスポートした int オブジェクトのネイティブな整数値です。 digits が NULL の場合だけ有効です。

uint8_t negative¶: 負の数なら 1、それ以外なら 0 です。 digits が NULL でない場合だけ有効です。

Py_ssize_t ndigits¶: digits 配列の桁数です。 digits が NULL でない場合だけ有効です。

const void *digits¶: 符号なしの桁を格納する読み出し専用の配列です。 NULL の場合もあります。

int PyLong_Export(PyObject *obj, PyLongExport *export_long)¶

次に属します: Stable ABI (バージョン 3.15 より).

Python の int オブジェクトをエクスポートします。

export_long は、呼び出し側が割り当てた PyLongExport 構造体を指す必要があります。 NULL であってはなりません。

成功すると *export_long を埋め、0 を返します。エラー時には例外を設定して -1 を返します。

エクスポートが不要になったら PyLong_FreeExport() を呼び出す必要があります。

obj が Python の int オブジェクトまたはそのサブクラスであれば、この関数は常に成功します。

void PyLong_FreeExport(PyLongExport *export_long)¶: 次に属します: Stable ABI (バージョン 3.15 より).
PyLong_Export() が作成したエクスポート export_long を解放します。

export_long->digits が NULL の場合、PyLong_FreeExport() の呼び出しは省略できます。

PyLongWriter API¶

PyLongWriter API を使って整数をインポートできます。

Added in version 3.14.

type PyLongWriter¶

次に属します: Stable ABI (不透明な構造体として) (バージョン 3.15 より).

Python の int ライターのインスタンスです。

インスタンスは PyLongWriter_Finish() または PyLongWriter_Discard() で破棄する必要があります。

PyLongWriter *PyLongWriter_Create(int negative, Py_ssize_t ndigits, void **digits)¶

次に属します: Stable ABI (バージョン 3.15 より).

PyLongWriter を作成します。

成功すると *digits を割り当て、ライターを返します。エラー時には例外を設定して NULL を返します。

negative は、負の数なら 1、それ以外なら 0 とします。

ndigits は digits 配列の桁数です。 0 より大きくなければなりません。

digits は NULL であってはなりません。

この関数の呼び出しが成功したら、呼び出し側は桁の配列 digits を埋め、PyLongWriter_Finish() を呼び出して Python の int を取得する必要があります。 digits のレイアウトは PyLong_GetNativeLayout() で記述されます。

各桁の値は [0; (1 << bits_per_digit) - 1] の範囲内でなければなりません (bits_per_digit は 1 桁あたりのビット数です)。使わない上位の桁はすべて 0 に設定する必要があります。

または、PyLongWriter_Discard() を呼び出して、int オブジェクトを作成せずにライターのインスタンスを破棄します。

PyObject *PyLongWriter_Finish(PyLongWriter *writer)¶

戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.15 より).

PyLongWriter_Create() で作成した PyLongWriter の処理を完了します。

成功すると Python の int オブジェクトを返します。エラー時には例外を設定して NULL を返します。

この関数は桁の正規化を行い、必要に応じてオブジェクトをコンパクトな整数に変換します。

呼び出し後は、ライターのインスタンスと digits 配列は無効になります。

void PyLongWriter_Discard(PyLongWriter *writer)¶

次に属します: Stable ABI (バージョン 3.15 より).

PyLongWriter_Create() で作成した PyLongWriter を破棄します。

writer が NULL の場合は何もしません。

呼び出し後は、ライターのインスタンスと digits 配列は無効になります。

非推奨の API¶

これらのマクロはソフト非推奨です。 PyLongObject インスタンスの内部表現のパラメーターを記述します。

代わりに PyLong_GetNativeLayout() と、整数データを読み取るための PyLong_Export()、または書き込むための PyLongWriter を使ってください。これらは現在は同じレイアウトを使っていますが、CPython の整数の内部表現が変わっても正しく動作し続けるように設計されています。

PyLong_SHIFT¶: PyLong_GetNativeLayout() の出力の bits_per_digit と等価です。

PyLong_BASE¶: 現在は 1 << PyLong_SHIFT と等価です。

PyLong_MASK¶: 現在は (1 << PyLong_SHIFT) - 1 と等価です。

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

ビルド設定¶

エクスポート API¶

PyLongWriter API¶

非推奨の API¶

目次

前のトピックへ

次のトピックへ

このページ