|
1 .. highlightlang:: c |
|
2 |
|
3 .. _setobjects: |
|
4 |
|
5 Set 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 |
|
17 This section details the public API for :class:`set` and :class:`frozenset` |
|
18 objects. Any functionality not listed below is best accessed using the either |
|
19 the abstract object protocol (including :cfunc:`PyObject_CallMethod`, |
|
20 :cfunc:`PyObject_RichCompareBool`, :cfunc:`PyObject_Hash`, |
|
21 :cfunc:`PyObject_Repr`, :cfunc:`PyObject_IsTrue`, :cfunc:`PyObject_Print`, and |
|
22 :cfunc:`PyObject_GetIter`) or the abstract number protocol (including |
|
23 :cfunc:`PyNumber_And`, :cfunc:`PyNumber_Subtract`, :cfunc:`PyNumber_Or`, |
|
24 :cfunc:`PyNumber_Xor`, :cfunc:`PyNumber_InPlaceAnd`, |
|
25 :cfunc:`PyNumber_InPlaceSubtract`, :cfunc:`PyNumber_InPlaceOr`, and |
|
26 :cfunc:`PyNumber_InPlaceXor`). |
|
27 |
|
28 |
|
29 .. ctype:: PySetObject |
|
30 |
|
31 This subtype of :ctype:`PyObject` is used to hold the internal data for both |
|
32 :class:`set` and :class:`frozenset` objects. It is like a :ctype:`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 .. cvar:: PyTypeObject PySet_Type |
|
41 |
|
42 This is an instance of :ctype:`PyTypeObject` representing the Python |
|
43 :class:`set` type. |
|
44 |
|
45 |
|
46 .. cvar:: PyTypeObject PyFrozenSet_Type |
|
47 |
|
48 This is an instance of :ctype:`PyTypeObject` representing the Python |
|
49 :class:`frozenset` type. |
|
50 |
|
51 The following type check macros work on pointers to any Python object. Likewise, |
|
52 the constructor functions work with any iterable Python object. |
|
53 |
|
54 |
|
55 .. cfunction:: 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 .. cfunction:: 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 .. cfunction:: 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 .. cfunction:: 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 .. cfunction:: 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 .. cfunction:: 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 .. cfunction:: 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 |
|
107 The following functions and macros are available for instances of :class:`set` |
|
108 or :class:`frozenset` or instances of their subtypes. |
|
109 |
|
110 |
|
111 .. cfunction:: 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 |
|
120 .. cfunction:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset) |
|
121 |
|
122 Macro form of :cfunc:`PySet_Size` without error checking. |
|
123 |
|
124 |
|
125 .. cfunction:: int PySet_Contains(PyObject *anyset, PyObject *key) |
|
126 |
|
127 Return 1 if found, 0 if not found, and -1 if an error is encountered. Unlike |
|
128 the Python :meth:`__contains__` method, this function does not automatically |
|
129 convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if |
|
130 the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a |
|
131 :class:`set`, :class:`frozenset`, or an instance of a subtype. |
|
132 |
|
133 |
|
134 .. cfunction:: int PySet_Add(PyObject *set, PyObject *key) |
|
135 |
|
136 Add *key* to a :class:`set` instance. Does not apply to :class:`frozenset` |
|
137 instances. Return 0 on success or -1 on failure. Raise a :exc:`TypeError` if |
|
138 the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow. |
|
139 Raise a :exc:`SystemError` if *set* is an not an instance of :class:`set` or its |
|
140 subtype. |
|
141 |
|
142 .. versionchanged:: 2.6 |
|
143 Now works with instances of :class:`frozenset` or its subtypes. |
|
144 Like :cfunc:`PyTuple_SetItem` in that it can be used to fill-in the |
|
145 values of brand new frozensets before they are exposed to other code. |
|
146 |
|
147 The following functions are available for instances of :class:`set` or its |
|
148 subtypes but not for instances of :class:`frozenset` or its subtypes. |
|
149 |
|
150 |
|
151 .. cfunction:: int PySet_Discard(PyObject *set, PyObject *key) |
|
152 |
|
153 Return 1 if found and removed, 0 if not found (no action taken), and -1 if an |
|
154 error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a |
|
155 :exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`discard` |
|
156 method, this function does not automatically convert unhashable sets into |
|
157 temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is an not an |
|
158 instance of :class:`set` or its subtype. |
|
159 |
|
160 |
|
161 .. cfunction:: PyObject* PySet_Pop(PyObject *set) |
|
162 |
|
163 Return a new reference to an arbitrary object in the *set*, and removes the |
|
164 object from the *set*. Return *NULL* on failure. Raise :exc:`KeyError` if the |
|
165 set is empty. Raise a :exc:`SystemError` if *set* is an not an instance of |
|
166 :class:`set` or its subtype. |
|
167 |
|
168 |
|
169 .. cfunction:: int PySet_Clear(PyObject *set) |
|
170 |
|
171 Empty an existing set of all elements. |