Debian Codegraph @

Doc/c-api/set.rst

raw
1 .. highlight:: c
2
3 .. _setobjects:
4
5 Set Objects
6 -----------
7
8 .. sectionauthor:: Raymond D. Hettinger <[email protected]>
9
10
11 .. index::
12 pair: object; set
13 pair: 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 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 all 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 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 .. note::
96
97 The operation is atomic on :term:`free threading <free-threaded build>`
98 when *iterable* is a :class:`set`, :class:`frozenset` or :class:`dict`.
99
100
101 .. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable)
102
103 Return a new :class:`frozenset` containing objects returned by the *iterable*.
104 The *iterable* may be ``NULL`` to create a new empty frozenset. Return the new
105 set on success or ``NULL`` on failure. Raise :exc:`TypeError` if *iterable* is
106 not actually iterable.
107
108 .. note::
109
110 The operation is atomic on :term:`free threading <free-threaded build>`
111 when *iterable* is a :class:`set`, :class:`frozenset` or :class:`dict`.
112
113
114 The following functions and macros are available for instances of :class:`set`
115 or :class:`frozenset` or instances of their subtypes.
116
117
118 .. c:function:: Py_ssize_t PySet_Size(PyObject *anyset)
119
120 .. index:: pair: built-in function; len
121
122 Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
123 ``len(anyset)``. Raises a :exc:`SystemError` if *anyset* is not a
124 :class:`set`, :class:`frozenset`, or an instance of a subtype.
125
126
127 .. c:function:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
128
129 Macro form of :c:func:`PySet_Size` without error checking.
130
131
132 .. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key)
133
134 Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered. Unlike
135 the Python :meth:`~object.__contains__` method, this function does not automatically
136 convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if
137 the *key* is unhashable. Raise :exc:`SystemError` if *anyset* is not a
138 :class:`set`, :class:`frozenset`, or an instance of a subtype.
139
140 .. note::
141
142 The operation is atomic on :term:`free threading <free-threaded build>`
143 when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
144
145 .. c:function:: int PySet_Add(PyObject *set, PyObject *key)
146
147 Add *key* to a :class:`set` instance. Also works with :class:`frozenset`
148 instances (like :c:func:`PyTuple_SetItem` it can be used to fill in the values
149 of brand new frozensets before they are exposed to other code). Return ``0`` on
150 success or ``-1`` on failure. Raise a :exc:`TypeError` if the *key* is
151 unhashable. Raise a :exc:`MemoryError` if there is no room to grow. Raise a
152 :exc:`SystemError` if *set* is not an instance of :class:`set` or its
153 subtype.
154
155 .. note::
156
157 The operation is atomic on :term:`free threading <free-threaded build>`
158 when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
159
160
161
162 The following functions are available for instances of :class:`set` or its
163 subtypes but not for instances of :class:`frozenset` or its subtypes.
164
165
166 .. c:function:: int PySet_Discard(PyObject *set, PyObject *key)
167
168 Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an
169 error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a
170 :exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~set.discard`
171 method, this function does not automatically convert unhashable sets into
172 temporary frozensets. Raise :exc:`SystemError` if *set* is not an
173 instance of :class:`set` or its subtype.
174
175 .. note::
176
177 The operation is atomic on :term:`free threading <free-threaded build>`
178 when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
179
180
181 .. c:function:: PyObject* PySet_Pop(PyObject *set)
182
183 Return a new reference to an arbitrary object in the *set*, and removes the
184 object from the *set*. Return ``NULL`` on failure. Raise :exc:`KeyError` if the
185 set is empty. Raise a :exc:`SystemError` if *set* is not an instance of
186 :class:`set` or its subtype.
187
188
189 .. c:function:: int PySet_Clear(PyObject *set)
190
191 Empty an existing set of all elements. Return ``0`` on
192 success. Return ``-1`` and raise :exc:`SystemError` if *set* is not an instance of
193 :class:`set` or its subtype.
194
195 .. note::
196
197 In the :term:`free-threaded build`, the set is emptied before its entries
198 are cleared, so other threads will observe an empty set rather than
199 intermediate states.
200
201
202 Deprecated API
203 ^^^^^^^^^^^^^^
204
205 .. c:macro:: PySet_MINSIZE
206
207 A :term:`soft deprecated` constant representing the size of an internal
208 preallocated table inside :c:type:`PySetObject` instances.
209
210 This is documented solely for completeness, as there are no guarantees
211 that a given version of CPython uses preallocated tables with a fixed
212 size.
213 In code that does not deal with unstable set internals,
214 :c:macro:`!PySet_MINSIZE` can be replaced with a small constant like ``8``.
215
216 If looking for the size of a set, use :c:func:`PySet_Size` instead.