数字协议¶
-
int PyNumber_Check(PyObject *o)¶
- 是 稳定 ABI 的一部分。
如果对象 o 提供数字协议,则返回
1
,否则返回 false。此函数始终成功。在版本 3.8 中更改: 如果 o 是索引整数,则返回
1
。
-
PyObject *PyNumber_Add(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
返回 o1 和 o2 相加的结果,或在失败时返回
NULL
。这等效于 Python 表达式o1 + o2
。
-
PyObject *PyNumber_Subtract(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
返回从 o1 中减去 o2 的结果,或在失败时返回
NULL
。这等效于 Python 表达式o1 - o2
。
-
PyObject *PyNumber_Multiply(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
返回o1和o2相乘的结果,如果失败则返回
NULL
。这等效于 Python 表达式o1 * o2
。
-
PyObject *PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2)¶
- 返回值:新引用。自版本 3.7 起,是 稳定 ABI 的一部分。
返回o1和o2矩阵乘法的结果,如果失败则返回
NULL
。这等效于 Python 表达式o1 @ o2
。在版本 3.5 中添加。
-
PyObject *PyNumber_FloorDivide(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
返回o1除以o2的向下取整,如果失败则返回
NULL
。这等效于 Python 表达式o1 // o2
。
-
PyObject *PyNumber_TrueDivide(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
返回o1除以o2的数学值的合理近似值,如果失败则返回
NULL
。返回值是“近似值”,因为二进制浮点数是近似值;不可能用二进制表示所有实数。当传递两个整数时,此函数可以返回浮点值。这等效于 Python 表达式o1 / o2
。
-
PyObject *PyNumber_Remainder(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
返回o1除以o2的余数,如果失败则返回
NULL
。这等效于 Python 表达式o1 % o2
。
-
PyObject *PyNumber_Divmod(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
参见内置函数
divmod()
。失败时返回NULL
。这等效于 Python 表达式divmod(o1, o2)
。
-
PyObject *PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
参见内置函数
pow()
。失败时返回NULL
。这等效于 Python 表达式pow(o1, o2, o3)
,其中 o3 是可选的。如果要忽略 o3,请在其位置传递Py_None
(为 o3 传递NULL
将导致非法内存访问)。
-
PyObject *PyNumber_Negative(PyObject *o)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
成功时返回 o 的负值,失败时返回
NULL
。这等效于 Python 表达式-o
。
-
PyObject *PyNumber_Positive(PyObject *o)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
成功时返回 o,失败时返回
NULL
。这等效于 Python 表达式+o
。
-
PyObject *PyNumber_Absolute(PyObject *o)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
返回 o 的绝对值,失败时返回
NULL
。这等效于 Python 表达式abs(o)
。
-
PyObject *PyNumber_Invert(PyObject *o)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
成功时返回 o 的按位取反,失败时返回
NULL
。这等效于 Python 表达式~o
。
-
PyObject *PyNumber_Lshift(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
成功时返回将 *o1* 左移 *o2* 位的结果,失败时返回
NULL
。这等效于 Python 表达式o1 << o2
。
-
PyObject *PyNumber_Rshift(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
成功时返回将 *o1* 右移 *o2* 位的结果,失败时返回
NULL
。这等效于 Python 表达式o1 >> o2
。
-
PyObject *PyNumber_And(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
成功时返回 *o1* 和 *o2* 的“按位与”,失败时返回
NULL
。这等效于 Python 表达式o1 & o2
。
-
PyObject *PyNumber_Xor(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
成功时返回 *o1* 和 *o2* 的“按位异或”,失败时返回
NULL
。这等效于 Python 表达式o1 ^ o2
。
-
PyObject *PyNumber_Or(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
成功时返回o1和o2的“按位或”,失败时返回
NULL
。这等效于 Python 表达式o1 | o2
。
-
PyObject *PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
返回o1和o2相加的结果,失败时返回
NULL
。当o1支持时,操作将就地执行。这等效于 Python 语句o1 += o2
。
-
PyObject *PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
返回从o1中减去o2的结果,失败时返回
NULL
。当o1支持时,操作将就地执行。这等效于 Python 语句o1 -= o2
。
-
PyObject *PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
返回o1和o2相乘的结果,失败时返回
NULL
。当o1支持时,操作将就地执行。这等效于 Python 语句o1 *= o2
。
-
PyObject *PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)¶
- 返回值:新引用。自版本 3.7 起,是 稳定 ABI 的一部分。
返回o1和o2的矩阵乘法结果,失败时返回
NULL
。当o1支持时,操作将就地执行。这等效于 Python 语句o1 @= o2
。在版本 3.5 中添加。
-
PyObject *PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
返回o1除以o2的数学地板值,失败时返回
NULL
。当o1支持时,操作将就地执行。这等效于 Python 语句o1 //= o2
。
-
PyObject *PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
返回o1除以o2的数学值的合理近似值,或在失败时返回
NULL
。返回值是“近似值”,因为二进制浮点数是近似值;无法用二进制表示所有实数。当传递两个整数时,此函数可以返回浮点值。当o1支持时,操作是在就地完成的。这相当于 Python 语句o1 /= o2
。
-
PyObject *PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
返回o1除以o2的余数,或在失败时返回
NULL
。当o1支持时,操作是在就地完成的。这相当于 Python 语句o1 %= o2
。
-
PyObject *PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
参见内置函数
pow()
。在失败时返回NULL
。当o1支持时,操作是在就地完成的。这相当于 Python 语句o1 **= o2
,当 o3 为Py_None
时,或者当 o3 不为Py_None
时,是pow(o1, o2, o3)
的就地变体。如果要忽略o3,请在其位置传递Py_None
(为o3传递NULL
会导致非法内存访问)。
-
PyObject *PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
在成功时返回o1左移o2的结果,或在失败时返回
NULL
。当o1支持时,操作是在就地完成的。这相当于 Python 语句o1 <<= o2
。
-
PyObject *PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
成功时返回将 *o1* 右移 *o2* 的结果,失败时返回
NULL
。当 *o1* 支持时,该操作将 *就地* 完成。这等效于 Python 语句o1 >>= o2
。
-
PyObject *PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
成功时返回 *o1* 和 *o2* 的“按位与”,失败时返回
NULL
。当 *o1* 支持时,该操作将 *就地* 完成。这等效于 Python 语句o1 &= o2
。
-
PyObject *PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
成功时返回 *o1* 和 *o2* 的“按位异或”,失败时返回
NULL
。当 *o1* 支持时,该操作将 *就地* 完成。这等效于 Python 语句o1 ^= o2
。
-
PyObject *PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
成功时返回 *o1* 和 *o2* 的“按位或”,失败时返回
NULL
。当 *o1* 支持时,该操作将 *就地* 完成。这等效于 Python 语句o1 |= o2
。
-
PyObject *PyNumber_Long(PyObject *o)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
成功时返回转换为整数对象的 *o*,失败时返回
NULL
。这等效于 Python 表达式int(o)
。
-
PyObject *PyNumber_Float(PyObject *o)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
如果成功,则返回转换为浮点数对象的 o,如果失败,则返回
NULL
。这等效于 Python 表达式float(o)
。
-
PyObject *PyNumber_Index(PyObject *o)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
如果成功,则返回转换为 Python 整数的 o,如果失败,则返回
NULL
,并引发TypeError
异常。在版本 3.10 中更改: 结果始终具有确切类型
int
。以前,结果可能是int
的子类的实例。
-
PyObject *PyNumber_ToBase(PyObject *n, int base)¶
- 返回值: 新引用。 是 稳定 ABI 的一部分。
返回将整数 n 转换为以 base 为底的字符串。base 参数必须是 2、8、10 或 16 之一。对于以 2、8 或 16 为底,返回的字符串以
'0b'
、'0o'
或'0x'
为前缀,分别表示底数标记。如果 n 不是 Python 整数,则首先使用PyNumber_Index()
将其转换为 Python 整数。
-
Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)¶
- 是 稳定 ABI 的一部分。
如果 o 可以解释为整数,则返回转换为
Py_ssize_t
值的 o。如果调用失败,则会引发异常并返回-1
。如果 o 可以转换为 Python 整数,但尝试转换为
Py_ssize_t
值会引发OverflowError
,则 exc 参数是将引发的异常类型(通常是IndexError
或OverflowError
)。如果 exc 为NULL
,则异常将被清除,并且值将被剪裁为负整数的PY_SSIZE_T_MIN
或正整数的PY_SSIZE_T_MAX
。