اشیاء تاپل

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 پایدار. Thread safety: Atomic.

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

PyObject *PyTuple_FromArray(PyObject *const *array, Py_ssize_t size)

Thread safety: Atomic.

یک تاپل با size تا آیتم ایجاد کنید و ارجاعات را از array به تاپل جدید کپی کنید.

اگر size برابر با 0 باشد، array می‌تواند NULL باشد.

در صورت موفقیت، یک ارجاع جدید برگردانید. در صورت بروز خطا، یک استثنا تنظیم کنید و NULL را برگردانید.

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

PyObject *PyTuple_Pack(Py_ssize_t n, ...)

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

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

Py_ssize_t PyTuple_Size(PyObject *p)

قسمتی از ABI پایدار. Thread safety: Atomic.

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

Py_ssize_t PyTuple_GET_SIZE(PyObject *p)

Thread safety: Atomic.

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

PyObject *PyTuple_GetItem(PyObject *p, Py_ssize_t pos)

مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار. Thread safety: Safe to call from multiple threads with external synchronization only.

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

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

PyObject *PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)

مقدار بازگشتی: مرجع امانتی. Thread safety: Safe to call from multiple threads with external synchronization only.

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

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

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

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

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

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

قسمتی از ABI پایدار. Thread safety: Safe to call from multiple threads with external synchronization only.

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

نکته

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

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

Thread safety: Safe to call from multiple threads with external synchronization only.

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

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

نکته

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

هشدار

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

int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)

Thread safety: Safe to call from multiple threads with external synchronization only.

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

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

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

برای ایجاد یک دنباله ساختاری، ابتدا باید یک نوع دنباله ساختاری خاص ایجاد کنید.

PyTypeObject *PyStructSequence_NewType(PyStructSequence_Desc *desc)

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

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

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

void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)

Thread safety: Safe to call without external synchronization on distinct objects.

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

int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)

Thread safety: Safe to call without external synchronization on distinct objects.

مانند 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 پایدار. Thread safety: Atomic.

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

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

PyObject *PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)

مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار. Thread safety: Safe to call from multiple threads with external synchronization only.

شیء موجود در موقعیت pos را در دنباله ساختاری اشاره‌شده توسط p برگردانید. ارجاع برگردانده‌شده از دنباله ساختاری p قرض گرفته شده است (یعنی: تا زمانی که یک ارجاع به p را حفظ کنید معتبر است).

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

PyObject *PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)

مقدار بازگشتی: مرجع امانتی. Thread safety: Safe to call from multiple threads with external synchronization only.

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

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

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

قسمتی از ABI پایدار. Thread safety: Safe to call from multiple threads with external synchronization only.

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

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

نکته

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

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

Thread safety: Safe to call from multiple threads with external synchronization only.

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

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