rest25/library/sets.rst => rest262/library/sets.rst
f1
2:mod:`sets` --- Unordered collections of unique elements
3========================================================
4
5.. module:: sets
6   :synopsis: Implementation of sets of unique elements.
n7+   :deprecated:
7.. moduleauthor:: Greg V. Wilson <gvwilson@nevex.com>
8.. moduleauthor:: Alex Martelli <aleax@aleax.it>
9.. moduleauthor:: Guido van Rossum <guido@python.org>
10.. sectionauthor:: Raymond D. Hettinger <python@rcn.com>
11
12
13.. versionadded:: 2.3
n15+ 
16+.. deprecated:: 2.6
17+   The built-in ``set``/``frozenset`` types replace this module.
14
15The :mod:`sets` module provides classes for constructing and manipulating
16unordered collections of unique elements.  Common uses include membership
17testing, removing duplicates from a sequence, and computing standard math
18operations on sets such as intersection, union, difference, and symmetric
19difference.
20
21Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in
80|                               |            | *s*                             |
81+-------------------------------+------------+---------------------------------+
82| ``s.issubset(t)``             | ``s <= t`` | test whether every element in   |
83|                               |            | *s* is in *t*                   |
84+-------------------------------+------------+---------------------------------+
85| ``s.issuperset(t)``           | ``s >= t`` | test whether every element in   |
86|                               |            | *t* is in *s*                   |
87+-------------------------------+------------+---------------------------------+
n88-| ``s.union(t)``                | *s* \*t* | new set with elements from both |
n92+| ``s.union(t)``                | ``s | t``  | new set with elements from both |
89|                               |            | *s* and *t*                     |
90+-------------------------------+------------+---------------------------------+
n91-| ``s.intersection(t)``         | *s* & *t*  | new set with elements common to |
n95+| ``s.intersection(t)``         | ``s & t``  | new set with elements common to |
92|                               |            | *s* and *t*                     |
93+-------------------------------+------------+---------------------------------+
n94-| ``s.difference(t)``           | *s* - *t*  | new set with elements in *s*    |
n98+| ``s.difference(t)``           | ``s - t``  | new set with elements in *s*    |
95|                               |            | but not in *t*                  |
96+-------------------------------+------------+---------------------------------+
n97-| ``s.symmetric_difference(t)`` | *s* ^ *t*  | new set with elements in either |
n101+| ``s.symmetric_difference(t)`` | ``s ^ t``  | new set with elements in either |
98|                               |            | *s* or *t* but not both         |
99+-------------------------------+------------+---------------------------------+
100| ``s.copy()``                  |            | new set with a shallow copy of  |
101|                               |            | *s*                             |
102+-------------------------------+------------+---------------------------------+
103
104Note, the non-operator versions of :meth:`union`, :meth:`intersection`,
105:meth:`difference`, and :meth:`symmetric_difference` will accept any iterable as
182Programmers should prefer the :meth:`update` method because it is supported by
183the builtin :class:`set()` and :class:`frozenset()` types.
184
185
186.. _set-example:
187
188Example
189-------
n190- 
191-::
192
193   >>> from sets import Set
194   >>> engineers = Set(['John', 'Jane', 'Jack', 'Janice'])
195   >>> programmers = Set(['Jack', 'Sam', 'Susan', 'Janice'])
196   >>> managers = Set(['Jane', 'Jack', 'Susan', 'Zack'])
197   >>> employees = engineers | programmers | managers           # union
198   >>> engineering_management = engineers & managers            # intersection
199   >>> fulltime_management = managers - engineers - programmers # difference
200   >>> engineers.add('Marvin')                                  # add element
n201-   >>> print engineers
n203+   >>> print engineers # doctest: +SKIP
202   Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack'])
n203-   >>> employees.issuperset(engineers)           # superset test
n205+   >>> employees.issuperset(engineers)     # superset test
204   False
n205-   >>> employees.union_update(engineers)         # update from another set
n207+   >>> employees.update(engineers)         # update from another set
206   >>> employees.issuperset(engineers)
207   True
n208-   >>> for group in [engineers, programmers, managers, employees]:
n210+   >>> for group in [engineers, programmers, managers, employees]: # doctest: +SKIP
209-   ...     group.discard('Susan')                # unconditionally remove element
211+   ...     group.discard('Susan')          # unconditionally remove element
210   ...     print group
211   ...
212   Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack'])
213   Set(['Janice', 'Jack', 'Sam'])
214   Set(['Jane', 'Zack', 'Jack'])
215   Set(['Jack', 'Sam', 'Jane', 'Marvin', 'Janice', 'John', 'Zack'])
216
217
219
220Protocol for automatic conversion to immutable
221----------------------------------------------
222
223Sets can only contain immutable elements.  For convenience, mutable :class:`Set`
224objects are automatically copied to an :class:`ImmutableSet` before being added
225as a set element.
226
n227-The mechanism is to always add a hashable element, or if it is not hashable, the
n229+The mechanism is to always add a :term:`hashable` element, or if it is not
228-element is checked to see if it has an :meth:`__as_immutable__` method which
230+hashable, the element is checked to see if it has an :meth:`__as_immutable__`
229-returns an immutable equivalent.
231+method which returns an immutable equivalent.
230
231Since :class:`Set` objects have a :meth:`__as_immutable__` method returning an
232instance of :class:`ImmutableSet`, it is possible to construct sets of sets.
233
234A similar mechanism is needed by the :meth:`__contains__` and :meth:`remove`
235methods which need to hash an element to check for membership in a set.  Those
236methods check an element for hashability and, if not, check for a
237:meth:`__as_temporarily_immutable__` method which returns the element wrapped by
269* The hash algorithm for the built-ins performs significantly better (fewer
270  collisions) for most datasets.
271
272* The built-in versions have more space efficient pickles.
273
274* The built-in versions do not have a :meth:`union_update` method. Instead, use
275  the :meth:`update` method which is equivalent.
276
t277-* The built-in versions do not have a :meth:`_repr(sorted=True)` method.
t279+* The built-in versions do not have a ``_repr(sorted=True)`` method.
278  Instead, use the built-in :func:`repr` and :func:`sorted` functions:
279  ``repr(sorted(s))``.
280
281* The built-in version does not have a protocol for automatic conversion to
282  immutable.  Many found this feature to be confusing and no one in the community
283  reported having found real uses for it.
284
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op