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 .. 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    .. 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
 151 The following functions are available for instances of :class:`set` or its
 152 subtypes 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.