Объекты множеств

В этом разделе подробно описывается общедоступный 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, представляющий тип Python set.

PyTypeObject PyFrozenSet_Type

Часть Стабильной ABI.

Это экземпляр PyTypeObject, представляющий тип Python frozenset.

Следующие макросы проверки типа работают с указателями на любые объекты Python. Аналогично, функции-конструкторы работают с любыми итерируемыми объектами Python.

int PySet_Check(PyObject *p)

Возвращает true, если p — объект set или экземпляр подтипа. Эта функция всегда выполняется успешно.

int PyFrozenSet_Check(PyObject *p)

Возвращает true, если p — объект frozenset или экземпляр подтипа. Эта функция всегда выполняется успешно.

int PyAnySet_Check(PyObject *p)

Возвращает true, если p — объект set, frozenset или экземпляр подтипа. Эта функция всегда выполняется успешно.

int PySet_CheckExact(PyObject *p)

Возвращает true, если p — объект set, но не экземпляр подтипа. Эта функция всегда выполняется успешно.

Добавлен в версии 3.10.

int PyAnySet_CheckExact(PyObject *p)

Возвращает true, если p — объект set или frozenset, но не экземпляр подтипа. Эта функция всегда выполняется успешно.

int PyFrozenSet_CheckExact(PyObject *p)

Возвращает true, если p — объект frozenset, но не экземпляр подтипа. Эта функция всегда выполняется успешно.

PyObject *PySet_New(PyObject *iterable)

Возвращаемое значение: новая ссылка. Часть Стабильной ABI.

Возвращает новый set, содержащий объекты, возвращаемые итерируемым iterable. iterable может быть NULL для создания нового пустого множества. Возвращает новое множество при успехе или NULL при неудаче. Вызывает TypeError, если iterable не является итерируемым. Конструктор также полезен для копирования множества (c=set(s)).

PyObject *PyFrozenSet_New(PyObject *iterable)

Возвращаемое значение: новая ссылка. Часть Стабильной ABI.

Возвращает новое frozenset, содержащий объекты, возвращаемые итерируемым iterable. iterable может быть NULL для создания нового пустого frozenset. Возвращает новое множество при успехе или NULL при неудаче. Вызывает TypeError, если iterable не является итерируемым.

Следующие функции и макросы доступны для экземпляров set или frozenset или экземпляров их подтипов.

Py_ssize_t PySet_Size(PyObject *anyset)

Часть Стабильной ABI.

Возвращает длину объекта set или frozenset. Эквивалентно len(anyset). Вызывает SystemError, если anyset не является объектом set, frozenset или экземпляром подтипа.

Py_ssize_t PySet_GET_SIZE(PyObject *anyset)

Макрос PySet_Size() без проверки ошибок.

int PySet_Contains(PyObject *anyset, PyObject *key)

Часть Стабильной ABI.

Возвращает 1 если найдено, 0 если не найдено, и -1 если произошла ошибка. В отличие от метода Python __contains__(), эта функция не автоматически преобразует нехешируемые множества в временные frozenset. Вызывает TypeError, если key не хешируется. Вызывает SystemError, если anyset не является объектом set, frozenset или экземпляром подтипа.

int PySet_Add(PyObject *set, PyObject *key)

Часть Стабильной ABI.

Добавляет ключ в экземпляр множества. Также работает с экземплярами frozenset (как и PyTuple_SetItem(), он может использоваться для заполнения значений новых фрозетов перед их экспонированием другому коду). Возвращает 0 при успехе или -1 при неудаче. Возбуждает TypeError, если ключ не хешируется. Возбуждает MemoryError, если нет места для роста. Возбуждает SystemError, если множество не является экземпляром множества или его подтипа.

Следующие функции доступны для экземпляров множества или его подтипов, но не для экземпляров frozenset или его подтипов.

int PySet_Discard(PyObject *set, PyObject *key)

Часть Стабильной ABI.

Возвращает 1 если найден и удалён, 0 если не найден (никаких действий не выполнено), и -1 если возникла ошибка. Не возбуждает KeyError для отсутствующих ключей. Возбуждает TypeError, если ключ не хешируется. В отличие от метода Python discard(), эта функция не автоматически преобразует нехешируемые множества во временные фрожены. Возбуждает SystemError, если множество не является экземпляром множества или его подтипа.

PyObject *PySet_Pop(PyObject *set)

Возвращаемое значение: Новая ссылка. Часть Стабильной ABI.

Возвращает новую ссылку на произвольный объект в множестве и удаляет объект из множества. Возвращает NULL при неудаче. Возбуждает KeyError, если множество пусто. Возбуждает SystemError, если множество не является экземпляром множества или его подтипа.

int PySet_Clear(PyObject *set)

Часть Стабильной ABI.

Очищает существующее множество от всех элементов. Возвращает 0 при успехе. Возвращает -1 и возбуждает SystemError, если множество не является экземпляром множества или его подтипа.