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
 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.