اشیاء تاپل

type PyTupleObject

این زیرنوع از PyObject معرف یک شیء تاپل پایتون است.

PyTypeObject PyTuple_Type

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

این نمونه از PyTypeObject نوع تاپل پایتون را نشان می‌دهد؛ این همان شیء tuple در لایه‌ی پایتون است.

int PyTuple_Check(PyObject *p)

اگر p یک شیء تاپل یا نمونه‌ای از یک زیرنوع از نوع تاپل باشد، مقدار true را برمی‌گرداند. این تابع همیشه موفق می‌شود.

int PyTuple_CheckExact(PyObject *p)

اگر p یک شیء تاپل باشد، اما نمونه‌ای از زیرنوعی از نوع تاپل نباشد، مقدار true را برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود.

PyObject *PyTuple_New(Py_ssize_t len)

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

یک شیء تاپل جدید با اندازه‌ی len برمی‌گرداند، یا در صورت شکست NULL را همراه با استثنای تنظیم‌شده برمی‌گرداند.

PyObject *PyTuple_Pack(Py_ssize_t n, ...)

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

یک شیء تاپل جدید با اندازه‌ی n برمی‌گرداند، یا در صورت شکست NULL به همراه یک استثنای تنظیم‌شده برمی‌گرداند. مقادیر تاپل به n آرگومان C بعدی که به اشیاء پایتون اشاره می‌کنند، مقداردهی اولیه می‌شوند. PyTuple_Pack(2, a, b) معادل Py_BuildValue("(OO)", a, b) است.

Py_ssize_t PyTuple_Size(PyObject *p)

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

یک اشاره‌گر به شیء تاپل می‌گیرد و اندازه‌ی آن تاپل را برمی‌گرداند. در صورت خطا، -1 همراه با استثنای تنظیم‌شده برمی‌گرداند.

Py_ssize_t PyTuple_GET_SIZE(PyObject *p)

مانند PyTuple_Size()، اما بدون بررسی خطا.

PyObject *PyTuple_GetItem(PyObject *p, Py_ssize_t pos)

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

شیء در موقعیت pos در تاپلی که توسط p به آن اشاره می‌شود را برمی‌گرداند. اگر pos منفی یا خارج از محدوده باشد، NULL را برمی‌گرداند و یک استثنای IndexError تنظیم می‌کند.

ارجاع بازگردانده‌شده از تاپل p امانت گرفته شده است (یعنی: تنها تا زمانی که شما ارجاعی به p را در اختیار دارید معتبر است). برای به دست آوردن ارجاع قوی، از Py_NewRef(PyTuple_GetItem(...)) یا PySequence_GetItem() استفاده کنید.

PyObject *PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)

مقدار بازگشتی: مرجع امانتی.

مانند PyTuple_GetItem()، اما هیچ بررسی‌ای روی آرگومان‌های خود انجام نمی‌دهد.

PyObject *PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)

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

اسلایس تاپلی را که p به آن اشاره می‌کند، بین low و high برمی‌گرداند، یا در صورت شکست NULL را همراه با استثنای تنظیم‌شده برمی‌گرداند.

این معادل عبارت پایتونی p[low:high] است. اندیس‌گذاری از انتهای تاپل پشتیبانی نمی‌شود.

int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

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

یک ارجاع به شیء o در موقعیت pos از تاپلی که p به آن اشاره می‌کند، درج می‌کند. در صورت موفقیت 0 برمی‌گرداند. اگر pos خارج از محدوده باشد، -1 برمی‌گرداند و استثنای IndexError را تنظیم می‌کند.

توجه

این تابع ارجاعی به o را «می‌دزدد (steal)» و ارجاع به آیتمی را که از قبل در جایگاه مورد تأثیر تاپل قرار دارد، دور می‌ریزد (مگر اینکه NULL بوده باشد).

void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)

مانند PyTuple_SetItem() است، اما هیچ بررسی خطایی انجام نمی‌دهد و باید فقط برای پر کردن تاپل‌های کاملاً جدید استفاده شود.

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

توجه

این تابع ارجاعی به o را «می‌دزدد» و برخلاف PyTuple_SetItem()، ارجاع به هیچ آیتمی را که در حال جایگزینی است دور نمی‌اندازد؛ هر ارجاعی که در جایگاه pos از تاپل باشد، نشت خواهد شد.

هشدار

این ماکرو باید تنها روی تاپل‌هایی که به‌تازگی ایجاد شده‌اند استفاده شود. استفاده از این ماکرو روی تاپلی که از قبل در حال استفاده است (یا به عبارت دیگر، شمارش ارجاع آن بزرگ‌تر از ۱ است) ممکن است به رفتار تعریف‌نشده منجر شود.

int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)

می‌تواند برای تغییر اندازه‌ی یک تاپل استفاده شود. newsize طول جدید تاپل خواهد بود. از آنجا که تاپل‌ها قرار است تغییرناپذیر باشند، این تابع فقط باید زمانی استفاده شود که تنها یک ارجاع به شیء وجود داشته باشد. اگر ممکن است تاپل از قبل توسط بخش دیگری از کد شناخته شده باشد، از این تابع استفاده نکنید. تاپل همیشه از انتها بزرگ‌تر یا کوچک‌تر می‌شود. این کار را به‌عنوان نابود کردن تاپل قدیمی و ایجاد یک تاپل جدید در نظر بگیرید، فقط با کارایی بیشتر. در صورت موفقیت 0 را برمی‌گرداند. کد کلاینت هرگز نباید فرض کند که مقدار حاصل *p با مقدار قبل از فراخوانی این تابع یکسان خواهد بود. اگر شیء ارجاع‌شده توسط *p جایگزین شود، *p اصلی نابود می‌شود. در صورت شکست، -1 را برمی‌گرداند، *p را برابر NULL قرار می‌دهد و MemoryError یا SystemError ایجاد می‌کند.

اشیاء دنباله ساختاری

اشیاء دنباله ساختاری معادل C برای اشیاء namedtuple() هستند؛ یعنی دنباله‌ای که به آیتم‌های آن می‌توان از طریق ویژگی‌ها نیز دسترسی داشت. برای ایجاد یک دنباله ساختاری، ابتدا باید یک نوع دنباله ساختاری خاص ایجاد کنید.

PyTypeObject *PyStructSequence_NewType(PyStructSequence_Desc *desc)

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

نوع دنباله ساختاری جدیدی از داده‌های موجود در desc که در ادامه توضیح داده شده است، ایجاد می‌کند. نمونه‌های نوع حاصل را می‌توان با PyStructSequence_New() ایجاد کرد.

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

void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)

نوع دنباله ساختاری type را از روی desc به‌صورت درجا مقداردهی اولیه می‌کند.

int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)

مانند PyStructSequence_InitType()، با این تفاوت که در صورت موفقیت 0 و در صورت شکست -1 همراه با تنظیم یک استثنا برمی‌گرداند.

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

type PyStructSequence_Desc

قسمتی از ABI پایدار شامل تمام اعضا.

شامل فراطلاعات نوع دنباله ساختاری‌ای است که باید ایجاد شود.

const char *name

نام کامل نوع؛ پایان‌یافته با تهی و کدگذاری‌شده با UTF-8. نام باید شامل نام ماژول باشد.

const char *doc

اشاره‌گر به رشته‌ی مستند برای نوع، یا NULL برای حذف آن.

PyStructSequence_Field *fields

اشاره‌گر به آرایه‌ی خاتمه‌یافته با NULL حاوی نام فیلدهای نوع جدید.

int n_in_sequence

تعداد فیلدهای قابل مشاهده برای سمت پایتون (در صورت استفاده به‌عنوان تاپل).

type PyStructSequence_Field

قسمتی از ABI پایدار شامل تمام اعضا.

یک فیلد از دنباله ساختاری را توصیف می‌کند. از آنجا که دنباله ساختاری به‌صورت یک تاپل مدل‌سازی می‌شود، همه‌ی فیلدها از نوع PyObject* هستند. اندیس در آرایه‌ی fields از PyStructSequence_Desc تعیین می‌کند که کدام فیلد از دنباله ساختاری توصیف می‌شود.

const char *name

نام فیلد یا NULL برای پایان دادن به فهرست فیلدهای نام‌دار؛ برای بی‌نام گذاشتن فیلد، روی PyStructSequence_UnnamedField تنظیم می‌شود.

const char *doc

رشته مستند فیلد یا NULL برای حذف.

const char *const PyStructSequence_UnnamedField

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

مقدار ویژه برای نام فیلد که آن را بی‌نام باقی می‌گذارد.

تغییر یافته در نسخه‌ی 3.9: نوع از char * تغییر یافت.

PyObject *PyStructSequence_New(PyTypeObject *type)

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

یک نمونه از type ایجاد می‌کند که باید با PyStructSequence_NewType() ایجاد شده باشد.

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

PyObject *PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)

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

شیء موجود در موقعیت pos در دنباله ساختاری‌ای که p به آن اشاره می‌کند را برمی‌گرداند.

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

PyObject *PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)

مقدار بازگشتی: مرجع امانتی.

نام مستعاری برای PyStructSequence_GetItem() است.

تغییر یافته در نسخه‌ی 3.13: اکنون به عنوان مستعاری برای PyStructSequence_GetItem() پیاده‌سازی شده است.

void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

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

فیلد در اندیس pos از دنباله ساختاری p را به مقدار o تنظیم می‌کند. مانند PyTuple_SET_ITEM()، این باید فقط برای پر کردن نمونه‌های کاملاً جدید استفاده شود.

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

توجه

این تابع ارجاعی به o را «می‌دزدد».

void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)

نام مستعاری برای PyStructSequence_SetItem() است.

تغییر یافته در نسخه‌ی 3.13: اکنون به عنوان نامی مستعار برای PyStructSequence_SetItem() پیاده‌سازی شده است.