پروتکل عدد¶

int PyNumber_Check(PyObject *o)¶

قسمتی از ABI پایدار.

اگر شیء o پروتکل‌های عددی را فراهم کند، 1 بازمی‌گرداند و در غیر این صورت نادرست. این تابع همیشه موفق می‌شود.

تغییر یافته در نسخه‌ی 3.8: اگر o یک عدد صحیح اندیس باشد، 1 برمی‌گرداند.

PyObject *PyNumber_Add(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

نتیجه‌ی جمع o1 و o2 را برمی‌گرداند، یا در صورت شکست NULL برمی‌گرداند. این معادل عبارت پایتونی o1 + o2 است.

PyObject *PyNumber_Subtract(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

نتیجه‌ی تفریق o2 از o1 را برمی‌گرداند، یا در صورت شکست NULL. این معادل عبارت پایتونی o1 - o2 است.

PyObject *PyNumber_Multiply(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

نتیجه‌ی ضرب o1 و o2 را برمی‌گرداند، یا در صورت شکست NULL. این معادل عبارت پایتونی o1 * o2 است.

PyObject *PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.7.

نتیجه‌ی ضرب ماتریسی روی o1 و o2 را برمی‌گرداند، یا در صورت شکست NULL. این معادل عبارت پایتونی o1 @ o2 است.

اضافه شده در نسخه‌ی 3.5.

PyObject *PyNumber_FloorDivide(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

کف تقسیم o1 بر o2 را برمی‌گرداند، یا در صورت شکست NULL. این معادل عبارت پایتونی o1 // o2 است.

PyObject *PyNumber_TrueDivide(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

تقریبی معقول از مقدار ریاضی o1 تقسیم‌شده بر o2 را برمی‌گرداند، یا در صورت شکست NULL را برمی‌گرداند. مقدار بازگشتی «تقریبی» است، زیرا اعداد ممیز شناور دودویی تقریبی‌اند؛ نمی‌توان همه‌ی اعداد حقیقی را در مبنای دو نمایش داد. این تابع می‌تواند هنگام دریافت دو عدد صحیح، یک مقدار ممیز شناور برگرداند. این معادل عبارت پایتونی o1 / o2 است.

PyObject *PyNumber_Remainder(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

باقیمانده‌ی تقسیم o1 بر o2 را برمی‌گرداند، یا در صورت شکست NULL. این معادل عبارت پایتونی o1 % o2 است.

PyObject *PyNumber_Divmod(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

تابع توکار divmod() را ببینید. در صورت شکست NULL را برمی‌گرداند. این معادل عبارت پایتونی divmod(o1, o2) است.

PyObject *PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

به تابع توکار pow() مراجعه کنید. در صورت شکست، NULL برمی‌گرداند. این معادل عبارت پایتونی pow(o1, o2, o3) است که در آن o3 اختیاری است. اگر قرار است o3 نادیده گرفته شود، به جای آن Py_None را ارسال کنید (ارسال NULL برای o3 باعث دسترسی غیرمجاز به حافظه می‌شود).

PyObject *PyNumber_Negative(PyObject *o)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

نفی o را در صورت موفقیت، یا NULL را در صورت شکست برمی‌گرداند. این معادل عبارت پایتونی -o است.

PyObject *PyNumber_Positive(PyObject *o)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

در صورت موفقیت o و در صورت شکست NULL را برمی‌گرداند. این معادل عبارت پایتونی +o است.

PyObject *PyNumber_Absolute(PyObject *o)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

قدر مطلق o را برمی‌گرداند، یا در صورت شکست NULL. این معادل عبارت پایتونی abs(o) است.

PyObject *PyNumber_Invert(PyObject *o)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

نقیض بیتی o را در صورت موفقیت و NULL را در صورت شکست برمی‌گرداند. این معادل عبارت پایتونی ~o است.

PyObject *PyNumber_Lshift(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

در صورت موفقیت، نتیجه‌ی شیفت به چپ o1 به اندازه‌ی o2 را برمی‌گرداند، یا در صورت شکست NULL را برمی‌گرداند. این معادل عبارت پایتونی o1 << o2 است.

PyObject *PyNumber_Rshift(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

در صورت موفقیت، نتیجه‌ی شیفت به راست o1 به اندازه‌ی o2 را برمی‌گرداند و در صورت شکست NULL. این معادل عبارت پایتون o1 >> o2 است.

PyObject *PyNumber_And(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

در صورت موفقیت، «وِ بیتی» o1 و o2 را و در صورت شکست NULL را برمی‌گرداند. این معادل عبارت o1 & o2 در پایتون است.

PyObject *PyNumber_Xor(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

در صورت موفقیت، «یای انحصاری بیتی» o1 با o2 را برمی‌گرداند و در صورت شکست NULL را برمی‌گرداند. این معادل عبارت پایتونی o1 ^ o2 است.

PyObject *PyNumber_Or(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

در صورت موفقیت، «یای بیتی» o1 و o2 را برمی‌گرداند و در صورت شکست NULL. این معادل عبارت پایتونی o1 | o2 است.

PyObject *PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

حاصل جمع o1 و o2 را برمی‌گرداند، یا در صورت شکست NULL. عملیات زمانی به‌صورت درجا (in-place) انجام می‌شود که o1 آن را پشتیبانی کند. این معادل دستور پایتونی o1 += o2 است.

PyObject *PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

نتیجه‌ی تفریق o2 از o1 را برمی‌گرداند، یا در صورت شکست NULL. این عملیات هنگامی که o1 از آن پشتیبانی کند، به‌صورت درجا انجام می‌شود. این معادل دستور o1 -= o2 در پایتون است.

PyObject *PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

نتیجه‌ی ضرب o1 و o2 را برمی‌گرداند، یا در صورت شکست NULL. این عملیات زمانی که o1 از آن پشتیبانی کند، به‌صورت درجا انجام می‌شود. این معادل دستور o1 *= o2 در پایتون است.

PyObject *PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.7.

نتیجه‌ی ضرب ماتریسی روی o1 و o2 را برمی‌گرداند، یا در صورت شکست NULL. این عملیات زمانی درجا انجام می‌شود که o1 از آن پشتیبانی کند. این معادل دستور پایتونی o1 @= o2 است.

اضافه شده در نسخه‌ی 3.5.

PyObject *PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

کف ریاضی تقسیم o1 بر o2 را برمی‌گرداند، یا در صورت شکست NULL. این عملیات زمانی که o1 از آن پشتیبانی کند، به‌صورت درجا انجام می‌شود. این معادل دستور پایتونی o1 //= o2 است.

PyObject *PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

تقریب معقولی از مقدار ریاضیِ o1 تقسیم بر o2 را برمی‌گرداند، یا در صورت شکست NULL. مقدار بازگشتی «تقریبی» است زیرا اعداد ممیز شناور دودویی تقریبی‌اند؛ نمی‌توان تمامی اعداد حقیقی را در مبنای دو نمایش داد. این تابع می‌تواند هنگامی که دو عدد صحیح به آن داده شود، مقداری ممیز شناور برگرداند. این عملیات در صورتی که o1 از آن پشتیبانی کند، درجا انجام می‌شود. این معادل دستور پایتونی o1 /= o2 است.

PyObject *PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

باقیمانده‌ی تقسیم o1 بر o2 را برمی‌گرداند، یا در صورت شکست NULL. این عملیات زمانی که o1 از آن پشتیبانی کند، درجا انجام می‌شود. این معادل دستور پایتونی o1 %= o2 است.

PyObject *PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

تابع توکار pow() را ببینید. در صورت شکست، NULL را برمی‌گرداند. این عملیات زمانی که o1 از آن پشتیبانی کند، درجا انجام می‌شود. این معادل دستور پایتونی o1 **= o2 است وقتی که o3 برابر Py_None باشد، یا در غیر این صورت، گونه‌ی درجای pow(o1, o2, o3) است. اگر قرار باشد o3 نادیده گرفته شود، Py_None را به‌جای آن پاس دهید (پاس دادن NULL برای o3 باعث دسترسی غیرمجاز به حافظه خواهد شد).

PyObject *PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

در صورت موفقیت، نتیجه‌ی شیفت به چپ o1 به اندازه‌ی o2 و در صورت شکست NULL را برمی‌گرداند. این عملیات در صورتی که o1 از آن پشتیبانی کند، به‌صورت درجا (in-place) انجام می‌شود. این معادل دستور o1 <<= o2 در پایتون است.

PyObject *PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

نتیجه‌ی شیفت به راست o1 به میزان o2 را در صورت موفقیت برمی‌گرداند و در صورت شکست NULL را. این عملیات زمانی که o1 از آن پشتیبانی کند، درجا انجام می‌شود. این معادل دستور پایتون o1 >>= o2 است.

PyObject *PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

در صورت موفقیت، «و بیتی» o1 و o2 را برمی‌گرداند و در صورت شکست NULL برمی‌گرداند. این عملیات زمانی که o1 از آن پشتیبانی کند، به‌صورت درجا انجام می‌شود. این معادل دستور پایتونی o1 &= o2 است.

PyObject *PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

در صورت موفقیت، «یای انحصاری بیتی» o1 با o2 را برمی‌گرداند و در صورت شکست NULL. این عملیات زمانی که o1 از آن پشتیبانی کند، درجا انجام می‌شود. این معادل دستور o1 ^= o2 در پایتون است.

PyObject *PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

در صورت موفقیت، «یای بیتی» o1 و o2 و در صورت شکست NULL را برمی‌گرداند. این عملیات هنگامی که o1 از آن پشتیبانی کند، به‌صورت درجا انجام می‌شود. این معادل دستور پایتونی o1 |= o2 است.

PyObject *PyNumber_Long(PyObject *o)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

در صورت موفقیت، o تبدیل‌شده به یک شیء عدد صحیح را بازمی‌گرداند، یا در صورت شکست NULL را برمی‌گرداند. این معادل عبارت پایتونی int(o) است.

PyObject *PyNumber_Float(PyObject *o)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

در صورت موفقیت، o تبدیل‌شده به یک شیء اعشاری و در صورت شکست NULL را برمی‌گرداند. این معادل عبارت پایتونی float(o) است.

PyObject *PyNumber_Index(PyObject *o)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

در صورت موفقیت، o تبدیل‌شده به یک عدد صحیح پایتون را برمی‌گرداند و در صورت شکست، NULL را همراه با ایجاد استثنای TypeError برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.10: نتیجه همیشه دقیقاً از نوع int است. پیش‌تر، نتیجه می‌توانست نمونه‌ای از یک زیرکلاس از int باشد.

PyObject *PyNumber_ToBase(PyObject *n, int base)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

عدد صحیح n تبدیل‌شده به مبنای base را به‌صورت رشته برمی‌گرداند. آرگومان base باید یکی از مقادیر ۲، ۸، ۱۰ یا ۱۶ باشد. برای مبنای ۲، ۸ یا ۱۶، رشته‌ی برگردانده‌شده به‌ترتیب با نشانگر مبنای '0b'، '0o' یا '0x' پیشوند می‌گیرد. اگر n یک int پایتون نباشد، ابتدا با PyNumber_Index() تبدیل می‌شود.

Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)¶

قسمتی از ABI پایدار.

در صورتی که o بتواند به عنوان یک عدد صحیح تفسیر شود، o را به یک مقدار Py_ssize_t تبدیل‌شده برمی‌گرداند. اگر فراخوانی شکست بخورد، یک استثنا مطرح می‌شود و -1 برگردانده می‌شود.

اگر o بتواند به یک int پایتون تبدیل شود، اما تلاش برای تبدیل به مقدار Py_ssize_t موجب ایجاد OverflowError شود، آنگاه آرگومان exc نوع استثنایی است که ایجاد خواهد شد (معمولاً IndexError یا OverflowError). اگر exc برابر NULL باشد، استثنا پاک می‌شود و مقدار برای عدد صحیح منفی به PY_SSIZE_T_MIN و برای عدد صحیح مثبت به PY_SSIZE_T_MAX بریده می‌شود.

int PyIndex_Check(PyObject *o)¶

قسمتی از ABI پایدار از نسخه‌ی 3.8.

اگر o یک عدد صحیح اندیس باشد (جایگاه nb_index در ساختار tp_as_number آن پر شده باشد)، 1 و در غیر این صورت 0 برمی‌گرداند. این تابع همیشه موفق می‌شود.