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

int `PyNumber_Check`( | PyObject *o)

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

PyObject* `PyNumber_Add`( | PyObject *o1, PyObject *o2)

  戻り値: 新たな参照.
  成功するとo1 と o2 を加算した結果を返し、 失敗すると `NULL` を返します。 Python の式 "`o1 + o2`" と同じです。

PyObject* `PyNumber_Subtract`( | PyObject *o1, PyObject *o2)

  戻り値: 新たな参照.
  成功するとo1 から o2 を減算した結果を返し、 失敗すると `NULL` を返します。 Python の式 "`o1 - o2`" と同じです。

PyObject* `PyNumber_Multiply`( | PyObject *o1, PyObject *o2)

  戻り値: 新たな参照.
  成功するとo1 と o2 を乗算した結果を返し、失敗すると `NULL` を返します。 Python の式 "`o1 * o2`" と同じです。

PyObject* `PyNumber_Divide`( | PyObject *o1, PyObject *o2)

  戻り値: 新たな参照.
  成功すると o1 を o2 で除算した結果を返し, 失敗すると `NULL` を返します。 Python の式 "`o1 / o2`" と同じです。

PyObject* `PyNumber_FloorDivide`( | PyObject *o1, PyObject *o2)

  戻り値: 新たな参照.
  成功するとo1 を o2 で除算した切捨て値を返し、 失敗すると `NULL` を返します。 ``旧仕様の'' 整数間での除算と同じです。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* `PyNumber_TrueDivide`( | PyObject *o1, PyObject *o2)

  戻り値: 新たな参照.
  成功すると、数学的な o1 の o2 による除算値に対する 妥当な近似 (reasonable approximation) を返し、 失敗すると `NULL` を返します。 全ての実数を 2 を基数として表現するのは不可能なため、二進の浮動小数点数は ``近似値'' しか表現できません。このため、戻り値も近似になります。 この関数に二つの整数を渡した際、浮動小数点の値を返すことがあります。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* `PyNumber_Remainder`( | PyObject *o1, PyObject *o2)

  戻り値: 新たな参照.
  成功すると o1 を o2 で除算した剰余を返し、 失敗すると `NULL` を返します。 Python の式 "`o1 % o2`" と同じです。

PyObject* `PyNumber_Divmod`( | PyObject *o1, PyObject *o2)

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

PyObject* `PyNumber_Power`( | PyObject *o1, PyObject *o2, PyObject *o3)

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

PyObject* `PyNumber_Negative`( | PyObject *o)

  戻り値: 新たな参照.
  成功するとo の符号反転を返し、失敗すると `NULL` を返します。 Python の式 "`-o`" と同じです。

PyObject* `PyNumber_Positive`( | PyObject *o)

  戻り値: 新たな参照.
  成功すると o を返し、失敗すると `NULL` を返します。 Python の式 "`+o`" と同じです。

PyObject* `PyNumber_Absolute`( | PyObject *o)

  戻り値: 新たな参照.
  成功すると o の絶対値を返し、失敗すると `NULL` を返します。 Python の式 "`abs(o)`" と同じです。

PyObject* `PyNumber_Invert`( | PyObject *o)

  戻り値: 新たな参照.
  成功すると o のビット単位反転 (bitwise negation) を返し、 失敗すると `NULL` を返します。Python の式 "`~o`" と同じです。

PyObject* `PyNumber_Lshift`( | PyObject *o1, PyObject *o2)

  戻り値: 新たな参照.
  成功すると o1 を o2 だけ左シフトした結果を返し、 失敗すると `NULL` を返します。 Python の式 "`o1 <`<` o2`" と同じです。

PyObject* `PyNumber_Rshift`( | PyObject *o1, PyObject *o2)

  戻り値: 新たな参照.
  成功すると o1 を o2 だけ右シフトした結果を返し、 失敗すると `NULL` を返します。 Python の式 "`o1 >`>` o2`" と同じです。

PyObject* `PyNumber_And`( | PyObject *o1, PyObject *o2)

  戻り値: 新たな参照.
  成功すると o1 と o2 の ``ビット単位論理積 (bitwise and)'' を返し、 失敗すると `NULL` を返します。 Python の式 "`o1 & o2`" と同じです。

PyObject* `PyNumber_Xor`( | PyObject *o1, PyObject *o2)

  戻り値: 新たな参照.
  成功すると o1 と o2 の ``ビット単位排他的論理和 (bitwise exclusive or)'' を返し、 失敗すると `NULL` を返します。 Python の式 "`o1 ^ o2`" と同じです。

PyObject* `PyNumber_Or`( | PyObject *o1, PyObject *o2)

  戻り値: 新たな参照.
  成功すると o1 と o2 の ``ビット単位論理和 (bitwise or)'' を返し 失敗すると `NULL` を返します。 Python の式 "`o1 | o2`" と同じです。

PyObject* `PyNumber_InPlaceAdd`( | PyObject *o1, PyObject *o2)

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

PyObject* `PyNumber_InPlaceSubtract`( | PyObject *o1, PyObject *o2)

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

PyObject* `PyNumber_InPlaceMultiply`( | PyObject *o1, PyObject *o2)

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

PyObject* `PyNumber_InPlaceDivide`( | PyObject *o1, PyObject *o2)

  戻り値: 新たな参照.
  成功すると o1 を o2 で除算した結果を返し, 失敗すると `NULL` を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 Python の文 "`o1 /= o2`" と同じです。

PyObject* `PyNumber_InPlaceFloorDivide`( | PyObject *o1, PyObject *o2)

  戻り値: 新たな参照.
  成功するとo1 を o2 で除算した切捨て値を返し、 失敗すると `NULL` を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 Python の文 "`o1 //= o2`" と同じです。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* `PyNumber_InPlaceTrueDivide`( | PyObject *o1, PyObject *o2)

  戻り値: 新たな参照.
  成功すると、数学的な o1 の o2 による除算値に対する 妥当な近似 (reasonable approximation) を返し、 失敗すると `NULL` を返します。 全ての実数を 2 を基数として表現するのは不可能なため、二進の浮動小数点数は ``近似値'' しか表現できません。このため、戻り値も近似になります。 この関数に二つの整数を渡した際、浮動小数点の値を返すことがあります。 o1 が in-place 演算をサポートする場合、in-place 演算を 行います。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* `PyNumber_InPlaceRemainder`( | PyObject *o1, PyObject *o2)

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

PyObject* `PyNumber_InPlacePower`( | PyObject *o1, PyObject *o2, PyObject *o3)

  戻り値: 新たな参照.
  組み込み関数`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)

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

PyObject* `PyNumber_InPlaceRshift`( | PyObject *o1, PyObject *o2)

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

PyObject* `PyNumber_InPlaceAnd`( | PyObject *o1, PyObject *o2)

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

PyObject* `PyNumber_InPlaceXor`( | PyObject *o1, PyObject *o2)

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

PyObject* `PyNumber_InPlaceOr`( | PyObject *o1, PyObject *o2)

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

int `PyNumber_Coerce`( | PyObject **p1, PyObject **p2)

  この関数は`PyObject*` 型の二つの変数のアドレスを引数にとります。 `*p1` と`*p2` が指すオブジェクトが同じ型の場合、 それぞれの参照カウントをインクリメントして `0` (成功) を返します。 オブジェクトを変換して共通の数値型にできる場合、 `*p1` と `*p2` を変換後の値に置き換えて (参照カウントを '新しく' して) 、`0` を返します。 変換が不可能な場合や、その他何らかのエラーが生じた場合、`-1` (失敗) を返し、参照カウントをインクリメントしません。 `PyNumber_Coerce(&o1, &o2)` の呼び出しは Python 文 "`o1, o2 = coerce(o1, o2)`" と同じです。

PyObject* `PyNumber_Int`( | PyObject *o)

  戻り値: 新たな参照.
  成功するとo を整数に変換したものを返し、 失敗すると `NULL` を返します。 引数の値が整数の範囲外の場合、長整数を代わりに返します。 Python の式 "`int(o)`" と同じです。

PyObject* `PyNumber_Long`( | PyObject *o)

  戻り値: 新たな参照.
  成功するとo を長整数に変換したものを返し、 失敗すると `NULL` を返します。 Python の式 "`long(o)`" と同じです。

PyObject* `PyNumber_Float`( | PyObject *o)

  戻り値: 新たな参照.
  成功するとo を浮動小数点数に変換したものを返し、 失敗すると `NULL` を返します。 Python の式 "`float(o)`" と同じです。