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

В этом разделе подробно описан публичный 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)

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

int PyFrozenSet_Check(PyObject *p)

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

int PyAnySet_Check(PyObject *p)

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

int PySet_CheckExact(PyObject *p)

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

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

int PyAnySet_CheckExact(PyObject *p)

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

int PyFrozenSet_CheckExact(PyObject *p)

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

PyObject *PySet_New(PyObject *iterable)

Возвращаемое значение: новая ссылка.Входит в стабильный ABI.Потокобезопасность: безопасно для одновременного использования с одним и тем же объектом.

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

Примечание

Операция атомарна при свободной многопоточности, если iterable — это set, frozenset или dict.

PyObject *PyFrozenSet_New(PyObject *iterable)

Возвращаемое значение: новая ссылка.Входит в стабильный ABI.Потокобезопасность: безопасно для одновременного использования с одним и тем же объектом.

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

Примечание

Операция атомарна при свободной многопоточности, если iterable — это set, frozenset или dict.

Следующие функции и макросы доступны для экземпляров 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 или экземпляром подтипа.

Примечание

Операция атомарна при свободной многопоточности, если key — это str, int, float, bool или bytes.

int PySet_Add(PyObject *set, PyObject *key)

Входит в стабильный ABI.Потокобезопасность: безопасно для одновременного использования с одним и тем же объектом.

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

Примечание

Операция атомарна при свободной многопоточности, если key — это str, int, float, bool или bytes.

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

int PySet_Discard(PyObject *set, PyObject *key)

Входит в стабильный ABI.Потокобезопасность: безопасно для одновременного использования с одним и тем же объектом.

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

Примечание

Операция атомарна при свободной многопоточности, если key — это str, int, float, bool или bytes.

PyObject *PySet_Pop(PyObject *set)

Возвращаемое значение: новая ссылка.Входит в стабильный ABI.Потокобезопасность: атомарная операция.

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

int PySet_Clear(PyObject *set)

Входит в стабильный ABI.Потокобезопасность: атомарная операция.

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

Примечание

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