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

В этом разделе описан публичный 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. В случае успеха возвращает новое множество, а в случае ошибки — 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__(), эта функция не преобразует автоматически нехешируемые множества во временные неизменяемые множества. Вызывает TypeError, если key не хешируется. Вызывает SystemError, если anyset не является объектом set, frozenset или экземпляром подтипа одного из них.

int PySet_Add(PyObject *set, PyObject *key)

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

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

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

int PySet_Discard(PyObject *set, PyObject *key)

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

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

PyObject *PySet_Pop(PyObject *set)

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

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

int PySet_Clear(PyObject *set)

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

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