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.