PageRenderTime 47ms CodeModel.GetById 36ms app.highlight 9ms RepoModel.GetById 1ms app.codeStats 0ms

/Doc/c-api/set.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 175 lines | 110 code | 65 blank | 0 comment | 0 complexity | 87db4d97fcff81afb5303a823baff97e MD5 | raw file
  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 :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
 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.. 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
107The following functions and macros are available for instances of :class:`set`
108or :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   .. versionchanged:: 2.5
120      This function returned an :ctype:`int`. This might require changes in
121      your code for properly supporting 64-bit systems.
122
123
124.. cfunction:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
125
126   Macro form of :cfunc:`PySet_Size` without error checking.
127
128
129.. cfunction:: 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.. cfunction:: 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 an 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 :cfunc:`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.. cfunction:: 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:`discard`
160   method, this function does not automatically convert unhashable sets into
161   temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is an not an
162   instance of :class:`set` or its subtype.
163
164
165.. cfunction:: 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 an not an instance of
170   :class:`set` or its subtype.
171
172
173.. cfunction:: int PySet_Clear(PyObject *set)
174
175   Empty an existing set of all elements.