Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/set.rst @ 79675:c0a2294de787 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16199: Backport 2to3 typo fix from 3.2.
author Chris Jerdonek <chris.jerdonek@gmail.com>
date Thu, 11 Oct 2012 16:15:46 -0700
parents 74ff71b2f53d
children 9b855a701e28
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _setobjects:
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 Set Objects
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 -----------
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. sectionauthor:: Raymond D. Hettinger <python@rcn.com>
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
9
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 .. index::
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 object: set
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 object: frozenset
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
14
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 .. versionadded:: 2.5
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 This section details the public API for :class:`set` and :class:`frozenset`
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 objects. Any functionality not listed below is best accessed using the either
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
19 the abstract object protocol (including :c:func:`PyObject_CallMethod`,
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
20 :c:func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`,
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
21 :c:func:`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
22 :c:func:`PyObject_GetIter`) or the abstract number protocol (including
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
23 :c:func:`PyNumber_And`, :c:func:`PyNumber_Subtract`, :c:func:`PyNumber_Or`,
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
24 :c:func:`PyNumber_Xor`, :c:func:`PyNumber_InPlaceAnd`,
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
25 :c:func:`PyNumber_InPlaceSubtract`, :c:func:`PyNumber_InPlaceOr`, and
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
26 :c:func:`PyNumber_InPlaceXor`).
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
27
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
28
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
29 .. c:type:: PySetObject
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
30
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
31 This subtype of :c:type:`PyObject` is used to hold the internal data for both
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
32 :class:`set` and :class:`frozenset` objects. It is like a :c:type:`PyDictObject`
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 in that it is a fixed size for small sets (much like tuple storage) and will
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 point to a separate, variable sized block of memory for medium and large sized
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 sets (much like list storage). None of the fields of this structure should be
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 considered public and are subject to change. All access should be done through
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 the documented API rather than by manipulating the values in the structure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
39
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
40 .. c:var:: PyTypeObject PySet_Type
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
41
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
42 This is an instance of :c:type:`PyTypeObject` representing the Python
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
43 :class:`set` type.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
44
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
45
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
46 .. c:var:: PyTypeObject PyFrozenSet_Type
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
47
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
48 This is an instance of :c:type:`PyTypeObject` representing the Python
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 :class:`frozenset` type.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
50
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
51 The following type check macros work on pointers to any Python object. Likewise,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 the constructor functions work with any iterable Python object.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
53
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
54
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
55 .. c:function:: int PySet_Check(PyObject *p)
45038
756413c0ff1d Factor-out common code with a new macro
Raymond Hettinger <python@rcn.com>
parents: 45035
diff changeset
56
756413c0ff1d Factor-out common code with a new macro
Raymond Hettinger <python@rcn.com>
parents: 45035
diff changeset
57 Return true if *p* is a :class:`set` object or an instance of a subtype.
756413c0ff1d Factor-out common code with a new macro
Raymond Hettinger <python@rcn.com>
parents: 45035
diff changeset
58
756413c0ff1d Factor-out common code with a new macro
Raymond Hettinger <python@rcn.com>
parents: 45035
diff changeset
59 .. versionadded:: 2.6
756413c0ff1d Factor-out common code with a new macro
Raymond Hettinger <python@rcn.com>
parents: 45035
diff changeset
60
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
61 .. c:function:: int PyFrozenSet_Check(PyObject *p)
45138
4f6f44bc5195 Ensure that PySet_Add() operates on a newly created frozenset, like PyTuple_SetItem does.
Amaury Forgeot d'Arc <amauryfa@gmail.com>
parents: 45038
diff changeset
62
4f6f44bc5195 Ensure that PySet_Add() operates on a newly created frozenset, like PyTuple_SetItem does.
Amaury Forgeot d'Arc <amauryfa@gmail.com>
parents: 45038
diff changeset
63 Return true if *p* is a :class:`frozenset` object or an instance of a
4f6f44bc5195 Ensure that PySet_Add() operates on a newly created frozenset, like PyTuple_SetItem does.
Amaury Forgeot d'Arc <amauryfa@gmail.com>
parents: 45038
diff changeset
64 subtype.
4f6f44bc5195 Ensure that PySet_Add() operates on a newly created frozenset, like PyTuple_SetItem does.
Amaury Forgeot d'Arc <amauryfa@gmail.com>
parents: 45038
diff changeset
65
4f6f44bc5195 Ensure that PySet_Add() operates on a newly created frozenset, like PyTuple_SetItem does.
Amaury Forgeot d'Arc <amauryfa@gmail.com>
parents: 45038
diff changeset
66 .. versionadded:: 2.6
4f6f44bc5195 Ensure that PySet_Add() operates on a newly created frozenset, like PyTuple_SetItem does.
Amaury Forgeot d'Arc <amauryfa@gmail.com>
parents: 45038
diff changeset
67
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
68 .. c:function:: int PyAnySet_Check(PyObject *p)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
69
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
70 Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
71 instance of a subtype.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
72
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
73
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
74 .. c:function:: int PyAnySet_CheckExact(PyObject *p)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
75
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 Return true if *p* is a :class:`set` object or a :class:`frozenset` object but
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 not an instance of a subtype.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
78
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
79
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
80 .. c:function:: int PyFrozenSet_CheckExact(PyObject *p)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
81
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 Return true if *p* is a :class:`frozenset` object but not an instance of a
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 subtype.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
84
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
85
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
86 .. c:function:: PyObject* PySet_New(PyObject *iterable)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
87
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 Return a new :class:`set` containing objects returned by the *iterable*. The
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
89 *iterable* may be *NULL* to create a new empty set. Return the new set on
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is not
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 actually iterable. The constructor is also useful for copying a set
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 (``c=set(s)``).
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
93
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
94
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
95 .. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
96
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 Return a new :class:`frozenset` containing objects returned by the *iterable*.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 The *iterable* may be *NULL* to create a new empty frozenset. Return the new
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 set on success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 not actually iterable.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
101
45035
15e8b34254ec Make PySet_Add() work with frozensets.
Raymond Hettinger <python@rcn.com>
parents: 44964
diff changeset
102 .. versionchanged:: 2.6
15e8b34254ec Make PySet_Add() work with frozensets.
Raymond Hettinger <python@rcn.com>
parents: 44964
diff changeset
103 Now guaranteed to return a brand-new :class:`frozenset`. Formerly,
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 45138
diff changeset
104 frozensets of zero-length were a singleton. This got in the way of
45035
15e8b34254ec Make PySet_Add() work with frozensets.
Raymond Hettinger <python@rcn.com>
parents: 44964
diff changeset
105 building-up new frozensets with :meth:`PySet_Add`.
15e8b34254ec Make PySet_Add() work with frozensets.
Raymond Hettinger <python@rcn.com>
parents: 44964
diff changeset
106
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 The following functions and macros are available for instances of :class:`set`
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 or :class:`frozenset` or instances of their subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
109
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
110
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
111 .. c:function:: Py_ssize_t PySet_Size(PyObject *anyset)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
112
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
113 .. index:: builtin: len
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
114
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
116 ``len(anyset)``. Raises a :exc:`PyExc_SystemError` if *anyset* is not a
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
117 :class:`set`, :class:`frozenset`, or an instance of a subtype.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
118
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
119 .. versionchanged:: 2.5
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
120 This function returned an :c:type:`int`. This might require changes in
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
121 your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
122
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
123
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
124 .. c:function:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
125
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
126 Macro form of :c:func:`PySet_Size` without error checking.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
127
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
128
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
129 .. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
130
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
131 Return 1 if found, 0 if not found, and -1 if an error is encountered. Unlike
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
132 the Python :meth:`__contains__` method, this function does not automatically
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
134 the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
135 :class:`set`, :class:`frozenset`, or an instance of a subtype.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
136
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
137
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
138 .. c:function:: int PySet_Add(PyObject *set, PyObject *key)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
139
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
140 Add *key* to a :class:`set` instance. Does not apply to :class:`frozenset`
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
141 instances. Return 0 on success or -1 on failure. Raise a :exc:`TypeError` if
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
142 the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
143 Raise a :exc:`SystemError` if *set* is an not an instance of :class:`set` or its
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
144 subtype.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
145
45035
15e8b34254ec Make PySet_Add() work with frozensets.
Raymond Hettinger <python@rcn.com>
parents: 44964
diff changeset
146 .. versionchanged:: 2.6
15e8b34254ec Make PySet_Add() work with frozensets.
Raymond Hettinger <python@rcn.com>
parents: 44964
diff changeset
147 Now works with instances of :class:`frozenset` or its subtypes.
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
148 Like :c:func:`PyTuple_SetItem` in that it can be used to fill-in the
45035
15e8b34254ec Make PySet_Add() work with frozensets.
Raymond Hettinger <python@rcn.com>
parents: 44964
diff changeset
149 values of brand new frozensets before they are exposed to other code.
15e8b34254ec Make PySet_Add() work with frozensets.
Raymond Hettinger <python@rcn.com>
parents: 44964
diff changeset
150
15e8b34254ec Make PySet_Add() work with frozensets.
Raymond Hettinger <python@rcn.com>
parents: 44964
diff changeset
151 The following functions are available for instances of :class:`set` or its
15e8b34254ec Make PySet_Add() work with frozensets.
Raymond Hettinger <python@rcn.com>
parents: 44964
diff changeset
152 subtypes but not for instances of :class:`frozenset` or its subtypes.
15e8b34254ec Make PySet_Add() work with frozensets.
Raymond Hettinger <python@rcn.com>
parents: 44964
diff changeset
153
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
154
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
155 .. c:function:: int PySet_Discard(PyObject *set, PyObject *key)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
156
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
157 Return 1 if found and removed, 0 if not found (no action taken), and -1 if an
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
158 error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
159 :exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`discard`
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
160 method, this function does not automatically convert unhashable sets into
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
161 temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is an not an
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
162 instance of :class:`set` or its subtype.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
163
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
164
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
165 .. c:function:: PyObject* PySet_Pop(PyObject *set)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
166
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
167 Return a new reference to an arbitrary object in the *set*, and removes the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
168 object from the *set*. Return *NULL* on failure. Raise :exc:`KeyError` if the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
169 set is empty. Raise a :exc:`SystemError` if *set* is an not an instance of
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
170 :class:`set` or its subtype.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
171
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
172
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 53588
diff changeset
173 .. c:function:: int PySet_Clear(PyObject *set)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
174
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
175 Empty an existing set of all elements.