اشیاء مجموعه

این بخش API عمومی اشیاء set و frozenset را با جزئیات شرح می‌دهد. بهترین راه دسترسی به هر قابلیتی که در ادامه فهرست نشده است، استفاده از پروتکل انتزاعی شیء (شامل PyObject_CallMethod()، PyObject_RichCompareBool()، PyObject_Hash()، PyObject_Repr()، PyObject_IsTrue()، PyObject_Print() و PyObject_GetIter()) یا پروتکل انتزاعی عدد (شامل PyNumber_And()، PyNumber_Subtract()، PyNumber_Or()، PyNumber_Xor()، PyNumber_InPlaceAnd()، PyNumber_InPlaceSubtract()، PyNumber_InPlaceOr() و PyNumber_InPlaceXor()) است.

type PySetObject

این زیرنوع از PyObject برای نگه‌داشتن داده‌های داخلی هر دو نوع شیء set و frozenset استفاده می‌شود. این زیرنوع مانند PyDictObject است از این جهت که برای مجموعه‌های کوچک اندازه‌ای ثابت دارد (بسیار شبیه ذخیره‌سازی تاپل) و برای مجموعه‌های متوسط و بزرگ به یک بلوک حافظه‌ی جداگانه با اندازه متغیر اشاره می‌کند (بسیار شبیه ذخیره‌سازی فهرست). هیچ‌یک از فیلدهای این ساختار نباید عمومی در نظر گرفته شود و همه آن‌ها ممکن است تغییر کنند. تمام دسترسی‌ها باید از طریق API مستندشده انجام شود، نه با دستکاری مقادیر درون ساختار.

PyTypeObject PySet_Type

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

این یک نمونه از PyTypeObject است که نوع set پایتون را نشان می‌دهد.

PyTypeObject PyFrozenSet_Type

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

این یک نمونه از PyTypeObject است که نوع frozenset پایتون را نشان می‌دهد.

ماکروهای بررسی نوع زیر روی اشاره‌گر به هر شیء پایتونی کار می‌کنند. به همین ترتیب، توابع سازنده با هر شیء پیمایش‌پذیر پایتونی کار می‌کنند.

int PySet_Check(PyObject *p)

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

int PyFrozenSet_Check(PyObject *p)

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

int PyAnySet_Check(PyObject *p)

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

int PySet_CheckExact(PyObject *p)

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

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

int PyAnySet_CheckExact(PyObject *p)

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

int PyFrozenSet_CheckExact(PyObject *p)

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

PyObject *PySet_New(PyObject *iterable)

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

یک set جدید شامل اشیاء بازگردانده‌شده توسط iterable برمی‌گرداند. iterable می‌تواند NULL باشد تا یک مجموعه‌ی خالی جدید ایجاد شود. در صورت موفقیت مجموعه‌ی جدید و در صورت شکست NULL برمی‌گرداند. اگر iterable در واقع پیمایش‌پذیر نباشد، استثنای TypeError ایجاد می‌شود. این سازنده برای کپی‌کردن یک مجموعه نیز مفید است (c=set(s)).

توجه

این عملیات در نخ‌بندی آزاد زمانی اتمی است که iterable یک set، frozenset یا dict باشد.

PyObject *PyFrozenSet_New(PyObject *iterable)

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

یک frozenset جدید شامل اشیایی که توسط iterable برگردانده می‌شوند را برمی‌گرداند. iterable می‌تواند NULL باشد تا یک frozenset خالی جدید ایجاد شود. در صورت موفقیت، مجموعه جدید و در صورت شکست، NULL برگردانده می‌شود. اگر iterable در واقع پیمایش‌پذیر نباشد، TypeError ایجاد می‌شود.

توجه

این عملیات در نخ‌بندی آزاد زمانی اتمی است که iterable یک set، frozenset یا dict باشد.

توابع و ماکروهای زیر برای نمونه‌های set یا frozenset یا نمونه‌های زیرنوع‌های آن‌ها در دسترس هستند.

Py_ssize_t PySet_Size(PyObject *anyset)

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

طول یک شیء set یا frozenset را برمی‌گرداند. معادل len(anyset) است. اگر anyset یک set، frozenset یا نمونه‌ای از یک زیرنوع نباشد، استثنای SystemError ایجاد می‌کند.

Py_ssize_t PySet_GET_SIZE(PyObject *anyset)

Thread safety: Atomic.

شکل ماکروی PySet_Size() بدون بررسی خطا.

int PySet_Contains(PyObject *anyset, PyObject *key)

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

مقدار 1 را در صورت یافت‌شدن، 0 را در صورت یافت‌نشدن و -1 را در صورت بروز خطا برمی‌گرداند. برخلاف متد __contains__() پایتون، این تابع مجموعه‌های هش‌ناپذیر را به‌طور خودکار به frozenset‌های موقت تبدیل نمی‌کند. اگر key هش‌ناپذیر باشد، یک TypeError ایجاد می‌کند. اگر anyset یک set، frozenset یا نمونه‌ای از یک زیرنوع نباشد، SystemError ایجاد می‌کند.

توجه

این عملیات در نخ‌بندی آزاد زمانی که key از نوع str، int، float، bool یا bytes باشد، اتمیک است.

int PySet_Add(PyObject *set, PyObject *key)

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

key را به یک نمونه از set اضافه می‌کند. همچنین با نمونه‌های frozenset کار می‌کند (مانند PyTuple_SetItem()، می‌توان از آن برای پر کردن مقادیر frozenset‌های تازه‌ساخته پیش از آنکه در معرض کد دیگر قرار گیرند استفاده کرد). در صورت موفقیت 0 یا در صورت شکست -1 را برمی‌گرداند. اگر key هش‌ناپذیر باشد، TypeError ایجاد می‌شود. اگر فضایی برای رشد وجود نداشته باشد، MemoryError ایجاد می‌شود. اگر set نمونه‌ای از set یا زیرنوع آن نباشد، SystemError ایجاد می‌شود.

توجه

این عملیات در نخ‌بندی آزاد زمانی که key از نوع str، int، float، bool یا bytes باشد، اتمیک است.

توابع زیر برای نمونه‌های set یا زیرنوع‌های آن در دسترس هستند، اما برای نمونه‌های frozenset یا زیرنوع‌های آن در دسترس نیستند.

int PySet_Discard(PyObject *set, PyObject *key)

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

اگر یافته و حذف شود، 1؛ اگر یافت نشود (هیچ عملی انجام نمی‌شود)، 0؛ و اگر با خطایی مواجه شود، -1 برمی‌گرداند. استثنای KeyError را برای کلیدهای مفقود ایجاد نمی‌کند. اگر key هش‌ناپذیر باشد، استثنای TypeError ایجاد می‌کند. برخلاف متد discard() در پایتون، این تابع مجموعه‌های هش‌ناپذیر را به‌طور خودکار به frozenset‌های موقت تبدیل نمی‌کند. اگر set نمونه‌ای از set یا زیرنوع آن نباشد، استثنای SystemError ایجاد می‌کند.

توجه

این عملیات در نخ‌بندی آزاد زمانی که key از نوع str، int، float، bool یا bytes باشد، اتمیک است.

PyObject *PySet_Pop(PyObject *set)

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

یک ارجاع جدید به یک شیء دلخواه در set برمی‌گرداند و آن شیء را از set حذف می‌کند. در صورت شکست NULL را برمی‌گرداند. اگر مجموعه خالی باشد، استثنای KeyError ایجاد می‌شود. اگر set نمونه‌ای از set یا زیرنوع آن نباشد، استثنای SystemError ایجاد می‌شود.

int PySet_Clear(PyObject *set)

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

یک مجموعه‌ی موجود را از تمام عناصرش خالی می‌کند. در صورت موفقیت 0 را برمی‌گرداند. اگر set نمونه‌ای از set یا زیرنوع آن نباشد، -1 را برمی‌گرداند و استثنای SystemError را ایجاد می‌کند.

توجه

در free-threaded build، مجموعه پیش از پاک شدن ورودی‌هایش خالی می‌شود، بنابراین نخ‌های دیگر به‌جای وضعیت‌های میانی، مجموعه‌ای خالی را مشاهده خواهند کرد.

API منسوخ

PySet_MINSIZE

ثابتی که نشان‌دهنده‌ی اندازه‌ی جدول داخلی پیش‌تخصیص‌شده درون نمونه‌های PySetObject است.

این مورد صرفاً برای کامل بودن مستند شده است، زیرا هیچ تضمینی وجود ندارد که نسخه‌ی خاصی از سی‌پایتون از جدول‌های پیش‌تخصیص‌شده با اندازه‌ی ثابت استفاده کند. در کدی که با جزئیات داخلی ناپایدار مجموعه سروکار ندارد، می‌توان PySet_MINSIZE را با یک ثابت کوچک مانند 8 جایگزین کرد.

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

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