整数型オブジェクト (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" に相当します。

   These values are available when compiling for the Stable ABI since
   version 3.14.

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

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 と等価です。
