شیءهای عدد صحیح

تمام اعداد صحیح به‌صورت اشیاء عدد صحیح «long» با اندازه دلخواه پیاده‌سازی شده‌اند.

در صورت خطا، بیشتر APIهای PyLong_As* مقدار (return type)-1 را برمی‌گردانند که از یک عدد قابل تشخیص نیست. برای رفع ابهام از PyErr_Occurred() استفاده کنید.

type PyLongObject
قسمتی از API محدود (به‌عنوان یک ساختار مبهم).

این زیرنوع از PyObject یک شیء عدد صحیح پایتون را نشان می‌دهد.

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

این نمونه از PyTypeObject نوع عدد صحیح پایتون را نشان می‌دهد. این همان شیء int در لایه‌ی پایتون است.

int PyLong_Check(PyObject *p)

اگر آرگومان آن یک PyLongObject یا زیرنوعی از PyLongObject باشد، مقدار true را برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود.

int PyLong_CheckExact(PyObject *p)

در صورتی که آرگومان آن یک PyLongObject باشد، اما زیرنوعی از PyLongObject نباشد، مقدار true را برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود.

PyObject *PyLong_FromLong(long v)
مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

یک شیء جدید PyLongObject از v برمی‌گرداند، یا در صورت شکست NULL.

سی‌پایتون آرایه‌ای از اشیاء عدد صحیح را برای تمام اعداد صحیح بین -5 و 256 نگه می‌دارد. وقتی شما یک int در این بازه ایجاد می‌کنید، در واقع فقط ارجاعی به شیء موجود را دریافت می‌کنید.

PyObject *PyLong_FromUnsignedLong(unsigned long v)
مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

یک شیء جدید PyLongObject از یک unsigned long در C برمی‌گرداند، یا در صورت شکست NULL.

PyObject *PyLong_FromSsize_t(Py_ssize_t v)
مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

یک شیء جدید PyLongObject از یک Py_ssize_t در C برمی‌گرداند، یا در صورت شکست NULL.

PyObject *PyLong_FromSize_t(size_t v)
مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

یک شیء جدید PyLongObject از یک size_t در C برمی‌گرداند، یا در صورت شکست NULL.

PyObject *PyLong_FromLongLong(long long v)
مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

یک شیء جدید PyLongObject از یک long long در C برمی‌گرداند، یا در صورت شکست NULL.

PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)
مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

یک شیء جدید PyLongObject از یک unsigned long long در C برمی‌گرداند، یا در صورت شکست NULL.

PyObject *PyLong_FromInt32(int32_t value)
PyObject *PyLong_FromInt64(int64_t value)
قسمتی از ABI پایدار از نسخه‌ی 3.14.

یک شیء جدید PyLongObject از یک int32_t یا int64_t علامت‌دار در C برمی‌گرداند، یا در صورت شکست NULL را همراه با یک استثنای تنظیم‌شده برمی‌گرداند.

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

PyObject *PyLong_FromUInt32(uint32_t value)
PyObject *PyLong_FromUInt64(uint64_t value)
قسمتی از ABI پایدار از نسخه‌ی 3.14.

یک شیء جدید PyLongObject از یک uint32_t یا uint64_t بدون علامت C برمی‌گرداند، یا در صورت شکست، NULL همراه با یک استثنای تنظیم‌شده برمی‌گرداند.

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

PyObject *PyLong_FromDouble(double v)
مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

یک شیء جدید PyLongObject از بخش عدد صحیح v برمی‌گرداند، یا در صورت شکست NULL.

PyObject *PyLong_FromString(const char *str, char **pend, int base)
مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

یک PyLongObject جدید بر اساس مقدار رشته‌ای موجود در str برمی‌گرداند که مطابق با مبنای عددی موجود در base تفسیر می‌شود، یا در صورت شکست NULL برمی‌گرداند. اگر pend غیر NULL باشد، *pend در صورت موفقیت به انتهای str و در صورت خطا به نخستین نویسه‌ای که نتوان آن را پردازش کرد اشاره خواهد کرد. اگر base برابر 0 باشد، str با استفاده از تعریف مقادیر لفظی عدد صحیح تفسیر می‌شود؛ در این حالت، صفرهای ابتدایی در یک عدد ده‌دهی غیرصفر باعث پرتاب استثنای ValueError می‌شوند. اگر base برابر 0 نباشد، باید مقداری بین 2 و 36 (با احتساب هر دو) باشد. فضاهای سفید ابتدایی و انتهایی و همچنین زیرسطرهای تکی پس از مشخص‌کننده‌ی مبنا و بین ارقام نادیده گرفته می‌شوند. اگر هیچ رقمی وجود نداشته باشد یا str پس از ارقام و فضاهای سفید انتهایی با NULL خاتمه نیافته باشد، استثنای ValueError پرتاب خواهد شد.

همچنین ملاحظه نمائید

می‌توان از توابع PyLong_AsNativeBytes() و PyLong_FromNativeBytes() برای تبدیل یک PyLongObject به/از آرایه‌ای از بایت‌ها در مبنای 256 استفاده کرد.

PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)
مقدار بازگشتی: مرجع جدید.

تبدیل دنباله‌ای از ارقام یونیکد در رشته u به یک مقدار عدد صحیح پایتون.

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

PyObject *PyLong_FromVoidPtr(void *p)
مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

یک عدد صحیح پایتون از اشاره‌گر p می‌سازد. مقدار اشاره‌گر را می‌توان با استفاده از PyLong_AsVoidPtr() از مقدار حاصل بازیابی کرد.

PyObject *PyLong_FromNativeBytes(const void *buffer, size_t n_bytes, int flags)
قسمتی از ABI پایدار از نسخه‌ی 3.14.

یک عدد صحیح پایتون از مقدار موجود در n_bytes اول buffer می‌سازد که به‌عنوان یک عدد علامت‌دار مکمل دو تفسیر می‌شود.

flags همان‌طور است که برای PyLong_AsNativeBytes() توضیح داده شده است. با ارسال -1، اندیان بومی‌ای که سی‌پایتون با آن کامپایل شده است انتخاب می‌شود و فرض می‌شود که بیش‌ارزش‌ترین بیت، بیت علامت است. با ارسال Py_ASNATIVEBYTES_UNSIGNED_BUFFER، همان نتیجه‌ی فراخوانی PyLong_FromUnsignedNativeBytes() تولید می‌شود. سایر پرچم‌ها نادیده گرفته می‌شوند.

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

PyObject *PyLong_FromUnsignedNativeBytes(const void *buffer, size_t n_bytes, int flags)
قسمتی از ABI پایدار از نسخه‌ی 3.14.

یک عدد صحیح پایتون از مقدار موجود در n_bytes بایت اول buffer بسازید که به‌عنوان یک عدد بدون علامت تفسیر می‌شود.

flags همانند PyLong_AsNativeBytes() است. ارسال -1 اندیان بومی‌ای را که سی‌پایتون با آن کامپایل شده است انتخاب می‌کند و فرض می‌کند که بیش‌اهمیت‌ترین بیت، بیت علامت نیست. پرچم‌های غیر از اندیان نادیده گرفته می‌شوند.

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

PyLong_FromPid(pid)

ماکرویی برای ایجاد یک عدد صحیح پایتون از شناسه‌ی فرایند.

این می‌تواند بسته به اندازه‌ی نوع PID سیستم، به عنوان مستعاری برای PyLong_FromLong() یا PyLong_FromLongLong() تعریف شود.

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

long PyLong_AsLong(PyObject *obj)
قسمتی از ABI پایدار.

نمایشی از نوع long در زبان C از obj برمی‌گرداند. اگر 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 یا استثنای دیگری شکست بخورد.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.14.

int PyLong_AsInt(PyObject *obj)
قسمتی از ABI پایدار از نسخه‌ی 3.13.

مانند PyLong_AsLong()، اما نتیجه را به‌جای یک long در C، در یک int در C ذخیره می‌کند.

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

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
قسمتی از ABI پایدار.

نمایشی از نوع long در زبان C از obj برمی‌گرداند. اگر obj نمونه‌ای از PyLongObject نباشد، ابتدا متد __index__() آن (در صورت وجود) فراخوانی می‌شود تا به PyLongObject تبدیل شود.

اگر مقدار obj بزرگ‌تر از LONG_MAX یا کوچک‌تر از LONG_MIN باشد، *overflow را به‌ترتیب برابر 1 یا -1 قرار می‌دهد و -1 را برمی‌گرداند؛ در غیر این صورت، *overflow را برابر 0 قرار می‌دهد. اگر هر استثنای دیگری رخ دهد، *overflow را برابر 0 قرار می‌دهد و -1 را طبق معمول برمی‌گرداند.

در صورت خطا -1 برمی‌گرداند. برای رفع ابهام از PyErr_Occurred() استفاده کنید.

تغییر یافته در نسخه‌ی 3.8: در صورت وجود، از __index__() استفاده کنید.

تغییر یافته در نسخه‌ی 3.10: این تابع دیگر از __int__() استفاده نخواهد کرد.

long long PyLong_AsLongLong(PyObject *obj)
قسمتی از 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)
قسمتی از ABI پایدار.

نمایشی از obj به صورت C long long برمی‌گرداند. اگر obj نمونه‌ای از PyLongObject نباشد، ابتدا متد __index__() آن (در صورت وجود) فراخوانی می‌شود تا به PyLongObject تبدیل شود.

اگر مقدار obj بزرگ‌تر از LLONG_MAX یا کوچک‌تر از LLONG_MIN باشد، *overflow را به‌ترتیب روی 1 یا -1 قرار می‌دهد و -1 را برمی‌گرداند؛ در غیر این صورت، *overflow را روی 0 قرار می‌دهد. اگر استثنای دیگری رخ دهد، *overflow را روی 0 قرار می‌دهد و -1 را طبق معمول برمی‌گرداند.

در صورت خطا -1 برمی‌گرداند. برای رفع ابهام از PyErr_Occurred() استفاده کنید.

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

تغییر یافته در نسخه‌ی 3.8: در صورت وجود، از __index__() استفاده کنید.

تغییر یافته در نسخه‌ی 3.10: این تابع دیگر از __int__() استفاده نخواهد کرد.

Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
قسمتی از ABI پایدار.

نمایش C از pylong به‌صورت Py_ssize_t را برمی‌گرداند. pylong باید نمونه‌ای از PyLongObject باشد.

اگر مقدار pylong خارج از محدوده‌ی Py_ssize_t باشد، استثنای OverflowError ایجاد می‌کند.

در صورت خطا -1 برمی‌گرداند. برای رفع ابهام از PyErr_Occurred() استفاده کنید.

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
قسمتی از ABI پایدار.

نمایش unsigned long در C از pylong را برمی‌گرداند. pylong باید نمونه‌ای از PyLongObject باشد.

اگر مقدار pylong خارج از محدوده‌ی unsigned long باشد، OverflowError ایجاد می‌کند.

در صورت خطا (unsigned long)-1 را برمی‌گرداند. برای رفع ابهام از PyErr_Occurred() استفاده کنید.

size_t PyLong_AsSize_t(PyObject *pylong)
قسمتی از ABI پایدار.

نمایش C size_t از pylong را برمی‌گرداند. pylong باید نمونه‌ای از PyLongObject باشد.

اگر مقدار pylong خارج از محدوده‌ی size_t باشد، استثنای OverflowError را ایجاد می‌کند.

در صورت خطا (size_t)-1 برمی‌گرداند. برای رفع ابهام از PyErr_Occurred() استفاده کنید.

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)
قسمتی از ABI پایدار.

نمایش C unsigned long long از pylong را برمی‌گرداند. pylong باید نمونه‌ای از PyLongObject باشد.

اگر مقدار pylong خارج از محدوده‌ی یک unsigned long long باشد، استثنای OverflowError ایجاد می‌شود.

در صورت خطا (unsigned long long)-1 برمی‌گرداند. برای رفع ابهام از PyErr_Occurred() استفاده کنید.

تغییر یافته در نسخه‌ی 3.1: یک pylong منفی اکنون OverflowError ایجاد می‌کند، نه TypeError.

unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
قسمتی از ABI پایدار.

نمایشی از obj را به صورت unsigned long در C برمی‌گرداند. اگر 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)
قسمتی از ABI پایدار.

یک نمایش unsigned long long در C از obj برمی‌گرداند. اگر 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)
قسمتی از ABI پایدار از نسخه‌ی 3.14.

مقدار *value را به نمایش علامت‌دار int32_t یا int64_t زبان C از obj تنظیم می‌کند.

اگر obj نمونه‌ای از PyLongObject نباشد، ابتدا متد __index__() آن (در صورت وجود) فراخوانی می‌شود تا آن را به PyLongObject تبدیل کند.

اگر مقدار obj خارج از محدوده باشد، یک OverflowError ایجاد می‌شود.

در صورت موفقیت، *value را تنظیم کرده و 0 را برمی‌گرداند. در صورت خطا، یک استثنا تنظیم کرده و -1 را برمی‌گرداند.

value نباید NULL باشد.

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

int PyLong_AsUInt32(PyObject *obj, uint32_t *value)
int PyLong_AsUInt64(PyObject *obj, uint64_t *value)
قسمتی از ABI پایدار از نسخه‌ی 3.14.

مقدار *value را به بازنمایی بدون علامت uint32_t یا uint64_t در C از obj تنظیم کنید.

اگر obj نمونه‌ای از PyLongObject نباشد، ابتدا متد __index__() آن (در صورت وجود) فراخوانی می‌شود تا آن را به PyLongObject تبدیل کند.

  • اگر obj منفی باشد، یک ValueError raise می‌شود.

  • اگر مقدار obj خارج از محدوده باشد، یک OverflowError ایجاد می‌شود.

در صورت موفقیت، *value را تنظیم کرده و 0 را برمی‌گرداند. در صورت خطا، یک استثنا تنظیم کرده و -1 را برمی‌گرداند.

value نباید NULL باشد.

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

double PyLong_AsDouble(PyObject *pylong)
قسمتی از ABI پایدار.

بازنمایی pylong را به‌صورت یک double در C برمی‌گرداند. pylong باید نمونه‌ای از PyLongObject باشد.

اگر مقدار pylong از محدوده‌ی double خارج باشد، استثنای OverflowError ایجاد می‌شود.

در صورت خطا -1.0 برمی‌گرداند. برای رفع ابهام از PyErr_Occurred() استفاده کنید.

void *PyLong_AsVoidPtr(PyObject *pylong)
قسمتی از ABI پایدار.

یک عدد صحیح پایتون pylong را به یک اشاره‌گر void در C تبدیل می‌کند. اگر pylong قابل تبدیل نباشد، یک OverflowError به‌وجود می‌آید. تولید اشاره‌گر void قابل استفاده فقط برای مقادیری که با PyLong_FromVoidPtr() ایجاد شده‌اند تضمین می‌شود.

در صورت خطا NULL برمی‌گرداند. برای رفع ابهام از PyErr_Occurred() استفاده کنید.

Py_ssize_t PyLong_AsNativeBytes(PyObject *pylong, void *buffer, Py_ssize_t n_bytes, int flags)
قسمتی از ABI پایدار از نسخه‌ی 3.14.

مقدار عدد صحیح پایتون pylong را به یک buffer بومی با اندازه‌ی n_bytes کپی کنید. flags را می‌توان روی -1 تنظیم کرد تا مشابه تبدیل نوع در زبان C رفتار کند، یا برای کنترل رفتار، روی مقادیر مستندشده در ادامه تنظیم کرد.

در صورت خطا، -1 را همراه با ایجاد یک استثنا برمی‌گرداند. این ممکن است زمانی رخ دهد که pylong نتواند به‌عنوان یک عدد صحیح تفسیر شود، یا اینکه pylong منفی بوده و پرچم Py_ASNATIVEBYTES_REJECT_NEGATIVE تنظیم شده باشد.

در غیر این صورت، تعداد بایت‌های مورد نیاز برای ذخیره مقدار را برمی‌گرداند. اگر این عدد برابر یا کمتر از n_bytes باشد، کل مقدار کپی شده است. تمام n_bytes بافر نوشته می‌شوند: بایت‌های باقی‌مانده با کپی‌هایی از بیت علامت پر می‌شوند.

اگر مقدار بازگشتی بزرگ‌تر از n_bytes باشد، مقدار اسلایس‌شده است: هر تعداد از کم‌ارزش‌ترین بیت‌های مقدار که جا داشتند نوشته می‌شوند و بیت‌های پرارزش نادیده گرفته می‌شوند. این با رفتار معمول تبدیل نوع به پایین (downcast) به سبک C مطابقت دارد.

توجه

سرریز به‌عنوان خطا در نظر گرفته نمی‌شود. اگر مقدار بازگشتی بزرگ‌تر از n_bytes باشد، بیت‌های پرارزش دور ریخته شده‌اند.

0 هرگز بازگردانده نمی‌شود.

مقادیر همیشه به‌صورت مکمل دو کپی می‌شوند.

مثال استفاده:

int32_t value;
Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, &value, sizeof(value), -1);
if (bytes < 0) {
    // Failed. A Python exception was set with the reason.
    return NULL;
}
else if (bytes <= (Py_ssize_t)sizeof(value)) {
    // Success!
}
else {
    // Overflow occurred, but 'value' contains the truncated
    // lowest bits of pylong.
}

ارسال صفر به n_bytes اندازه‌ی بافری را برمی‌گرداند که برای نگه‌داشتن مقدار به‌اندازه‌ی کافی بزرگ باشد. این اندازه ممکن است از آنچه از نظر فنی لازم است بزرگ‌تر باشد، اما نه به‌طور نامعقول. اگر n_bytes=0 باشد، buffer می‌تواند NULL باشد.

توجه

ارسال n_bytes=0 به این تابع، راه دقیقی برای تعیین طول بیتی مقدار نیست.

برای دسترسی به کل مقدار پایتون با اندازه‌ی نامشخص، می‌توان تابع را دو بار فراخوانی کرد: ابتدا برای تعیین اندازه‌ی بافر، سپس برای پر کردن آن:

// Ask how much space we need.
Py_ssize_t expected = PyLong_AsNativeBytes(pylong, NULL, 0, -1);
if (expected < 0) {
    // Failed. A Python exception was set with the reason.
    return NULL;
}
assert(expected != 0);  // Impossible per the API definition.
uint8_t *bignum = malloc(expected);
if (!bignum) {
    PyErr_SetString(PyExc_MemoryError, "bignum malloc failed.");
    return NULL;
}
// Safely get the entire value.
Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, bignum, expected, -1);
if (bytes < 0) {  // Exception has been set.
    free(bignum);
    return NULL;
}
else if (bytes > expected) {  // This should not be possible.
    PyErr_SetString(PyExc_RuntimeError,
        "Unexpected bignum truncation after a size check.");
    free(bignum);
    return NULL;
}
// The expected success given the above pre-check.
// ... use bignum ...
free(bignum);

flags یا -1 (Py_ASNATIVEBYTES_DEFAULTS) است تا پیش‌فرض‌هایی را انتخاب کند که رفتارشان بیشترین شباهت را به قالب‌ریزی C دارد، یا ترکیبی از پرچم‌های دیگر در جدول زیر است. توجه داشته باشید که -1 را نمی‌توان با پرچم‌های دیگر ترکیب کرد.

در حال حاضر، -1 معادل Py_ASNATIVEBYTES_NATIVE_ENDIAN | Py_ASNATIVEBYTES_UNSIGNED_BUFFER است.

پرچم

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

-1
Py_ASNATIVEBYTES_BIG_ENDIAN
قسمتی از ABI پایدار از نسخه‌ی 3.14.

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

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

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

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

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

16

مشخص کردن Py_ASNATIVEBYTES_NATIVE_ENDIAN هر پرچم اندیان دیگری را لغو می‌کند. ارسال 2 رزرو شده است.

به‌طور پیش‌فرض، بافر کافی برای گنجاندن بیت علامت درخواست می‌شود. برای مثال، هنگام تبدیل ۱۲۸ با n_bytes=1، تابع ۲ (یا بیشتر) را برمی‌گرداند تا بیت علامت صفر ذخیره شود.

اگر Py_ASNATIVEBYTES_UNSIGNED_BUFFER مشخص شده باشد، بیت علامت صفر از محاسبات اندازه حذف می‌شود. این امکان را فراهم می‌کند که برای مثال عدد ۱۲۸ در یک بافر تک‌بایتی جا شود. اگر بافر مقصد بعداً علامت‌دار تلقی شود، ممکن است یک مقدار ورودی مثبت به مقداری منفی تبدیل شود. توجه داشته باشید که این پرچم بر مدیریت مقادیر منفی تأثیری ندارد: برای این مقادیر، همیشه فضایی برای بیت علامت درخواست می‌شود.

مشخص کردن Py_ASNATIVEBYTES_REJECT_NEGATIVE باعث می‌شود در صورت منفی بودن pylong، یک استثنا تنظیم شود. بدون این پرچم، مقادیر منفی کپی می‌شوند، به شرطی که فضای کافی برای حداقل یک بیت علامت وجود داشته باشد؛ صرف‌نظر از اینکه Py_ASNATIVEBYTES_UNSIGNED_BUFFER مشخص شده باشد یا خیر.

اگر Py_ASNATIVEBYTES_ALLOW_INDEX تعیین شده باشد و یک مقدار غیر عدد صحیح پاس داده شود، متد __index__() آن ابتدا فراخوانی خواهد شد. این ممکن است منجر به اجرای کد پایتون شود و به نخ‌های دیگر اجازه اجرا داده شود، که می‌تواند تغییراتی در اشیاء یا مقادیر دیگر در حال استفاده ایجاد کند. وقتی flags برابر -1 باشد، این گزینه تنظیم نشده است و مقادیر غیر عدد صحیح باعث ایجاد TypeError می‌شوند.

توجه

با flags پیش‌فرض (-1، یا UNSIGNED_BUFFER بدون REJECT_NEGATIVE)، چندین عدد صحیح پایتون می‌توانند بدون سرریز به یک مقدار واحد نگاشت شوند. برای مثال، هر دو 255 و -1 در یک بافر تک‌بایتی جا می‌شوند و تمام بیت‌های آن را تنظیم می‌کنند. این با رفتار تبدیل نوع معمول در C مطابقت دارد.

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

PyLong_AsPid(pid)

ماکرویی برای تبدیل یک عدد صحیح پایتون به شناسه فرایند.

این می‌تواند بسته به اندازه‌ی نوع PID سیستم، به عنوان نام مستعاری برای PyLong_AsLong()، PyLong_FromLongLong() یا PyLong_AsInt() تعریف شود.

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

int PyLong_GetSign(PyObject *obj, int *sign)

علامت شیء عدد صحیح obj را دریافت کنید.

در صورت موفقیت، *sign را برابر علامت عدد صحیح قرار می‌دهد (به ترتیب ۰، -۱ یا +۱ برای عدد صحیح صفر، منفی یا مثبت) و ۰ را برمی‌گرداند.

در صورت شکست، مقدار -1 را همراه با یک استثنای تنظیم‌شده برمی‌گرداند. اگر obj یک PyLongObject یا زیرنوع آن باشد، این تابع همیشه موفق می‌شود.

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

int PyLong_IsPositive(PyObject *obj)

بررسی کنید که شیء عدد صحیح obj مثبت باشد (obj > 0).

اگر obj نمونه‌ای از PyLongObject یا زیرنوع آن باشد، در صورت مثبت بودن 1 و در غیر این صورت 0 را برمی‌گرداند. وگرنه یک استثنا تنظیم کرده و -1 را برمی‌گرداند.

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

int PyLong_IsNegative(PyObject *obj)

بررسی می‌کند که آیا شیء عدد صحیح obj منفی است (obj < 0).

اگر obj نمونه‌ای از PyLongObject یا زیرنوع آن باشد، در صورت منفی بودن 1 و در غیر این صورت 0 برمی‌گرداند. وگرنه یک استثنا تنظیم کرده و -1 برمی‌گرداند.

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

int PyLong_IsZero(PyObject *obj)

بررسی کنید که آیا شیء عدد صحیح obj صفر است.

اگر obj نمونه‌ای از PyLongObject یا زیرنوع آن باشد، در صورت صفر بودن مقدار 1 و در غیر این صورت 0 را برمی‌گرداند. در غیر این صورت، یک استثنا تنظیم می‌کند و -1 را برمی‌گرداند.

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

PyObject *PyLong_GetInfo(void)
قسمتی از ABI پایدار.

در صورت موفقیت، یک named tuple فقط‌خواندنی برمی‌گرداند که حاوی اطلاعاتی درباره‌ی نمایش داخلی پایتون از اعداد صحیح است. برای توضیح هر یک از فیلدها به sys.int_info مراجعه کنید.

در صورت شکست، NULL را همراه با یک استثنای تنظیم‌شده برمی‌گرداند.

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

int PyUnstable_Long_IsCompact(const PyLongObject *op)
این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

اگر op فشرده باشد، ۱ و در غیر این صورت ۰ برمی‌گرداند.

این تابع به کدهای حساس به کارایی امکان می‌دهد تا یک «مسیر سریع» برای اعداد صحیح کوچک پیاده‌سازی کنند. برای مقادیر فشرده از PyUnstable_Long_CompactValue() استفاده کنید؛ برای مقادیر دیگر به یک تابع PyLong_As* یا PyLong_AsNativeBytes() مراجعه کنید.

انتظار می‌رود که افزایش سرعت برای اکثر کاربران ناچیز باشد.

اینکه دقیقاً چه مقادیری فشرده در نظر گرفته می‌شوند، جزئیات پیاده‌سازی است و ممکن است تغییر کند.

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

Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)
این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

اگر op فشرده باشد، همان‌طور که با PyUnstable_Long_IsCompact() تعیین می‌شود، مقدار آن را برمی‌گرداند.

در غیر این صورت، مقدار بازگشتی تعریف‌نشده است.

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

API اکسپورت

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

struct PyLongLayout

چیدمان آرایه‌ای از «رقم‌ها» («limbs» در اصطلاحات GMP)، که برای نمایش مقدار مطلق اعداد صحیح با دقت دلخواه استفاده می‌شود.

برای دریافت چیدمان بومی اشیاء int پایتون، که به‌طور داخلی برای اعداد صحیح با مقدار مطلق «به اندازه کافی بزرگ» به کار می‌رود، از PyLong_GetNativeLayout() استفاده کنید.

همچنین sys.int_info را ببینید که اطلاعات مشابهی را در پایتون در دسترس قرار می‌دهد.

uint8_t bits_per_digit

بیت به ازای هر رقم. برای مثال، یک رقم ۱۵ بیتی به این معنی است که بیت‌های ۰ تا ۱۴ حاوی اطلاعات معنادار هستند.

uint8_t digit_size

اندازه رقم بر حسب بایت. برای مثال، یک رقم ۱۵ بیتی حداقل به ۲ بایت نیاز خواهد داشت.

int8_t digits_order

ترتیب ارقام:

  • 1 برای باارزش‌ترین رقم در ابتدا

  • -1 برای کم‌ارزش‌ترین رقم در ابتدا

int8_t digit_endianness

اندیان ارقام:

  • 1 برای معنادارترین بایت در ابتدا (بزرگ‌اندیان)

  • -1 برای کم‌ارزش‌ترین بایت در ابتدا (کوچک‌اندیان)

const PyLongLayout *PyLong_GetNativeLayout(void)

دریافت چیدمان بومی اشیای int پایتون.

ساختار PyLongLayout را ببینید.

تابع نباید نه پیش از مقداردهی اولیه پایتون و نه پس از نهایی‌سازی پایتون فراخوانی شود. چیدمان بازگردانده‌شده تا زمان نهایی‌سازی پایتون معتبر است. چیدمان برای همه زیرمفسرهای پایتون در یک فرایند یکسان است و بنابراین می‌توان آن را در نهانگاه ذخیره کرد.

struct PyLongExport

اکسپورت یک شیء int پایتون.

دو حالت وجود دارد:

  • اگر 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)

یک شیء int پایتون را اکسپورت (export) می‌کند.

export_long باید به یک ساختار PyLongExport که توسط فراخواننده تخصیص داده‌شده است اشاره کند. این نباید NULL باشد.

در صورت موفقیت، *export_long را پر می‌کند و 0 برمی‌گرداند. در صورت خطا، یک استثنا تنظیم می‌کند و -1 برمی‌گرداند.

PyLong_FreeExport() باید زمانی فراخوانی شود که اکسپورت (export) دیگر مورد نیاز نیست.

این تابع همیشه موفق می‌شود اگر obj یک شیء int پایتون یا زیرکلاسی از آن باشد.

void PyLong_FreeExport(PyLongExport *export_long)

آزاد کردن اکسپورت (export) export_long که توسط PyLong_Export() ایجاد شده است.

فراخوانی PyLong_FreeExport() در صورتی که export_long->digits برابر NULL باشد، اختیاری است.

APIی PyLongWriter

می‌توان از API PyLongWriter برای ایمپورت کردن یک عدد صحیح استفاده کرد.

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

struct PyLongWriter

یک نمونه نویسنده‌ی int پایتون.

نمونه باید توسط PyLongWriter_Finish() یا PyLongWriter_Discard() نابود شود.

PyLongWriter *PyLongWriter_Create(int negative, Py_ssize_t ndigits, void **digits)

یک PyLongWriter ایجاد کنید.

در صورت موفقیت، *digits تخصیص داده می‌شود و یک نویسنده برگردانده می‌شود. در صورت خطا، یک استثنا تنظیم می‌شود و NULL برگردانده می‌شود.

negative در صورت منفی بودن عدد برابر 1 و در غیر این صورت برابر 0 است.

ndigits تعداد ارقام در آرایه digits است. باید بزرگ‌تر از ۰ باشد.

digits نباید NULL باشد.

پس از فراخوانی موفق این تابع، فراخوانی‌کننده باید آرایه‌ی ارقام digits را پر کند و سپس PyLongWriter_Finish() را فراخوانی کند تا یک int پایتونی به دست آورد. چیدمان digits توسط PyLong_GetNativeLayout() توصیف می‌شود.

رقم‌ها باید در بازه‌ی [0; (1 << bits_per_digit) - 1] باشند (که در آن bits_per_digit تعداد بیت‌های هر رقم است). هر رقم مرتبه‌بالا که استفاده نشده باشد، باید برابر 0 قرار داده شود.

به‌طور جایگزین، می‌توانید PyLongWriter_Discard() را فراخوانی کنید تا نمونه‌ی نویسنده را بدون ایجاد شیء int نابود کنید.

PyObject *PyLongWriter_Finish(PyLongWriter *writer)
مقدار بازگشتی: مرجع جدید.

یک PyLongWriter ایجاد‌شده توسط PyLongWriter_Create() را نهایی کنید.

در صورت موفقیت، یک شیء int پایتون برمی‌گرداند. در صورت خطا، یک استثنا تنظیم کرده و NULL را برمی‌گرداند.

این تابع نرمال‌سازی ارقام را انجام می‌دهد و در صورت نیاز، شیء را به یک عدد صحیح فشرده تبدیل می‌کند.

نمونه‌ی نوشتارگر و آرایه‌ی digits پس از فراخوانی نامعتبر می‌شوند.

void PyLongWriter_Discard(PyLongWriter *writer)

یک PyLongWriter ایجاد‌شده توسط PyLongWriter_Create() را دور بیندازید.

اگر writer برابر NULL باشد، هیچ عملیاتی انجام نمی‌شود.

نمونه‌ی نوشتارگر و آرایه‌ی digits پس از فراخوانی نامعتبر می‌شوند.

API منسوخ

این ماکروها به‌نرمی منسوخ هستند. آن‌ها پارامترهای نمایش داخلی نمونه‌های PyLongObject را توصیف می‌کنند.

به‌جای آن از PyLong_GetNativeLayout() استفاده کنید، همراه با PyLong_Export() برای خواندن داده‌های عدد صحیح یا PyLongWriter برای نوشتن آن. این‌ها در حال حاضر از همان چیدمان استفاده می‌کنند، اما به‌گونه‌ای طراحی شده‌اند که حتی اگر نمایش داخلی اعداد صحیح در سی‌پایتون تغییر کند، همچنان به‌درستی کار کنند.

PyLong_SHIFT

این معادل bits_per_digit در خروجی PyLong_GetNativeLayout() است.

PyLong_BASE

این در حال حاضر معادل 1 << PyLong_SHIFT است.

PyLong_MASK

این در حال حاضر معادل (1 << PyLong_SHIFT) - 1 است