# 数値型プロトコル (number protocol)

int PyNumber_Check(PyObject *o)
  Part of the Stable ABI.

  オブジェクト o が数値型プロトコルを提供している場合に `1` を返し、そうでないときには偽を返します。この関数呼び出しは常に成功します。

  バージョン 3.8 で変更: o がインデックス整数だった場合、 `1` を返します。

PyObject *PyNumber_Add(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 と o2 を加算した結果を返し、失敗すると `NULL` を返します。Python の式 `o1 + o2` と同じです。

PyObject *PyNumber_Subtract(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 から o2 を減算した結果を返し、失敗すると `NULL` を返します。Python の式 `o1 - o2` と同じです。

PyObject *PyNumber_Multiply(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 と o2 を乗算した結果を返し、失敗すると `NULL` を返します。Python の式 `o1 * o2` と同じです。

PyObject *PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI since version 3.7.

  成功すると o1 と o2 を行列乗算した結果を返し、失敗すると `NULL` を返します。 Python の式 `o1 @ o2` と同じです。

  Added in version 3.5.

PyObject *PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  Return the floor of o1 divided by o2, or `NULL` on failure. This is the equivalent of the Python expression `o1 // o2`.

PyObject *PyNumber_TrueDivide(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると、数学的な o1 の o2 による除算値に対する妥当な近似 (reasonable approximation) を返し、失敗すると `NULL` を返します。全ての実数を 2 を基数として表現するのは不可能なため、二進の浮動小数点数は "近似値" しか表現できません。このため、戻り値も近似になります。この関数に二つの整数を渡した際、浮動小数点の値を返すことがあります。Python の式 `o1 / o2` と同じです。

PyObject *PyNumber_Remainder(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 を o2 で除算した剰余を返し、失敗すると `NULL` を返します。Python の式 `o1 % o2` と同じです。

PyObject *PyNumber_Divmod(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  組み込み関数 `divmod()` を参照してください。失敗すると `NULL` を返します。 Python の式 `divmod(o1, o2)` と同じです。

PyObject *PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)
  Return value: New reference. Part of the Stable ABI.

  組み込み関数 `pow()` を参照してください。失敗すると `NULL` を返します。 Python の式 `pow(o1, o2, o3)` と同じです。 o3 はオプションです。 o3 を無視させたいなら、 `Py_None` を入れてください (o3 に `NULL` を渡すと、不正なメモリアクセスを引き起こすことがあります)。

PyObject *PyNumber_Negative(PyObject *o)
  Return value: New reference. Part of the Stable ABI.

  成功すると o の符号反転を返し、失敗すると `NULL` を返します。Python の式 `-o` と同じです。

PyObject *PyNumber_Positive(PyObject *o)
  Return value: New reference. Part of the Stable ABI.

  成功すると o を返し、失敗すると `NULL` を返します。Python の式 `+o` と同じです。

PyObject *PyNumber_Absolute(PyObject *o)
  Return value: New reference. Part of the Stable ABI.

  成功すると o の絶対値を返し、失敗すると `NULL` を返します。Python の式 `abs(o)` と同じです。

PyObject *PyNumber_Invert(PyObject *o)
  Return value: New reference. Part of the Stable ABI.

  成功すると o のビット単位反転 (bitwise negation) を返し、失敗すると `NULL` を返します。Python の式 `~o` と同じです。

PyObject *PyNumber_Lshift(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 を o2 だけ左シフトした結果を返し、失敗すると `NULL` を返します。Python の式 `o1 << o2` と同じです。

PyObject *PyNumber_Rshift(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 を o2 だけ右シフトした結果を返し、失敗すると `NULL` を返します。Python の式 `o1 >> o2` と同じです。

PyObject *PyNumber_And(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 と o2 の "ビット単位論理積 (bitwise and)" を返し、失敗すると `NULL` を返します。Python の式 `o1 & o2` と同じです。

PyObject *PyNumber_Xor(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 と o2 の "ビット単位排他的論理和 (bitwise exclusive or)" を返し、失敗すると `NULL` を返します。Python の式 `o1 ^ o2` と同じです。

PyObject *PyNumber_Or(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 と o2 の "ビット単位論理和 (bitwise or)" を返し失敗すると `NULL` を返します。Python の式 `o1 | o2` と同じです。

PyObject *PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 と o2 を加算した結果を返し、失敗すると `NULL` を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 `o1 += o2` と同じです。

PyObject *PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 から o2 を減算した結果を返し、失敗すると `NULL` を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 `o1 -= o2` と同じです。

PyObject *PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 と o2 を乗算した結果を返し、失敗すると `NULL` を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 `o1 *= o2` と同じです。

PyObject *PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI since version 3.7.

  成功すると o1 と o2 を行列乗算した結果を返し、失敗すると `NULL` を返します。 o1 が in-place 演算をサポートする場合、 in-place 演算を行います。 Python の文 `o1 @= o2` と同じです。

  Added in version 3.5.

PyObject *PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 を o2 で除算した切捨て値を返し、失敗すると `NULL` を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 `o1 //= o2` と同じです。

PyObject *PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると、数学的な o1 の o2 による除算値に対する妥当な近似 (reasonable approximation) を返し、失敗すると `NULL` を返します。全ての実数を 2 を基数として表現するのは不可能なため、二進の浮動小数点数は "近似値" しか表現できません。このため、戻り値も近似になります。この関数に二つの整数を渡した際、浮動小数点の値を返すことがあります。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 `o1 /= o2` と同じです。

PyObject *PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 を o2 で除算した剰余を返し、, 失敗すると `NULL` を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 `o1 %= o2` と同じです。

PyObject *PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)
  Return value: New reference. Part of the Stable ABI.

  組み込み関数 `pow()` を参照してください。失敗すると `NULL` を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。この関数は o3 が `Py_None` の場合は Python 文 `o1 **= o2` と同じで、それ以外の場合は `pow(o1, o2, o3)` の in-place 版です。 o3 を無視させたいなら、 `Py_None` を入れてください (o3 に `NULL` を渡すと、不正なメモリアクセスを引き起こすことがあります)。

PyObject *PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 を o2 だけ左シフトした結果を返し、失敗すると `NULL` を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 `o1 <<= o2` と同じです。

PyObject *PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 を o2 だけ右シフトした結果を返し、失敗すると `NULL` を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 `o1 >>= o2` と同じです。

PyObject *PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 と o2 の "ビット単位論理積 (bitwise and)" を返し、失敗すると `NULL` を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 `o1 &= o2` と同じです。

PyObject *PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 と o2 の "ビット単位排他的論理和 (bitwise exclusive or)" を返し、失敗すると `NULL` を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 `o1 ^= o2` と同じです。

PyObject *PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)
  Return value: New reference. Part of the Stable ABI.

  成功すると o1 と o2 の "ビット単位論理和 (bitwise or)" を返し失敗すると `NULL` を返します。o1 が in-place 演算をサポートする場合、in-place 演算を行います。Python の文 `o1 |= o2` と同じです。

PyObject *PyNumber_Long(PyObject *o)
  Return value: New reference. Part of the Stable ABI.

  成功すると o を整数に変換したものを返し、失敗すると `NULL` を返します。Python の式 `int(o)` と同じです。

PyObject *PyNumber_Float(PyObject *o)
  Return value: New reference. Part of the Stable ABI.

  成功すると o を浮動小数点数に変換したものを返し、失敗すると `NULL` を返します。Python の式 `float(o)` と同じです。

PyObject *PyNumber_Index(PyObject *o)
  Return value: New reference. Part of the Stable ABI.

  o をPythonのint型に変換し、成功したらその値を返します。失敗したら `NULL` が返され、 `TypeError` 例外が送出されます。

  バージョン 3.10 で変更: 結果は常に厳密な `int` 型です。 以前は、結果は `int` のサブクラスのインスタンスのこともありました。

PyObject *PyNumber_ToBase(PyObject *n, int base)
  Return value: New reference. Part of the Stable ABI.

  base 進数に変換された整数 n を文字列として返します。 base 引数は2, 8, 10または16のいずれかでなければなりません。 基数2、8、16について、返される文字列の先頭には基数マーカー `'0b'` 、 `'0o'` または `'0x'` が、それぞれ付与されます。 もし n が Python のint型でなければ、まず `PyNumber_Index()` で変換されます。

Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
  Part of the Stable ABI.

  o を整数として解釈可能だった場合、`Py_ssize_t` 型の値に変換して返します。呼び出しが失敗したら、例外が送出され、 `-1` が返されます。

  もし o がPythonのintに変換できたのに、`Py_ssize_t` への変換が `OverflowError` になる場合は、 exc 引数で渡された型 (普通は `IndexError` か `OverflowError`) の例外を送出します。もし、 exc が `NULL` なら、例外はクリアされて、値が負の場合は `PY_SSIZE_T_MIN` へ、正の場合は `PY_SSIZE_T_MAX` へと制限されます。

int PyIndex_Check(PyObject *o)
  Part of the Stable ABI since version 3.8.

  o がインデックス整数である場合 (`tp_as_number` 構造体の `nb_index` スロットが埋まっている場合) に `1` を返し、そうでない場合に `0` を返します。 この関数は常に成功します。