1.. highlight:: c 2 3.. _setobjects: 4 5Set Objects 6----------- 7 8.. sectionauthor:: Raymond D. Hettinger <python@rcn.com> 9 10 11.. index:: 12 object: set 13 object: frozenset 14 15This section details the public API for :class:`set` and :class:`frozenset` 16objects. Any functionality not listed below is best accessed using the either 17the abstract object protocol (including :c:func:`PyObject_CallMethod`, 18:c:func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`, 19:c:func:`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and 20:c:func:`PyObject_GetIter`) or the abstract number protocol (including 21:c:func:`PyNumber_And`, :c:func:`PyNumber_Subtract`, :c:func:`PyNumber_Or`, 22:c:func:`PyNumber_Xor`, :c:func:`PyNumber_InPlaceAnd`, 23:c:func:`PyNumber_InPlaceSubtract`, :c:func:`PyNumber_InPlaceOr`, and 24:c:func:`PyNumber_InPlaceXor`). 25 26 27.. c:type:: PySetObject 28 29 This subtype of :c:type:`PyObject` is used to hold the internal data for both 30 :class:`set` and :class:`frozenset` objects. It is like a :c:type:`PyDictObject` 31 in that it is a fixed size for small sets (much like tuple storage) and will 32 point to a separate, variable sized block of memory for medium and large sized 33 sets (much like list storage). None of the fields of this structure should be 34 considered public and are subject to change. All access should be done through 35 the documented API rather than by manipulating the values in the structure. 36 37 38.. c:var:: PyTypeObject PySet_Type 39 40 This is an instance of :c:type:`PyTypeObject` representing the Python 41 :class:`set` type. 42 43 44.. c:var:: PyTypeObject PyFrozenSet_Type 45 46 This is an instance of :c:type:`PyTypeObject` representing the Python 47 :class:`frozenset` type. 48 49The following type check macros work on pointers to any Python object. Likewise, 50the constructor functions work with any iterable Python object. 51 52 53.. c:function:: int PySet_Check(PyObject *p) 54 55 Return true if *p* is a :class:`set` object or an instance of a subtype. 56 This function always succeeds. 57 58.. c:function:: int PyFrozenSet_Check(PyObject *p) 59 60 Return true if *p* is a :class:`frozenset` object or an instance of a 61 subtype. This function always succeeds. 62 63.. c:function:: int PyAnySet_Check(PyObject *p) 64 65 Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an 66 instance of a subtype. This function always succeeds. 67 68.. c:function:: int PySet_CheckExact(PyObject *p) 69 70 Return true if *p* is a :class:`set` object but not an instance of a 71 subtype. This function always succeeds. 72 73 .. versionadded:: 3.10 74 75.. c:function:: int PyAnySet_CheckExact(PyObject *p) 76 77 Return true if *p* is a :class:`set` object or a :class:`frozenset` object but 78 not an instance of a subtype. This function always succeeds. 79 80 81.. c:function:: int PyFrozenSet_CheckExact(PyObject *p) 82 83 Return true if *p* is a :class:`frozenset` object but not an instance of a 84 subtype. This function always succeeds. 85 86 87.. c:function:: PyObject* PySet_New(PyObject *iterable) 88 89 Return a new :class:`set` containing objects returned by the *iterable*. The 90 *iterable* may be ``NULL`` to create a new empty set. Return the new set on 91 success or ``NULL`` on failure. Raise :exc:`TypeError` if *iterable* is not 92 actually iterable. The constructor is also useful for copying a set 93 (``c=set(s)``). 94 95 96.. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable) 97 98 Return a new :class:`frozenset` containing objects returned by the *iterable*. 99 The *iterable* may be ``NULL`` to create a new empty frozenset. Return the new 100 set on success or ``NULL`` on failure. Raise :exc:`TypeError` if *iterable* is 101 not actually iterable. 102 103 104The following functions and macros are available for instances of :class:`set` 105or :class:`frozenset` or instances of their subtypes. 106 107 108.. c:function:: Py_ssize_t PySet_Size(PyObject *anyset) 109 110 .. index:: builtin: len 111 112 Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to 113 ``len(anyset)``. Raises a :exc:`PyExc_SystemError` if *anyset* is not a 114 :class:`set`, :class:`frozenset`, or an instance of a subtype. 115 116 117.. c:function:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset) 118 119 Macro form of :c:func:`PySet_Size` without error checking. 120 121 122.. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key) 123 124 Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered. Unlike 125 the Python :meth:`__contains__` method, this function does not automatically 126 convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if 127 the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a 128 :class:`set`, :class:`frozenset`, or an instance of a subtype. 129 130 131.. c:function:: int PySet_Add(PyObject *set, PyObject *key) 132 133 Add *key* to a :class:`set` instance. Also works with :class:`frozenset` 134 instances (like :c:func:`PyTuple_SetItem` it can be used to fill-in the values 135 of brand new frozensets before they are exposed to other code). Return ``0`` on 136 success or ``-1`` on failure. Raise a :exc:`TypeError` if the *key* is 137 unhashable. Raise a :exc:`MemoryError` if there is no room to grow. Raise a 138 :exc:`SystemError` if *set* is not an instance of :class:`set` or its 139 subtype. 140 141 142The following functions are available for instances of :class:`set` or its 143subtypes but not for instances of :class:`frozenset` or its subtypes. 144 145 146.. c:function:: int PySet_Discard(PyObject *set, PyObject *key) 147 148 Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an 149 error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a 150 :exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~set.discard` 151 method, this function does not automatically convert unhashable sets into 152 temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is not an 153 instance of :class:`set` or its subtype. 154 155 156.. c:function:: PyObject* PySet_Pop(PyObject *set) 157 158 Return a new reference to an arbitrary object in the *set*, and removes the 159 object from the *set*. Return ``NULL`` on failure. Raise :exc:`KeyError` if the 160 set is empty. Raise a :exc:`SystemError` if *set* is not an instance of 161 :class:`set` or its subtype. 162 163 164.. c:function:: int PySet_Clear(PyObject *set) 165 166 Empty an existing set of all elements. 167