1 .. highlightlang:: c 2 3 .. _setobjects: 4 5 Set Objects 6 ----------- 7 8 .. sectionauthor:: Raymond D. Hettinger <python (a] rcn.com> 9 10 11 .. index:: 12 object: set 13 object: frozenset 14 15 This section details the public API for :class:`set` and :class:`frozenset` 16 objects. Any functionality not listed below is best accessed using the either 17 the 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 49 The following type check macros work on pointers to any Python object. Likewise, 50 the 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 57 .. c:function:: int PyFrozenSet_Check(PyObject *p) 58 59 Return true if *p* is a :class:`frozenset` object or an instance of a 60 subtype. 61 62 .. c:function:: int PyAnySet_Check(PyObject *p) 63 64 Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an 65 instance of a subtype. 66 67 68 .. c:function:: int PyAnySet_CheckExact(PyObject *p) 69 70 Return true if *p* is a :class:`set` object or a :class:`frozenset` object but 71 not an instance of a subtype. 72 73 74 .. c:function:: int PyFrozenSet_CheckExact(PyObject *p) 75 76 Return true if *p* is a :class:`frozenset` object but not an instance of a 77 subtype. 78 79 80 .. c:function:: PyObject* PySet_New(PyObject *iterable) 81 82 Return a new :class:`set` containing objects returned by the *iterable*. The 83 *iterable* may be *NULL* to create a new empty set. Return the new set on 84 success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is not 85 actually iterable. The constructor is also useful for copying a set 86 (``c=set(s)``). 87 88 89 .. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable) 90 91 Return a new :class:`frozenset` containing objects returned by the *iterable*. 92 The *iterable* may be *NULL* to create a new empty frozenset. Return the new 93 set on success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is 94 not actually iterable. 95 96 97 The following functions and macros are available for instances of :class:`set` 98 or :class:`frozenset` or instances of their subtypes. 99 100 101 .. c:function:: Py_ssize_t PySet_Size(PyObject *anyset) 102 103 .. index:: builtin: len 104 105 Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to 106 ``len(anyset)``. Raises a :exc:`PyExc_SystemError` if *anyset* is not a 107 :class:`set`, :class:`frozenset`, or an instance of a subtype. 108 109 110 .. c:function:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset) 111 112 Macro form of :c:func:`PySet_Size` without error checking. 113 114 115 .. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key) 116 117 Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered. Unlike 118 the Python :meth:`__contains__` method, this function does not automatically 119 convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if 120 the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a 121 :class:`set`, :class:`frozenset`, or an instance of a subtype. 122 123 124 .. c:function:: int PySet_Add(PyObject *set, PyObject *key) 125 126 Add *key* to a :class:`set` instance. Also works with :class:`frozenset` 127 instances (like :c:func:`PyTuple_SetItem` it can be used to fill-in the values 128 of brand new frozensets before they are exposed to other code). Return ``0`` on 129 success or ``-1`` on failure. Raise a :exc:`TypeError` if the *key* is 130 unhashable. Raise a :exc:`MemoryError` if there is no room to grow. Raise a 131 :exc:`SystemError` if *set* is not an instance of :class:`set` or its 132 subtype. 133 134 135 The following functions are available for instances of :class:`set` or its 136 subtypes but not for instances of :class:`frozenset` or its subtypes. 137 138 139 .. c:function:: int PySet_Discard(PyObject *set, PyObject *key) 140 141 Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an 142 error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a 143 :exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~set.discard` 144 method, this function does not automatically convert unhashable sets into 145 temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is not an 146 instance of :class:`set` or its subtype. 147 148 149 .. c:function:: PyObject* PySet_Pop(PyObject *set) 150 151 Return a new reference to an arbitrary object in the *set*, and removes the 152 object from the *set*. Return *NULL* on failure. Raise :exc:`KeyError` if the 153 set is empty. Raise a :exc:`SystemError` if *set* is not an instance of 154 :class:`set` or its subtype. 155 156 157 .. c:function:: int PySet_Clear(PyObject *set) 158 159 Empty an existing set of all elements. 160 161 162 .. c:function:: int PySet_ClearFreeList() 163 164 Clear the free list. Return the total number of freed items. 165 166 .. versionadded:: 3.3 167
