پروتکل دنباله¶

int PySequence_Check(PyObject *o)¶

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

اگر شیء پروتکل دنباله را فراهم کند، 1 را برمی‌گرداند و در غیر این صورت 0. توجه داشته باشید که این تابع برای کلاس‌های پایتونی که متد __getitem__() دارند 1 برمی‌گرداند، مگر آنکه زیرکلاس‌های dict باشند، زیرا به‌طور کلی غیرممکن است تعیین کرد که کلاس از چه نوع کلیدهایی پشتیبانی می‌کند. این تابع همیشه موفق می‌شود.

Py_ssize_t PySequence_Size(PyObject *o)¶

Py_ssize_t PySequence_Length(PyObject *o)¶

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

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

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

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

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

PyObject *PySequence_Repeat(PyObject *o, Py_ssize_t count)¶

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

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

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

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

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

PyObject *PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)¶

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

نتیجه‌ی تکرار شیء دنباله o به تعداد count بار را برمی‌گرداند، یا در صورت شکست NULL. این عملیات هنگامی که o از آن پشتیبانی کند، به‌صورت درجا (in-place) انجام می‌شود. این معادل عبارت پایتونی o *= count است.

PyObject *PySequence_GetItem(PyObject *o, Py_ssize_t i)¶

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

عنصر iاُم از o را برمی‌گرداند، یا در صورت شکست NULL. این معادل عبارت پایتونی o[i] است.

PyObject *PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)¶

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

اسلایس شیء دنباله o بین i1 و i2 را برمی‌گرداند، یا در صورت شکست NULL. این معادل عبارت پایتونی o[i1:i2] است.

int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)¶

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

شیء v را به عنصر iام از o اختصاص می‌دهد. در صورت شکست، یک استثنا مطرح می‌کند و -1 را برمی‌گرداند؛ در صورت موفقیت 0 را برمی‌گرداند. این معادل دستور پایتونی o[i] = v است. این تابع ارجاعی به v را "steal" نمی‌کند.

اگر v برابر NULL باشد، المان حذف می‌شود، اما این قابلیت منسوخ شده و به‌جای آن استفاده از PySequence_DelItem() توصیه می‌شود.

int PySequence_DelItem(PyObject *o, Py_ssize_t i)¶

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

عنصر iاُم از شیء o را حذف می‌کند. در صورت شکست -1 برمی‌گرداند. این معادل دستور پایتون del o[i] است.

int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)¶

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

شیء دنباله v را به اسلایس موجود در شیء دنباله o از i1 تا i2 منتسب کنید. این معادل دستور پایتونی o[i1:i2] = v است.

int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)¶

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

اسلایس موجود در شیء دنباله o را از i1 تا i2 حذف می‌کند. در صورت شکست، -1 برمی‌گرداند. این معادل دستور پایتون del o[i1:i2] است.

Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)¶

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

تعداد رخدادهای value در o را بازمی‌گرداند؛ یعنی تعداد کلیدهایی که o[key] == value باشد را بازمی‌گرداند. در صورت شکست، -1 بازمی‌گرداند. این معادل عبارت پایتونی o.count(value) است.

int PySequence_Contains(PyObject *o, PyObject *value)¶

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

بررسی می‌کند که آیا o شامل value است. اگر آیتمی در o برابر با value باشد، 1 و در غیر این صورت 0 برگردانده می‌شود. در صورت خطا، -1 برگردانده می‌شود. این معادل عبارت پایتونی value in o است.

int PySequence_In(PyObject *o, PyObject *value)¶

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

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

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.14: این تابع نباید دیگر برای نوشتن کد جدید استفاده شود.

Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)¶

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

اولین اندیس i را که o[i] == value باشد برمی‌گرداند. در صورت خطا، -1 را برمی‌گرداند. این معادل عبارت پایتونی o.index(value) است.

PyObject *PySequence_List(PyObject *o)¶

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

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

PyObject *PySequence_Tuple(PyObject *o)¶

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

یک شیء تاپل با همان محتوای دنباله یا پیمایش‌پذیر o برمی‌گرداند، یا در صورت شکست NULL برمی‌گرداند. اگر o یک تاپل باشد، یک ارجاع جدید بازگردانده می‌شود؛ در غیر این صورت، تاپلی با محتوای مناسب ساخته می‌شود. این معادل عبارت پایتونی tuple(o) است.

PyObject *PySequence_Fast(PyObject *o, const char *m)¶

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

دنباله یا پیمایش‌پذیر o را به‌صورت شیء‌ای قابل استفاده توسط سایر توابع خانواده PySequence_Fast* برمی‌گرداند. اگر شیء یک دنباله یا پیمایش‌پذیر نباشد، استثنای TypeError را با m به‌عنوان متن پیام ایجاد می‌کند. در صورت شکست، NULL برمی‌گرداند.

توابع PySequence_Fast* به این دلیل چنین نام‌گذاری شده‌اند که فرض می‌کنند o یک PyTupleObject یا PyListObject است و مستقیماً به فیلدهای داده‌ی o دسترسی دارند.

به عنوان یک جزئیات از پیاده‌سازی سی‌پایتون، اگر o از قبل یک دنباله یا فهرست باشد، همان بازگردانده خواهد شد.

Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)¶

طول o را برمی‌گرداند، با این فرض که o توسط PySequence_Fast() برگردانده‌شده و o برابر NULL نیست. اندازه را می‌توان با فراخوانی PySequence_Size() روی o نیز بازیابی کرد، اما PySequence_Fast_GET_SIZE() سریع‌تر است زیرا می‌تواند فرض کند o یک فهرست یا تاپل است.

PyObject *PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)¶

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

بازگرداندن عنصر iام از o، با این فرض که o توسط PySequence_Fast() بازگردانده شده باشد، o برابر NULL نباشد و i در محدوده باشد.

PyObject **PySequence_Fast_ITEMS(PyObject *o)¶

آرایه‌ی زیربنایی اشاره‌گرهای PyObject را برمی‌گرداند. فرض می‌کند که o توسط PySequence_Fast() برگردانده شده باشد و o برابر NULL نباشد.

توجه داشته باشید که اگر اندازه‌ی یک فهرست تغییر کند، تخصیص مجدد ممکن است آرایه‌ی آیتم‌ها را جابه‌جا کند. بنابراین، اشاره‌گر آرایه‌ی زیرین را تنها در زمینه‌هایی استفاده کنید که دنباله در آن‌ها نمی‌تواند تغییر کند.

PyObject *PySequence_ITEM(PyObject *o, Py_ssize_t i)¶

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

عنصر i-ام از o یا در صورت شکست NULL را برمی‌گرداند. شکل سریع‌تری از PySequence_GetItem() است، اما بدون بررسی اینکه PySequence_Check() روی o درست باشد و بدون تعدیل اندیس‌های منفی.