← Back to branch summary

~ubuntu-branches/ubuntu/trusty/python3.4/trusty-proposed

« back to all changes in this revision

Viewing changes to Doc/c-api/set.rst

  • Committer: Package Import Robot
  • Author(s): Matthias Klose
  • Date: 2013-11-25 09:44:27 UTC
  • Revision ID: package-import@ubuntu.com-20131125094427-lzxj8ap5w01lmo7f
Tags: upstream-3.4~b1
Import upstream version 3.4~b1

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/c-api/set.rst
 
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
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 an 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 an 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 an 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