cpython/Doc/c-api/set.rst

167 lines
6.2 KiB
ReStructuredText
Raw Normal View History

.. highlight:: c
2008-01-20 05:30:57 -04:00
.. _setobjects:
Set Objects
-----------
.. sectionauthor:: Raymond D. Hettinger <python@rcn.com>
.. index::
pair: object; set
pair: object; frozenset
2008-01-20 05:30:57 -04:00
This section details the public API for :class:`set` and :class:`frozenset`
objects. Any functionality not listed below is best accessed using 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`).
2008-01-20 05:30:57 -04:00
.. c:type:: PySetObject
2008-01-20 05:30:57 -04:00
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`
2008-01-20 05:30:57 -04:00
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 all are subject to change. All access should be done through
2008-01-20 05:30:57 -04:00
the documented API rather than by manipulating the values in the structure.
.. c:var:: PyTypeObject PySet_Type
2008-01-20 05:30:57 -04:00
This is an instance of :c:type:`PyTypeObject` representing the Python
2008-01-20 05:30:57 -04:00
:class:`set` type.
.. c:var:: PyTypeObject PyFrozenSet_Type
2008-01-20 05:30:57 -04:00
This is an instance of :c:type:`PyTypeObject` representing the Python
2008-01-20 05:30:57 -04:00
: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)
Merged revisions 60383-60407 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60388 | thomas.heller | 2008-01-28 09:44:13 +0100 (Mon, 28 Jan 2008) | 1 line Revert rev. 59925, it breaks comtypes (I need to further examine this). ........ r60397 | raymond.hettinger | 2008-01-28 21:34:33 +0100 (Mon, 28 Jan 2008) | 5 lines Make PySet_Add() work with frozensets. Works like PyTuple_SetItem() to build-up values in a brand new frozenset. Also, PyFrozenSet_New() is now guaranteed to produce a distinct new frozenset. ........ r60398 | raymond.hettinger | 2008-01-28 22:34:30 +0100 (Mon, 28 Jan 2008) | 1 line Let marshal built-up sets and frozensets one element at a time (without creating an intermediate tuple). ........ r60399 | raymond.hettinger | 2008-01-28 22:47:42 +0100 (Mon, 28 Jan 2008) | 1 line Factor-out common code with a new macro ........ r60400 | raymond.hettinger | 2008-01-28 22:48:07 +0100 (Mon, 28 Jan 2008) | 1 line Factor-out common code with a new macro ........ r60401 | raymond.hettinger | 2008-01-28 22:51:25 +0100 (Mon, 28 Jan 2008) | 1 line Removed unnecessary conditional (spotted by Neal Norwitz). ........ r60403 | gregory.p.smith | 2008-01-29 00:21:00 +0100 (Tue, 29 Jan 2008) | 4 lines Disable use of BerkeleyDB 4.6.x to see what the odd platform buildbots think. In particular, neal norwitz has traced an Ubuntu sparc64 crash to the Lib/test/bsddb/test_basics.py test when opening a db with DB_THREAD. ........ r60405 | brett.cannon | 2008-01-29 05:13:07 +0100 (Tue, 29 Jan 2008) | 2 lines Fix the reindent rule to use $(BUILDPYTHON). ........ r60406 | brett.cannon | 2008-01-29 05:18:04 +0100 (Tue, 29 Jan 2008) | 3 lines Update Vim syntax highlighting to specify what revision was used to generate the file. ........ r60407 | brett.cannon | 2008-01-29 05:20:56 +0100 (Tue, 29 Jan 2008) | 2 lines Ignore .pyc and .pyo files. ........
2008-01-29 08:18:50 -04:00
Return true if *p* is a :class:`set` object or an instance of a subtype.
This function always succeeds.
Merged revisions 60383-60407 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60388 | thomas.heller | 2008-01-28 09:44:13 +0100 (Mon, 28 Jan 2008) | 1 line Revert rev. 59925, it breaks comtypes (I need to further examine this). ........ r60397 | raymond.hettinger | 2008-01-28 21:34:33 +0100 (Mon, 28 Jan 2008) | 5 lines Make PySet_Add() work with frozensets. Works like PyTuple_SetItem() to build-up values in a brand new frozenset. Also, PyFrozenSet_New() is now guaranteed to produce a distinct new frozenset. ........ r60398 | raymond.hettinger | 2008-01-28 22:34:30 +0100 (Mon, 28 Jan 2008) | 1 line Let marshal built-up sets and frozensets one element at a time (without creating an intermediate tuple). ........ r60399 | raymond.hettinger | 2008-01-28 22:47:42 +0100 (Mon, 28 Jan 2008) | 1 line Factor-out common code with a new macro ........ r60400 | raymond.hettinger | 2008-01-28 22:48:07 +0100 (Mon, 28 Jan 2008) | 1 line Factor-out common code with a new macro ........ r60401 | raymond.hettinger | 2008-01-28 22:51:25 +0100 (Mon, 28 Jan 2008) | 1 line Removed unnecessary conditional (spotted by Neal Norwitz). ........ r60403 | gregory.p.smith | 2008-01-29 00:21:00 +0100 (Tue, 29 Jan 2008) | 4 lines Disable use of BerkeleyDB 4.6.x to see what the odd platform buildbots think. In particular, neal norwitz has traced an Ubuntu sparc64 crash to the Lib/test/bsddb/test_basics.py test when opening a db with DB_THREAD. ........ r60405 | brett.cannon | 2008-01-29 05:13:07 +0100 (Tue, 29 Jan 2008) | 2 lines Fix the reindent rule to use $(BUILDPYTHON). ........ r60406 | brett.cannon | 2008-01-29 05:18:04 +0100 (Tue, 29 Jan 2008) | 3 lines Update Vim syntax highlighting to specify what revision was used to generate the file. ........ r60407 | brett.cannon | 2008-01-29 05:20:56 +0100 (Tue, 29 Jan 2008) | 2 lines Ignore .pyc and .pyo files. ........
2008-01-29 08:18:50 -04:00
.. c:function:: int PyFrozenSet_Check(PyObject *p)
Merged revisions 60481,60485,60489-60492,60494-60496,60498-60499,60501-60503,60505-60506,60508-60509,60523-60524,60532,60543,60545,60547-60548,60552-60567 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60553 | neal.norwitz | 2008-02-03 17:53:09 +0100 (Sun, 03 Feb 2008) | 1 line Ignore leaky warnings from test_asynchat ........ r60555 | christian.heimes | 2008-02-03 20:51:13 +0100 (Sun, 03 Feb 2008) | 1 line Another int -> pid_t case ........ r60560 | amaury.forgeotdarc | 2008-02-03 23:51:43 +0100 (Sun, 03 Feb 2008) | 6 lines Ensure that PySet_Add() operates on a newly created frozenset, like PyTuple_SetItem does. Add PyFrozenSet_Check(), which was not needed before; The list of Py*Set_Check* macros seems to be complete now. Add missing NEWS entries about all this. ........ r60563 | amaury.forgeotdarc | 2008-02-04 00:14:32 +0100 (Mon, 04 Feb 2008) | 2 lines Nasty typo in setobject.h ........ r60564 | amaury.forgeotdarc | 2008-02-04 00:15:32 +0100 (Mon, 04 Feb 2008) | 3 lines Correct test_mailbox on win32: since the test sets a custom 'colon' attribute to the main mailbox, copy it to secondary mailbox instances. ........ r60565 | amaury.forgeotdarc | 2008-02-04 00:57:24 +0100 (Mon, 04 Feb 2008) | 2 lines Let test_socketserver pass on win32, which does not have AF_UNIX sockets. ........ r60566 | jeffrey.yasskin | 2008-02-04 02:04:35 +0100 (Mon, 04 Feb 2008) | 2 lines Make int() and long() fall back to __trunc__(). See issue 2002. ........ r60567 | christian.heimes | 2008-02-04 19:00:12 +0100 (Mon, 04 Feb 2008) | 3 lines Patch #1953 I implemented the function sys._compact_freelists() and C API functions PyInt_/PyFloat_CompactFreeList() to compact the pre-allocated blocks of ints and floats. They allow the user to reduce the memory usage of a Python process that deals with lots of numbers. The patch also renames sys._cleartypecache to sys._clear_type_cache ........
2008-02-04 14:48:49 -04:00
Return true if *p* is a :class:`frozenset` object or an instance of a
subtype. This function always succeeds.
Merged revisions 60481,60485,60489-60492,60494-60496,60498-60499,60501-60503,60505-60506,60508-60509,60523-60524,60532,60543,60545,60547-60548,60552-60567 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60553 | neal.norwitz | 2008-02-03 17:53:09 +0100 (Sun, 03 Feb 2008) | 1 line Ignore leaky warnings from test_asynchat ........ r60555 | christian.heimes | 2008-02-03 20:51:13 +0100 (Sun, 03 Feb 2008) | 1 line Another int -> pid_t case ........ r60560 | amaury.forgeotdarc | 2008-02-03 23:51:43 +0100 (Sun, 03 Feb 2008) | 6 lines Ensure that PySet_Add() operates on a newly created frozenset, like PyTuple_SetItem does. Add PyFrozenSet_Check(), which was not needed before; The list of Py*Set_Check* macros seems to be complete now. Add missing NEWS entries about all this. ........ r60563 | amaury.forgeotdarc | 2008-02-04 00:14:32 +0100 (Mon, 04 Feb 2008) | 2 lines Nasty typo in setobject.h ........ r60564 | amaury.forgeotdarc | 2008-02-04 00:15:32 +0100 (Mon, 04 Feb 2008) | 3 lines Correct test_mailbox on win32: since the test sets a custom 'colon' attribute to the main mailbox, copy it to secondary mailbox instances. ........ r60565 | amaury.forgeotdarc | 2008-02-04 00:57:24 +0100 (Mon, 04 Feb 2008) | 2 lines Let test_socketserver pass on win32, which does not have AF_UNIX sockets. ........ r60566 | jeffrey.yasskin | 2008-02-04 02:04:35 +0100 (Mon, 04 Feb 2008) | 2 lines Make int() and long() fall back to __trunc__(). See issue 2002. ........ r60567 | christian.heimes | 2008-02-04 19:00:12 +0100 (Mon, 04 Feb 2008) | 3 lines Patch #1953 I implemented the function sys._compact_freelists() and C API functions PyInt_/PyFloat_CompactFreeList() to compact the pre-allocated blocks of ints and floats. They allow the user to reduce the memory usage of a Python process that deals with lots of numbers. The patch also renames sys._cleartypecache to sys._clear_type_cache ........
2008-02-04 14:48:49 -04:00
.. c:function:: int PyAnySet_Check(PyObject *p)
2008-01-20 05:30:57 -04:00
Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
instance of a subtype. This function always succeeds.
2008-01-20 05:30:57 -04:00
.. c:function:: int PySet_CheckExact(PyObject *p)
Return true if *p* is a :class:`set` object but not an instance of a
subtype. This function always succeeds.
.. versionadded:: 3.10
2008-01-20 05:30:57 -04:00
.. c:function:: int PyAnySet_CheckExact(PyObject *p)
2008-01-20 05:30:57 -04:00
Return true if *p* is a :class:`set` object or a :class:`frozenset` object but
not an instance of a subtype. This function always succeeds.
2008-01-20 05:30:57 -04:00
.. c:function:: int PyFrozenSet_CheckExact(PyObject *p)
2008-01-20 05:30:57 -04:00
Return true if *p* is a :class:`frozenset` object but not an instance of a
subtype. This function always succeeds.
2008-01-20 05:30:57 -04:00
.. c:function:: PyObject* PySet_New(PyObject *iterable)
2008-01-20 05:30:57 -04:00
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
2008-01-20 05:30:57 -04:00
actually iterable. The constructor is also useful for copying a set
(``c=set(s)``).
.. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable)
2008-01-20 05:30:57 -04:00
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
2008-01-20 05:30:57 -04:00
not actually iterable.
Merged revisions 60383-60407 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60388 | thomas.heller | 2008-01-28 09:44:13 +0100 (Mon, 28 Jan 2008) | 1 line Revert rev. 59925, it breaks comtypes (I need to further examine this). ........ r60397 | raymond.hettinger | 2008-01-28 21:34:33 +0100 (Mon, 28 Jan 2008) | 5 lines Make PySet_Add() work with frozensets. Works like PyTuple_SetItem() to build-up values in a brand new frozenset. Also, PyFrozenSet_New() is now guaranteed to produce a distinct new frozenset. ........ r60398 | raymond.hettinger | 2008-01-28 22:34:30 +0100 (Mon, 28 Jan 2008) | 1 line Let marshal built-up sets and frozensets one element at a time (without creating an intermediate tuple). ........ r60399 | raymond.hettinger | 2008-01-28 22:47:42 +0100 (Mon, 28 Jan 2008) | 1 line Factor-out common code with a new macro ........ r60400 | raymond.hettinger | 2008-01-28 22:48:07 +0100 (Mon, 28 Jan 2008) | 1 line Factor-out common code with a new macro ........ r60401 | raymond.hettinger | 2008-01-28 22:51:25 +0100 (Mon, 28 Jan 2008) | 1 line Removed unnecessary conditional (spotted by Neal Norwitz). ........ r60403 | gregory.p.smith | 2008-01-29 00:21:00 +0100 (Tue, 29 Jan 2008) | 4 lines Disable use of BerkeleyDB 4.6.x to see what the odd platform buildbots think. In particular, neal norwitz has traced an Ubuntu sparc64 crash to the Lib/test/bsddb/test_basics.py test when opening a db with DB_THREAD. ........ r60405 | brett.cannon | 2008-01-29 05:13:07 +0100 (Tue, 29 Jan 2008) | 2 lines Fix the reindent rule to use $(BUILDPYTHON). ........ r60406 | brett.cannon | 2008-01-29 05:18:04 +0100 (Tue, 29 Jan 2008) | 3 lines Update Vim syntax highlighting to specify what revision was used to generate the file. ........ r60407 | brett.cannon | 2008-01-29 05:20:56 +0100 (Tue, 29 Jan 2008) | 2 lines Ignore .pyc and .pyo files. ........
2008-01-29 08:18:50 -04:00
2008-01-20 05:30:57 -04:00
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)
2008-01-20 05:30:57 -04:00
.. index:: pair: built-in function; len
2008-01-20 05:30:57 -04:00
Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
``len(anyset)``. Raises a :exc:`SystemError` if *anyset* is not a
2008-01-20 05:30:57 -04:00
:class:`set`, :class:`frozenset`, or an instance of a subtype.
.. c:function:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
2008-01-20 05:30:57 -04:00
Macro form of :c:func:`PySet_Size` without error checking.
2008-01-20 05:30:57 -04:00
.. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key)
2008-01-20 05:30:57 -04:00
Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered. Unlike
the Python :meth:`~object.__contains__` method, this function does not automatically
2008-01-20 05:30:57 -04:00
convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if
the *key* is unhashable. Raise :exc:`SystemError` if *anyset* is not a
2008-01-20 05:30:57 -04:00
:class:`set`, :class:`frozenset`, or an instance of a subtype.
.. c:function:: int PySet_Add(PyObject *set, PyObject *key)
2008-01-20 05:30:57 -04:00
Add *key* to a :class:`set` instance. Also works with :class:`frozenset`
instances (like :c:func:`PyTuple_SetItem` it can be used to fill in the values
of brand new frozensets before they are exposed to other code). 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
2008-01-20 05:30:57 -04:00
subtype.
Merged revisions 60383-60407 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60388 | thomas.heller | 2008-01-28 09:44:13 +0100 (Mon, 28 Jan 2008) | 1 line Revert rev. 59925, it breaks comtypes (I need to further examine this). ........ r60397 | raymond.hettinger | 2008-01-28 21:34:33 +0100 (Mon, 28 Jan 2008) | 5 lines Make PySet_Add() work with frozensets. Works like PyTuple_SetItem() to build-up values in a brand new frozenset. Also, PyFrozenSet_New() is now guaranteed to produce a distinct new frozenset. ........ r60398 | raymond.hettinger | 2008-01-28 22:34:30 +0100 (Mon, 28 Jan 2008) | 1 line Let marshal built-up sets and frozensets one element at a time (without creating an intermediate tuple). ........ r60399 | raymond.hettinger | 2008-01-28 22:47:42 +0100 (Mon, 28 Jan 2008) | 1 line Factor-out common code with a new macro ........ r60400 | raymond.hettinger | 2008-01-28 22:48:07 +0100 (Mon, 28 Jan 2008) | 1 line Factor-out common code with a new macro ........ r60401 | raymond.hettinger | 2008-01-28 22:51:25 +0100 (Mon, 28 Jan 2008) | 1 line Removed unnecessary conditional (spotted by Neal Norwitz). ........ r60403 | gregory.p.smith | 2008-01-29 00:21:00 +0100 (Tue, 29 Jan 2008) | 4 lines Disable use of BerkeleyDB 4.6.x to see what the odd platform buildbots think. In particular, neal norwitz has traced an Ubuntu sparc64 crash to the Lib/test/bsddb/test_basics.py test when opening a db with DB_THREAD. ........ r60405 | brett.cannon | 2008-01-29 05:13:07 +0100 (Tue, 29 Jan 2008) | 2 lines Fix the reindent rule to use $(BUILDPYTHON). ........ r60406 | brett.cannon | 2008-01-29 05:18:04 +0100 (Tue, 29 Jan 2008) | 3 lines Update Vim syntax highlighting to specify what revision was used to generate the file. ........ r60407 | brett.cannon | 2008-01-29 05:20:56 +0100 (Tue, 29 Jan 2008) | 2 lines Ignore .pyc and .pyo files. ........
2008-01-29 08:18:50 -04:00
The following functions are available for instances of :class:`set` or its
subtypes but not for instances of :class:`frozenset` or its subtypes.
2008-01-20 05:30:57 -04:00
.. c:function:: int PySet_Discard(PyObject *set, PyObject *key)
2008-01-20 05:30:57 -04:00
Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an
2008-01-20 05:30:57 -04:00
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`
2008-01-20 05:30:57 -04:00
method, this function does not automatically convert unhashable sets into
temporary frozensets. Raise :exc:`SystemError` if *set* is not an
2008-01-20 05:30:57 -04:00
instance of :class:`set` or its subtype.
.. c:function:: PyObject* PySet_Pop(PyObject *set)
2008-01-20 05:30:57 -04:00
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
2008-01-20 05:30:57 -04:00
:class:`set` or its subtype.
.. c:function:: int PySet_Clear(PyObject *set)
2008-01-20 05:30:57 -04:00
Empty an existing set of all elements.