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 PyAnySet_Check(PyObject *p)
  56
  57    Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
  58    instance of a subtype.
  59
  60
  61 .. cfunction:: int PyAnySet_CheckExact(PyObject *p)
  62
  63    Return true if *p* is a :class:`set` object or a :class:`frozenset` object but
  64    not an instance of a subtype.
  65
  66
  67 .. cfunction:: int PyFrozenSet_CheckExact(PyObject *p)
  68
  69    Return true if *p* is a :class:`frozenset` object but not an instance of a
  70    subtype.
  71
  72
  73 .. cfunction:: PyObject* PySet_New(PyObject *iterable)
  74
  75    Return a new :class:`set` containing objects returned by the *iterable*.  The
  76    *iterable* may be *NULL* to create a new empty set.  Return the new set on
  77    success or *NULL* on failure.  Raise :exc:`TypeError` if *iterable* is not
  78    actually iterable.  The constructor is also useful for copying a set
  79    (``c=set(s)``).
  80
  81
  82 .. cfunction:: PyObject* PyFrozenSet_New(PyObject *iterable)
  83
  84    Return a new :class:`frozenset` containing objects returned by the *iterable*.
  85    The *iterable* may be *NULL* to create a new empty frozenset.  Return the new
  86    set on success or *NULL* on failure.  Raise :exc:`TypeError` if *iterable* is
  87    not actually iterable.
  88
  89 The following functions and macros are available for instances of :class:`set`
  90 or :class:`frozenset` or instances of their subtypes.
  91
  92
  93 .. cfunction:: Py_ssize_t PySet_Size(PyObject *anyset)
  94
  95    .. index:: builtin: len
  96
  97    Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
  98    ``len(anyset)``.  Raises a :exc:`PyExc_SystemError` if *anyset* is not a
  99    :class:`set`, :class:`frozenset`, or an instance of a subtype.
 100
 101
 102 .. cfunction:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
 103
 104    Macro form of :cfunc:`PySet_Size` without error checking.
 105
 106
 107 .. cfunction:: int PySet_Contains(PyObject *anyset, PyObject *key)
 108
 109    Return 1 if found, 0 if not found, and -1 if an error is encountered.  Unlike
 110    the Python :meth:`__contains__` method, this function does not automatically
 111    convert unhashable sets into temporary frozensets.  Raise a :exc:`TypeError` if
 112    the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
 113    :class:`set`, :class:`frozenset`, or an instance of a subtype.
 114
 115 The following functions are available for instances of :class:`set` or its
 116 subtypes but not for instances of :class:`frozenset` or its subtypes.
 117
 118
 119 .. cfunction:: int PySet_Add(PyObject *set, PyObject *key)
 120
 121    Add *key* to a :class:`set` instance.  Does not apply to :class:`frozenset`
 122    instances.  Return 0 on success or -1 on failure. Raise a :exc:`TypeError` if
 123    the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow.
 124    Raise a :exc:`SystemError` if *set* is an not an instance of :class:`set` or its
 125    subtype.
 126
 127
 128 .. cfunction:: int PySet_Discard(PyObject *set, PyObject *key)
 129
 130    Return 1 if found and removed, 0 if not found (no action taken), and -1 if an
 131    error is encountered.  Does not raise :exc:`KeyError` for missing keys.  Raise a
 132    :exc:`TypeError` if the *key* is unhashable.  Unlike the Python :meth:`discard`
 133    method, this function does not automatically convert unhashable sets into
 134    temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is an not an
 135    instance of :class:`set` or its subtype.
 136
 137
 138 .. cfunction:: PyObject* PySet_Pop(PyObject *set)
 139
 140    Return a new reference to an arbitrary object in the *set*, and removes the
 141    object from the *set*.  Return *NULL* on failure.  Raise :exc:`KeyError` if the
 142    set is empty. Raise a :exc:`SystemError` if *set* is an not an instance of
 143    :class:`set` or its subtype.
 144
 145
 146 .. cfunction:: int PySet_Clear(PyObject *set)
 147
 148    Empty an existing set of all elements.