اشیاء فهرست

type PyListObject

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

PyTypeObject PyList_Type

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

این نمونه از PyTypeObject نمایانگر نوع فهرست پایتون است. این همان شیء list در لایه‌ی پایتون است.

int PyList_Check(PyObject *p)

Thread safety: Atomic.

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

int PyList_CheckExact(PyObject *p)

Thread safety: Atomic.

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

PyObject *PyList_New(Py_ssize_t len)

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

در صورت موفقیت، فهرست جدیدی به طول len برمی‌گرداند، یا در صورت شکست NULL.

توجه

اگر len بزرگ‌تر از صفر باشد، آیتم‌های شیء فهرست بازگردانده‌شده روی NULL تنظیم می‌شوند. بنابراین پیش از آنکه تمام آیتم‌ها را با PyList_SetItem() یا PyList_SET_ITEM() روی یک شیء واقعی تنظیم کنید، نمی‌توانید از توابع API انتزاعی مانند PySequence_SetItem() استفاده کنید یا شیء را در دسترس کد پایتون قرار دهید. APIهای زیر پیش از آنکه فهرست به‌طور کامل مقداردهی اولیه شود، امن هستند: PyList_SetItem() و PyList_SET_ITEM().

Py_ssize_t PyList_Size(PyObject *list)

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

طول شیء فهرست در list را برمی‌گرداند؛ این معادل len(list) روی یک شیء فهرست است.

Py_ssize_t PyList_GET_SIZE(PyObject *list)

Thread safety: Atomic.

مشابه PyList_Size()، اما بدون بررسی خطا.

PyObject *PyList_GetItemRef(PyObject *list, Py_ssize_t index)

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

شیء موجود در موقعیت index در فهرستی که list به آن اشاره می‌کند را برمی‌گرداند. موقعیت باید نامنفی باشد؛ اندیس‌دهی از انتهای فهرست پشتیبانی نمی‌شود. اگر index خارج از محدوده باشد (<0 or >=len(list))، NULL را برمی‌گرداند و استثنای IndexError را تنظیم می‌کند.

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

PyObject *PyList_GetItem(PyObject *list, Py_ssize_t index)

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

مانند PyList_GetItemRef()، اما به‌جای ارجاع قوی، یک ارجاع امانتی برمی‌گرداند.

توجه

در ساخت‌ نخ‌آزاد، ارجاع امانتی بازگردانده‌شده ممکن است در صورت تغییر هم‌زمان فهرست توسط نخ دیگر، نامعتبر شود. بهتر است از PyList_GetItemRef() استفاده کنید که یک ارجاع قوی برمی‌گرداند.

PyObject *PyList_GET_ITEM(PyObject *list, Py_ssize_t i)

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

مشابه PyList_GetItem()، اما بدون بررسی خطا.

توجه

در ساخت‌ نخ‌آزاد، ارجاع امانتی بازگردانده‌شده ممکن است در صورت تغییر هم‌زمان فهرست توسط نخ دیگر، نامعتبر شود. بهتر است از PyList_GetItemRef() استفاده کنید که یک ارجاع قوی برمی‌گرداند.

int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)

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

آیتم موجود در اندیس index در فهرست را به item تنظیم می‌کند. در صورت موفقیت 0 را برمی‌گرداند. اگر index خارج از محدوده باشد، -1 را برمی‌گرداند و استثنای IndexError را برقرار می‌کند.

توجه

این تابع ارجاعی به item را «می‌دزدد»، حتی در صورت وقوع خطا. در صورت موفقیت، این تابع ارجاعی به آیتمی را که از قبل در موقعیت متأثر در فهرست بوده است، رها می‌کند (مگر آنکه NULL بوده باشد).

void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)

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

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

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

توجه

این ماکرو ارجاعی به item را «می‌دزدد» و برخلاف PyList_SetItem()، ارجاع به هیچ آیتمی که جایگزین می‌شود را دور نمی‌اندازد؛ هر ارجاعی که در جایگاه i از list باشد، نشت خواهد کرد.

توجه

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

int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)

قسمتی از ABI پایدار. Thread safety: Safe for concurrent use on the same object.

آیتم item را در جلوی اندیس index در فهرست list درج می‌کند. در صورت موفقیت 0 را برمی‌گرداند؛ در صورت عدم موفقیت -1 را برمی‌گرداند و یک استثنا تنظیم می‌کند. مشابه list.insert(index, item) است.

int PyList_Append(PyObject *list, PyObject *item)

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

شیء item را به انتهای فهرست list می‌افزاید. در صورت موفقیت 0 را برمی‌گرداند؛ در صورت ناموفق بودن، -1 را برمی‌گرداند و یک استثنا تنظیم می‌کند. مشابه list.append(item) است.

PyObject *PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)

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

فهرستی از اشیاء موجود در list را برمی‌گرداند که اشیاء بین low و high را در بر می‌گیرد. در صورت شکست، NULL برمی‌گرداند و یک استثنا تنظیم می‌کند. مشابه list[low:high] است. اندیس‌گذاری از انتهای فهرست پشتیبانی نمی‌شود.

int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)

قسمتی از ABI پایدار. Thread safety: Safe for concurrent use on the same object.

اسلایس list بین low و high را برابر محتویات itemlist قرار می‌دهد. مشابه list[low:high] = itemlist است. itemlist می‌تواند NULL باشد که نشان‌دهنده‌ی انتساب یک فهرست خالی است (حذف اسلایس). در صورت موفقیت 0 و در صورت شکست -1 را برمی‌گرداند. اندیس‌گذاری از انتهای فهرست پشتیبانی نمی‌شود.

توجه

در ساخت‌ نخ‌آزاد، وقتی itemlist یک list باشد، هر دو list و itemlist در طول عملیات قفل می‌شوند. برای سایر پیمایش‌پذیرها (یا NULL)، تنها list قفل می‌شود.

int PyList_Extend(PyObject *list, PyObject *iterable)

Thread safety: Safe for concurrent use on the same object.

list را با محتویات iterable گسترش می‌دهد. این همان PyList_SetSlice(list, PY_SSIZE_T_MAX, PY_SSIZE_T_MAX, iterable) است و مشابه list.extend(iterable) یا list += iterable است.

اگر list یک شیء list نباشد، استثنا ایجاد می‌کند و -1 را برمی‌گرداند. در صورت موفقیت ۰ را برمی‌گرداند.

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

توجه

در free-threaded build، وقتی iterable یک list، set، dict یا نمای دیکشنری باشد، هم list و هم iterable (یا دیکشنری زیربنایی آن) برای مدت‌زمان عملیات قفل می‌شوند. برای سایر پیمایش‌پذیرها، تنها list قفل می‌شود؛ iterable ممکن است به‌طور هم‌زمان توسط نخ دیگری تغییر داده شود.

int PyList_Clear(PyObject *list)

Thread safety: Atomic.

تمام آیتم‌ها را از list حذف می‌کند. این همان PyList_SetSlice(list, 0, PY_SSIZE_T_MAX, NULL) است و مشابه list.clear() یا del list[:] است.

اگر list یک شیء list نباشد، استثنا برمی‌انگیزد و -1 را برمی‌گرداند. در صورت موفقیت 0 را برمی‌گرداند.

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

int PyList_Sort(PyObject *list)

قسمتی از ABI پایدار. Thread safety: Safe for concurrent use on the same object.

آیتم‌های list را درجا مرتب می‌کند. در صورت موفقیت 0 و در صورت شکست -1 را برمی‌گرداند. این معادل list.sort() است.

توجه

در نسخه‌ی نخ‌آزاد، مقایسه‌ی عناصر از طریق __lt__() می‌تواند کد پایتون دلخواهی اجرا کند که در این مدت قفل به‌ازای هر شیء ممکن است به‌طور موقت آزاد شود. برای نوع‌های توکار (str، int، float)، قفل در حین مقایسه آزاد نمی‌شود.

int PyList_Reverse(PyObject *list)

قسمتی از ABI پایدار. Thread safety: Safe for concurrent use on the same object.

آیتم‌های list را به‌صورت درجا معکوس می‌کند. در صورت موفقیت 0 و در صورت شکست -1 برمی‌گرداند. این معادل list.reverse() است.

PyObject *PyList_AsTuple(PyObject *list)

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

یک شیء تاپل جدید حاوی محتوای list برمی‌گرداند؛ معادل tuple(list) است.