FM / c-api

/usr/share/doc/python2-docs/html/_sources/c-api/

/usr/share/doc/python2-docs/html/_sources/c-api

Name	Size	Mode	Actions
abstract.rst.txt	702	0644	edit dl rm
allocation.rst.txt	4796	0644	edit dl rm
arg.rst.txt	26004	0644	edit dl rm
bool.rst.txt	1304	0644	edit dl rm
buffer.rst.txt	22965	0644	edit dl rm
bytearray.rst.txt	2181	0644	edit dl rm
capsule.rst.txt	5741	0644	edit dl rm
cell.rst.txt	1940	0644	edit dl rm
class.rst.txt	1866	0644	edit dl rm
cobject.rst.txt	1870	0644	edit dl rm
code.rst.txt	1635	0644	edit dl rm
codec.rst.txt	4643	0644	edit dl rm
complex.rst.txt	4079	0644	edit dl rm
concrete.rst.txt	1963	0644	edit dl rm
conversion.rst.txt	7092	0644	edit dl rm
datetime.rst.txt	6413	0644	edit dl rm
descriptor.rst.txt	1296	0644	edit dl rm
dict.rst.txt	7757	0644	edit dl rm
exceptions.rst.txt	35304	0644	edit dl rm
file.rst.txt	6198	0644	edit dl rm
float.rst.txt	3371	0644	edit dl rm
function.rst.txt	2421	0644	edit dl rm
gcsupport.rst.txt	6587	0644	edit dl rm
gen.rst.txt	920	0644	edit dl rm
import.rst.txt	11221	0644	edit dl rm
index.rst.txt	578	0644	edit dl rm
init.rst.txt	49160	0644	edit dl rm
int.rst.txt	4578	0644	edit dl rm
intro.rst.txt	28473	0644	edit dl rm
iter.rst.txt	1390	0644	edit dl rm
iterator.rst.txt	1796	0644	edit dl rm
list.rst.txt	6362	0644	edit dl rm
long.rst.txt	7987	0644	edit dl rm
mapping.rst.txt	2874	0644	edit dl rm
marshal.rst.txt	3985	0644	edit dl rm
memory.rst.txt	11556	0644	edit dl rm
method.rst.txt	2099	0644	edit dl rm
module.rst.txt	3867	0644	edit dl rm
none.rst.txt	697	0644	edit dl rm
number.rst.txt	11939	0644	edit dl rm
objbuffer.rst.txt	2516	0644	edit dl rm
object.rst.txt	17491	0644	edit dl rm
objimpl.rst.txt	305	0644	edit dl rm
refcounting.rst.txt	2934	0644	edit dl rm
reflection.rst.txt	1567	0644	edit dl rm
sequence.rst.txt	8716	0644	edit dl rm
set.rst.txt	6588	0644	edit dl rm
slice.rst.txt	2979	0644	edit dl rm
string.rst.txt	15422	0644	edit dl rm
structures.rst.txt	14966	0644	edit dl rm
sys.rst.txt	5714	0644	edit dl rm
tuple.rst.txt	5491	0644	edit dl rm
type.rst.txt	2761	0644	edit dl rm
typeobj.rst.txt	66936	0644	edit dl rm
unicode.rst.txt	45126	0644	edit dl rm
utilities.rst.txt	415	0644	edit dl rm
veryhigh.rst.txt	13363	0644	edit dl rm
weakref.rst.txt	2820	0644	edit dl rm

Edit: /usr/share/doc/python2-docs/html/_sources/c-api/set.rst.txt (6588B)

.. highlightlang:: c

.. _setobjects:

Set Objects
-----------

.. sectionauthor:: Raymond D. Hettinger <python@rcn.com>

.. index::
   object: set
   object: frozenset

.. versionadded:: 2.5

This section details the public API for :class:`set` and :class:`frozenset`
objects.  Any functionality not listed below is best accessed using the either
the abstract object protocol (including :c:func:`PyObject_CallMethod`,
:c:func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`,
:c:func:`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and
:c:func:`PyObject_GetIter`) or the abstract number protocol (including
:c:func:`PyNumber_And`, :c:func:`PyNumber_Subtract`, :c:func:`PyNumber_Or`,
:c:func:`PyNumber_Xor`, :c:func:`PyNumber_InPlaceAnd`,
:c:func:`PyNumber_InPlaceSubtract`, :c:func:`PyNumber_InPlaceOr`, and
:c:func:`PyNumber_InPlaceXor`).

.. c:type:: PySetObject

This subtype of :c:type:`PyObject` is used to hold the internal data for both
   :class:`set` and :class:`frozenset` objects.  It is like a :c:type:`PyDictObject`
   in that it is a fixed size for small sets (much like tuple storage) and will
   point to a separate, variable sized block of memory for medium and large sized
   sets (much like list storage). None of the fields of this structure should be
   considered public and are subject to change.  All access should be done through
   the documented API rather than by manipulating the values in the structure.

.. c:var:: PyTypeObject PySet_Type

This is an instance of :c:type:`PyTypeObject` representing the Python
   :class:`set` type.

.. c:var:: PyTypeObject PyFrozenSet_Type

This is an instance of :c:type:`PyTypeObject` representing the Python
   :class:`frozenset` type.

The following type check macros work on pointers to any Python object. Likewise,
the constructor functions work with any iterable Python object.

.. c:function:: int PySet_Check(PyObject *p)

Return true if *p* is a :class:`set` object or an instance of a subtype.

.. versionadded:: 2.6

.. c:function:: int PyFrozenSet_Check(PyObject *p)

Return true if *p* is a :class:`frozenset` object or an instance of a
   subtype.

.. versionadded:: 2.6

.. c:function:: int PyAnySet_Check(PyObject *p)

Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
   instance of a subtype.

.. c:function:: int PyAnySet_CheckExact(PyObject *p)

Return true if *p* is a :class:`set` object or a :class:`frozenset` object but
   not an instance of a subtype.

.. c:function:: int PyFrozenSet_CheckExact(PyObject *p)

Return true if *p* is a :class:`frozenset` object but not an instance of a
   subtype.

.. c:function:: PyObject* PySet_New(PyObject *iterable)

Return a new :class:`set` containing objects returned by the *iterable*.  The
   *iterable* may be *NULL* to create a new empty set.  Return the new set on
   success or *NULL* on failure.  Raise :exc:`TypeError` if *iterable* is not
   actually iterable.  The constructor is also useful for copying a set
   (``c=set(s)``).

.. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable)

Return a new :class:`frozenset` containing objects returned by the *iterable*.
   The *iterable* may be *NULL* to create a new empty frozenset.  Return the new
   set on success or *NULL* on failure.  Raise :exc:`TypeError` if *iterable* is
   not actually iterable.

.. versionchanged:: 2.6
      Now guaranteed to return a brand-new :class:`frozenset`.  Formerly,
      frozensets of zero-length were a singleton.  This got in the way of
      building-up new frozensets with :meth:`PySet_Add`.

The following functions and macros are available for instances of :class:`set`
or :class:`frozenset` or instances of their subtypes.

.. c:function:: Py_ssize_t PySet_Size(PyObject *anyset)

.. index:: builtin: len

Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
   ``len(anyset)``.  Raises a :exc:`PyExc_SystemError` if *anyset* is not a
   :class:`set`, :class:`frozenset`, or an instance of a subtype.

.. versionchanged:: 2.5
      This function returned an :c:type:`int`. This might require changes in
      your code for properly supporting 64-bit systems.

.. c:function:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)

Macro form of :c:func:`PySet_Size` without error checking.

.. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key)

Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered.  Unlike
   the Python :meth:`__contains__` method, this function does not automatically
   convert unhashable sets into temporary frozensets.  Raise a :exc:`TypeError` if
   the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
   :class:`set`, :class:`frozenset`, or an instance of a subtype.

.. c:function:: int PySet_Add(PyObject *set, PyObject *key)

Add *key* to a :class:`set` instance.  Does not apply to :class:`frozenset`
   instances.  Return ``0`` on success or ``-1`` on failure. Raise a :exc:`TypeError` if
   the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow.
   Raise a :exc:`SystemError` if *set* is not an instance of :class:`set` or its
   subtype.

.. versionchanged:: 2.6
      Now works with instances of :class:`frozenset` or its subtypes.
      Like :c:func:`PyTuple_SetItem` in that it can be used to fill-in the
      values of brand new frozensets before they are exposed to other code.

The following functions are available for instances of :class:`set` or its
subtypes but not for instances of :class:`frozenset` or its subtypes.

.. c:function:: int PySet_Discard(PyObject *set, PyObject *key)

Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an
   error is encountered.  Does not raise :exc:`KeyError` for missing keys.  Raise a
   :exc:`TypeError` if the *key* is unhashable.  Unlike the Python :meth:`~set.discard`
   method, this function does not automatically convert unhashable sets into
   temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is not an
   instance of :class:`set` or its subtype.

.. c:function:: PyObject* PySet_Pop(PyObject *set)

Return a new reference to an arbitrary object in the *set*, and removes the
   object from the *set*.  Return *NULL* on failure.  Raise :exc:`KeyError` if the
   set is empty. Raise a :exc:`SystemError` if *set* is not an instance of
   :class:`set` or its subtype.

.. c:function:: int PySet_Clear(PyObject *set)

Empty an existing set of all elements.

.. highlightlang:: c .. _setobjects: Set Objects ----------- .. sectionauthor:: Raymond D. Hettinger .. index:: object: set object: frozenset .. versionadded:: 2.5 This section details the public API for :class:`set` and :class:`frozenset` objects. Any functionality not listed below is best accessed using the either the abstract object protocol (including :c:func:`PyObject_CallMethod`, :c:func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`, :c:func:`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and :c:func:`PyObject_GetIter`) or the abstract number protocol (including :c:func:`PyNumber_And`, :c:func:`PyNumber_Subtract`, :c:func:`PyNumber_Or`, :c:func:`PyNumber_Xor`, :c:func:`PyNumber_InPlaceAnd`, :c:func:`PyNumber_InPlaceSubtract`, :c:func:`PyNumber_InPlaceOr`, and :c:func:`PyNumber_InPlaceXor`). .. c:type:: PySetObject This subtype of :c:type:`PyObject` is used to hold the internal data for both :class:`set` and :class:`frozenset` objects. It is like a :c:type:`PyDictObject` in that it is a fixed size for small sets (much like tuple storage) and will point to a separate, variable sized block of memory for medium and large sized sets (much like list storage). None of the fields of this structure should be considered public and are subject to change. All access should be done through the documented API rather than by manipulating the values in the structure. .. c:var:: PyTypeObject PySet_Type This is an instance of :c:type:`PyTypeObject` representing the Python :class:`set` type. .. c:var:: PyTypeObject PyFrozenSet_Type This is an instance of :c:type:`PyTypeObject` representing the Python :class:`frozenset` type. The following type check macros work on pointers to any Python object. Likewise, the constructor functions work with any iterable Python object. .. c:function:: int PySet_Check(PyObject *p) Return true if *p* is a :class:`set` object or an instance of a subtype. .. versionadded:: 2.6 .. c:function:: int PyFrozenSet_Check(PyObject *p) Return true if *p* is a :class:`frozenset` object or an instance of a subtype. .. versionadded:: 2.6 .. c:function:: int PyAnySet_Check(PyObject *p) Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an instance of a subtype. .. c:function:: int PyAnySet_CheckExact(PyObject *p) Return true if *p* is a :class:`set` object or a :class:`frozenset` object but not an instance of a subtype. .. c:function:: int PyFrozenSet_CheckExact(PyObject *p) Return true if *p* is a :class:`frozenset` object but not an instance of a subtype. .. c:function:: PyObject* PySet_New(PyObject *iterable) Return a new :class:`set` containing objects returned by the *iterable*. The *iterable* may be *NULL* to create a new empty set. Return the new set on success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is not actually iterable. The constructor is also useful for copying a set (``c=set(s)``). .. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable) Return a new :class:`frozenset` containing objects returned by the *iterable*. The *iterable* may be *NULL* to create a new empty frozenset. Return the new set on success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is not actually iterable. .. versionchanged:: 2.6 Now guaranteed to return a brand-new :class:`frozenset`. Formerly, frozensets of zero-length were a singleton. This got in the way of building-up new frozensets with :meth:`PySet_Add`. The following functions and macros are available for instances of :class:`set` or :class:`frozenset` or instances of their subtypes. .. c:function:: Py_ssize_t PySet_Size(PyObject *anyset) .. index:: builtin: len Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to ``len(anyset)``. Raises a :exc:`PyExc_SystemError` if *anyset* is not a :class:`set`, :class:`frozenset`, or an instance of a subtype. .. versionchanged:: 2.5 This function returned an :c:type:`int`. This might require changes in your code for properly supporting 64-bit systems. .. c:function:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset) Macro form of :c:func:`PySet_Size` without error checking. .. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key) Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered. Unlike the Python :meth:`__contains__` method, this function does not automatically convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a :class:`set`, :class:`frozenset`, or an instance of a subtype. .. c:function:: int PySet_Add(PyObject *set, PyObject *key) Add *key* to a :class:`set` instance. Does not apply to :class:`frozenset` instances. Return ``0`` on success or ``-1`` on failure. Raise a :exc:`TypeError` if the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow. Raise a :exc:`SystemError` if *set* is not an instance of :class:`set` or its subtype. .. versionchanged:: 2.6 Now works with instances of :class:`frozenset` or its subtypes. Like :c:func:`PyTuple_SetItem` in that it can be used to fill-in the values of brand new frozensets before they are exposed to other code. The following functions are available for instances of :class:`set` or its subtypes but not for instances of :class:`frozenset` or its subtypes. .. c:function:: int PySet_Discard(PyObject *set, PyObject *key) Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a :exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~set.discard` method, this function does not automatically convert unhashable sets into temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is not an instance of :class:`set` or its subtype. .. c:function:: PyObject* PySet_Pop(PyObject *set) Return a new reference to an arbitrary object in the *set*, and removes the object from the *set*. Return *NULL* on failure. Raise :exc:`KeyError` if the set is empty. Raise a :exc:`SystemError` if *set* is not an instance of :class:`set` or its subtype. .. c:function:: int PySet_Clear(PyObject *set) Empty an existing set of all elements.