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