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

В этом разделе подробно описан общедоступный 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. Если iterable на самом деле не является итерируемым объектом, вызывает исключение TypeError. Конструктор также удобно использовать для копирования множества (c=set(s)).

PyObject *PyFrozenSet_New(PyObject *iterable)

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

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

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

Py_ssize_t PySet_Size(PyObject *anyset)

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

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

Py_ssize_t PySet_GET_SIZE(PyObject *anyset)

Форма макроса для PySet_Size() без проверки ошибок.

int PySet_Contains(PyObject *anyset, PyObject *key)

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

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

int PySet_Add(PyObject *set, PyObject *key)

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

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

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

int PySet_Discard(PyObject *set, PyObject *key)

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

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

PyObject *PySet_Pop(PyObject *set)

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

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

int PySet_Clear(PyObject *set)

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

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