path: root/devdocs/python~3.12/c-api%2Fset.html

 <span id="setobjects"></span><h1>Set Objects</h1> <p id="index-0">This section details the public API for <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a> and <a class="reference internal" href="../library/stdtypes#frozenset" title="frozenset"><code>frozenset</code></a> objects. Any functionality not listed below is best accessed using either the abstract object protocol (including <a class="reference internal" href="call#c.PyObject_CallMethod" title="PyObject_CallMethod"><code>PyObject_CallMethod()</code></a>, <a class="reference internal" href="object#c.PyObject_RichCompareBool" title="PyObject_RichCompareBool"><code>PyObject_RichCompareBool()</code></a>, <a class="reference internal" href="object#c.PyObject_Hash" title="PyObject_Hash"><code>PyObject_Hash()</code></a>, <a class="reference internal" href="object#c.PyObject_Repr" title="PyObject_Repr"><code>PyObject_Repr()</code></a>, <a class="reference internal" href="object#c.PyObject_IsTrue" title="PyObject_IsTrue"><code>PyObject_IsTrue()</code></a>, <a class="reference internal" href="object#c.PyObject_Print" title="PyObject_Print"><code>PyObject_Print()</code></a>, and <a class="reference internal" href="object#c.PyObject_GetIter" title="PyObject_GetIter"><code>PyObject_GetIter()</code></a>) or the abstract number protocol (including <a class="reference internal" href="number#c.PyNumber_And" title="PyNumber_And"><code>PyNumber_And()</code></a>, <a class="reference internal" href="number#c.PyNumber_Subtract" title="PyNumber_Subtract"><code>PyNumber_Subtract()</code></a>, <a class="reference internal" href="number#c.PyNumber_Or" title="PyNumber_Or"><code>PyNumber_Or()</code></a>, <a class="reference internal" href="number#c.PyNumber_Xor" title="PyNumber_Xor"><code>PyNumber_Xor()</code></a>, <a class="reference internal" href="number#c.PyNumber_InPlaceAnd" title="PyNumber_InPlaceAnd"><code>PyNumber_InPlaceAnd()</code></a>, <a class="reference internal" href="number#c.PyNumber_InPlaceSubtract" title="PyNumber_InPlaceSubtract"><code>PyNumber_InPlaceSubtract()</code></a>, <a class="reference internal" href="number#c.PyNumber_InPlaceOr" title="PyNumber_InPlaceOr"><code>PyNumber_InPlaceOr()</code></a>, and <a class="reference internal" href="number#c.PyNumber_InPlaceXor" title="PyNumber_InPlaceXor"><code>PyNumber_InPlaceXor()</code></a>).</p> <dl class="c type"> <dt class="sig sig-object c" id="c.PySetObject">
<code>type PySetObject</code> </dt> <dd>
<p>This subtype of <a class="reference internal" href="structures#c.PyObject" title="PyObject"><code>PyObject</code></a> is used to hold the internal data for both <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a> and <a class="reference internal" href="../library/stdtypes#frozenset" title="frozenset"><code>frozenset</code></a> objects. It is like a <a class="reference internal" href="dict#c.PyDictObject" title="PyDictObject"><code>PyDictObject</code></a> 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 the documented API rather than by manipulating the values in the structure.</p> </dd>
</dl> <dl class="c var"> <dt class="sig sig-object c" id="c.PySet_Type">
<code>PyTypeObject PySet_Type</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This is an instance of <a class="reference internal" href="type#c.PyTypeObject" title="PyTypeObject"><code>PyTypeObject</code></a> representing the Python <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a> type.</p> </dd>
</dl> <dl class="c var"> <dt class="sig sig-object c" id="c.PyFrozenSet_Type">
<code>PyTypeObject PyFrozenSet_Type</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This is an instance of <a class="reference internal" href="type#c.PyTypeObject" title="PyTypeObject"><code>PyTypeObject</code></a> representing the Python <a class="reference internal" href="../library/stdtypes#frozenset" title="frozenset"><code>frozenset</code></a> type.</p> </dd>
</dl> <p>The following type check macros work on pointers to any Python object. Likewise, the constructor functions work with any iterable Python object.</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PySet_Check">
<code>int PySet_Check(PyObject *p)</code> </dt> <dd>
<p>Return true if <em>p</em> is a <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a> object or an instance of a subtype. This function always succeeds.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFrozenSet_Check">
<code>int PyFrozenSet_Check(PyObject *p)</code> </dt> <dd>
<p>Return true if <em>p</em> is a <a class="reference internal" href="../library/stdtypes#frozenset" title="frozenset"><code>frozenset</code></a> object or an instance of a subtype. This function always succeeds.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyAnySet_Check">
<code>int PyAnySet_Check(PyObject *p)</code> </dt> <dd>
<p>Return true if <em>p</em> is a <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a> object, a <a class="reference internal" href="../library/stdtypes#frozenset" title="frozenset"><code>frozenset</code></a> object, or an instance of a subtype. This function always succeeds.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PySet_CheckExact">
<code>int PySet_CheckExact(PyObject *p)</code> </dt> <dd>
<p>Return true if <em>p</em> is a <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a> object but not an instance of a subtype. This function always succeeds.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.10.</span></p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyAnySet_CheckExact">
<code>int PyAnySet_CheckExact(PyObject *p)</code> </dt> <dd>
<p>Return true if <em>p</em> is a <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a> object or a <a class="reference internal" href="../library/stdtypes#frozenset" title="frozenset"><code>frozenset</code></a> object but not an instance of a subtype. This function always succeeds.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFrozenSet_CheckExact">
<code>int PyFrozenSet_CheckExact(PyObject *p)</code> </dt> <dd>
<p>Return true if <em>p</em> is a <a class="reference internal" href="../library/stdtypes#frozenset" title="frozenset"><code>frozenset</code></a> object but not an instance of a subtype. This function always succeeds.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PySet_New">
<code>PyObject *PySet_New(PyObject *iterable)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a new <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a> containing objects returned by the <em>iterable</em>. The <em>iterable</em> may be <code>NULL</code> to create a new empty set. Return the new set on success or <code>NULL</code> on failure. Raise <a class="reference internal" href="../library/exceptions#TypeError" title="TypeError"><code>TypeError</code></a> if <em>iterable</em> is not actually iterable. The constructor is also useful for copying a set (<code>c=set(s)</code>).</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFrozenSet_New">
<code>PyObject *PyFrozenSet_New(PyObject *iterable)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a new <a class="reference internal" href="../library/stdtypes#frozenset" title="frozenset"><code>frozenset</code></a> containing objects returned by the <em>iterable</em>. The <em>iterable</em> may be <code>NULL</code> to create a new empty frozenset. Return the new set on success or <code>NULL</code> on failure. Raise <a class="reference internal" href="../library/exceptions#TypeError" title="TypeError"><code>TypeError</code></a> if <em>iterable</em> is not actually iterable.</p> </dd>
</dl> <p>The following functions and macros are available for instances of <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a> or <a class="reference internal" href="../library/stdtypes#frozenset" title="frozenset"><code>frozenset</code></a> or instances of their subtypes.</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PySet_Size">
<code>Py_ssize_t PySet_Size(PyObject *anyset)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-1">Return the length of a <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a> or <a class="reference internal" href="../library/stdtypes#frozenset" title="frozenset"><code>frozenset</code></a> object. Equivalent to <code>len(anyset)</code>. Raises a <a class="reference internal" href="../library/exceptions#SystemError" title="SystemError"><code>SystemError</code></a> if <em>anyset</em> is not a <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a>, <a class="reference internal" href="../library/stdtypes#frozenset" title="frozenset"><code>frozenset</code></a>, or an instance of a subtype.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PySet_GET_SIZE">
<code>Py_ssize_t PySet_GET_SIZE(PyObject *anyset)</code> </dt> <dd>
<p>Macro form of <a class="reference internal" href="#c.PySet_Size" title="PySet_Size"><code>PySet_Size()</code></a> without error checking.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PySet_Contains">
<code>int PySet_Contains(PyObject *anyset, PyObject *key)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return <code>1</code> if found, <code>0</code> if not found, and <code>-1</code> if an error is encountered. Unlike the Python <a class="reference internal" href="../reference/datamodel#object.__contains__" title="object.__contains__"><code>__contains__()</code></a> method, this function does not automatically convert unhashable sets into temporary frozensets. Raise a <a class="reference internal" href="../library/exceptions#TypeError" title="TypeError"><code>TypeError</code></a> if the <em>key</em> is unhashable. Raise <a class="reference internal" href="../library/exceptions#SystemError" title="SystemError"><code>SystemError</code></a> if <em>anyset</em> is not a <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a>, <a class="reference internal" href="../library/stdtypes#frozenset" title="frozenset"><code>frozenset</code></a>, or an instance of a subtype.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PySet_Add">
<code>int PySet_Add(PyObject *set, PyObject *key)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Add <em>key</em> to a <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a> instance. Also works with <a class="reference internal" href="../library/stdtypes#frozenset" title="frozenset"><code>frozenset</code></a> instances (like <a class="reference internal" href="tuple#c.PyTuple_SetItem" title="PyTuple_SetItem"><code>PyTuple_SetItem()</code></a> it can be used to fill in the values of brand new frozensets before they are exposed to other code). Return <code>0</code> on success or <code>-1</code> on failure. Raise a <a class="reference internal" href="../library/exceptions#TypeError" title="TypeError"><code>TypeError</code></a> if the <em>key</em> is unhashable. Raise a <a class="reference internal" href="../library/exceptions#MemoryError" title="MemoryError"><code>MemoryError</code></a> if there is no room to grow. Raise a <a class="reference internal" href="../library/exceptions#SystemError" title="SystemError"><code>SystemError</code></a> if <em>set</em> is not an instance of <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a> or its subtype.</p> </dd>
</dl> <p>The following functions are available for instances of <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a> or its subtypes but not for instances of <a class="reference internal" href="../library/stdtypes#frozenset" title="frozenset"><code>frozenset</code></a> or its subtypes.</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PySet_Discard">
<code>int PySet_Discard(PyObject *set, PyObject *key)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return <code>1</code> if found and removed, <code>0</code> if not found (no action taken), and <code>-1</code> if an error is encountered. Does not raise <a class="reference internal" href="../library/exceptions#KeyError" title="KeyError"><code>KeyError</code></a> for missing keys. Raise a <a class="reference internal" href="../library/exceptions#TypeError" title="TypeError"><code>TypeError</code></a> if the <em>key</em> is unhashable. Unlike the Python <a class="reference internal" href="../library/stdtypes#frozenset.discard" title="frozenset.discard"><code>discard()</code></a> method, this function does not automatically convert unhashable sets into temporary frozensets. Raise <a class="reference internal" href="../library/exceptions#SystemError" title="SystemError"><code>SystemError</code></a> if <em>set</em> is not an instance of <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a> or its subtype.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PySet_Pop">
<code>PyObject *PySet_Pop(PyObject *set)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a new reference to an arbitrary object in the <em>set</em>, and removes the object from the <em>set</em>. Return <code>NULL</code> on failure. Raise <a class="reference internal" href="../library/exceptions#KeyError" title="KeyError"><code>KeyError</code></a> if the set is empty. Raise a <a class="reference internal" href="../library/exceptions#SystemError" title="SystemError"><code>SystemError</code></a> if <em>set</em> is not an instance of <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a> or its subtype.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PySet_Clear">
<code>int PySet_Clear(PyObject *set)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Empty an existing set of all elements. Return <code>0</code> on success. Return <code>-1</code> and raise <a class="reference internal" href="../library/exceptions#SystemError" title="SystemError"><code>SystemError</code></a> if <em>set</em> is not an instance of <a class="reference internal" href="../library/stdtypes#set" title="set"><code>set</code></a> or its subtype.</p> </dd>
</dl> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/c-api/set.html" class="_attribution-link">https://docs.python.org/3.12/c-api/set.html</a>
  </p>
</div>