author | johnathan.white@2718R8BGH51.accenture.com |
Mon, 08 Mar 2010 18:45:03 +0000 | |
changeset 46 | b6935a90ca64 |
parent 1 | 2fb8b9db1c86 |
permissions | -rw-r--r-- |
1
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
1 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
2 |
:mod:`sets` --- Unordered collections of unique elements |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
3 |
======================================================== |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
4 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
5 |
.. module:: sets |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
6 |
:synopsis: Implementation of sets of unique elements. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
7 |
:deprecated: |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
8 |
.. moduleauthor:: Greg V. Wilson <gvwilson@nevex.com> |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
9 |
.. moduleauthor:: Alex Martelli <aleax@aleax.it> |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
10 |
.. moduleauthor:: Guido van Rossum <guido@python.org> |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
11 |
.. sectionauthor:: Raymond D. Hettinger <python@rcn.com> |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
12 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
13 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
14 |
.. versionadded:: 2.3 |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
15 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
16 |
.. deprecated:: 2.6 |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
17 |
The built-in ``set``/``frozenset`` types replace this module. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
18 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
19 |
The :mod:`sets` module provides classes for constructing and manipulating |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
20 |
unordered collections of unique elements. Common uses include membership |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
21 |
testing, removing duplicates from a sequence, and computing standard math |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
22 |
operations on sets such as intersection, union, difference, and symmetric |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
23 |
difference. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
24 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
25 |
Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
26 |
set``. Being an unordered collection, sets do not record element position or |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
27 |
order of insertion. Accordingly, sets do not support indexing, slicing, or |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
28 |
other sequence-like behavior. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
29 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
30 |
Most set applications use the :class:`Set` class which provides every set method |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
31 |
except for :meth:`__hash__`. For advanced applications requiring a hash method, |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
32 |
the :class:`ImmutableSet` class adds a :meth:`__hash__` method but omits methods |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
33 |
which alter the contents of the set. Both :class:`Set` and :class:`ImmutableSet` |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
34 |
derive from :class:`BaseSet`, an abstract class useful for determining whether |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
35 |
something is a set: ``isinstance(obj, BaseSet)``. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
36 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
37 |
The set classes are implemented using dictionaries. Accordingly, the |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
38 |
requirements for set elements are the same as those for dictionary keys; namely, |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
39 |
that the element defines both :meth:`__eq__` and :meth:`__hash__`. As a result, |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
40 |
sets cannot contain mutable elements such as lists or dictionaries. However, |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
41 |
they can contain immutable collections such as tuples or instances of |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
42 |
:class:`ImmutableSet`. For convenience in implementing sets of sets, inner sets |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
43 |
are automatically converted to immutable form, for example, |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
44 |
``Set([Set(['dog'])])`` is transformed to ``Set([ImmutableSet(['dog'])])``. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
45 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
46 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
47 |
.. class:: Set([iterable]) |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
48 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
49 |
Constructs a new empty :class:`Set` object. If the optional *iterable* |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
50 |
parameter is supplied, updates the set with elements obtained from iteration. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
51 |
All of the elements in *iterable* should be immutable or be transformable to an |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
52 |
immutable using the protocol described in section :ref:`immutable-transforms`. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
53 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
54 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
55 |
.. class:: ImmutableSet([iterable]) |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
56 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
57 |
Constructs a new empty :class:`ImmutableSet` object. If the optional *iterable* |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
58 |
parameter is supplied, updates the set with elements obtained from iteration. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
59 |
All of the elements in *iterable* should be immutable or be transformable to an |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
60 |
immutable using the protocol described in section :ref:`immutable-transforms`. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
61 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
62 |
Because :class:`ImmutableSet` objects provide a :meth:`__hash__` method, they |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
63 |
can be used as set elements or as dictionary keys. :class:`ImmutableSet` |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
64 |
objects do not have methods for adding or removing elements, so all of the |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
65 |
elements must be known when the constructor is called. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
66 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
67 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
68 |
.. _set-objects: |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
69 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
70 |
Set Objects |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
71 |
----------- |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
72 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
73 |
Instances of :class:`Set` and :class:`ImmutableSet` both provide the following |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
74 |
operations: |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
75 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
76 |
+-------------------------------+------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
77 |
| Operation | Equivalent | Result | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
78 |
+===============================+============+=================================+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
79 |
| ``len(s)`` | | cardinality of set *s* | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
80 |
+-------------------------------+------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
81 |
| ``x in s`` | | test *x* for membership in *s* | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
82 |
+-------------------------------+------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
83 |
| ``x not in s`` | | test *x* for non-membership in | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
84 |
| | | *s* | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
85 |
+-------------------------------+------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
86 |
| ``s.issubset(t)`` | ``s <= t`` | test whether every element in | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
87 |
| | | *s* is in *t* | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
88 |
+-------------------------------+------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
89 |
| ``s.issuperset(t)`` | ``s >= t`` | test whether every element in | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
90 |
| | | *t* is in *s* | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
91 |
+-------------------------------+------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
92 |
| ``s.union(t)`` | ``s | t`` | new set with elements from both | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
93 |
| | | *s* and *t* | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
94 |
+-------------------------------+------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
95 |
| ``s.intersection(t)`` | ``s & t`` | new set with elements common to | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
96 |
| | | *s* and *t* | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
97 |
+-------------------------------+------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
98 |
| ``s.difference(t)`` | ``s - t`` | new set with elements in *s* | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
99 |
| | | but not in *t* | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
100 |
+-------------------------------+------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
101 |
| ``s.symmetric_difference(t)`` | ``s ^ t`` | new set with elements in either | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
102 |
| | | *s* or *t* but not both | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
103 |
+-------------------------------+------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
104 |
| ``s.copy()`` | | new set with a shallow copy of | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
105 |
| | | *s* | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
106 |
+-------------------------------+------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
107 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
108 |
Note, the non-operator versions of :meth:`union`, :meth:`intersection`, |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
109 |
:meth:`difference`, and :meth:`symmetric_difference` will accept any iterable as |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
110 |
an argument. In contrast, their operator based counterparts require their |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
111 |
arguments to be sets. This precludes error-prone constructions like |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
112 |
``Set('abc') & 'cbs'`` in favor of the more readable |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
113 |
``Set('abc').intersection('cbs')``. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
114 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
115 |
.. versionchanged:: 2.3.1 |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
116 |
Formerly all arguments were required to be sets. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
117 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
118 |
In addition, both :class:`Set` and :class:`ImmutableSet` support set to set |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
119 |
comparisons. Two sets are equal if and only if every element of each set is |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
120 |
contained in the other (each is a subset of the other). A set is less than |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
121 |
another set if and only if the first set is a proper subset of the second set |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
122 |
(is a subset, but is not equal). A set is greater than another set if and only |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
123 |
if the first set is a proper superset of the second set (is a superset, but is |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
124 |
not equal). |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
125 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
126 |
The subset and equality comparisons do not generalize to a complete ordering |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
127 |
function. For example, any two disjoint sets are not equal and are not subsets |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
128 |
of each other, so *all* of the following return ``False``: ``a<b``, ``a==b``, |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
129 |
or ``a>b``. Accordingly, sets do not implement the :meth:`__cmp__` method. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
130 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
131 |
Since sets only define partial ordering (subset relationships), the output of |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
132 |
the :meth:`list.sort` method is undefined for lists of sets. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
133 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
134 |
The following table lists operations available in :class:`ImmutableSet` but not |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
135 |
found in :class:`Set`: |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
136 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
137 |
+-------------+------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
138 |
| Operation | Result | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
139 |
+=============+==============================+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
140 |
| ``hash(s)`` | returns a hash value for *s* | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
141 |
+-------------+------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
142 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
143 |
The following table lists operations available in :class:`Set` but not found in |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
144 |
:class:`ImmutableSet`: |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
145 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
146 |
+--------------------------------------+-------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
147 |
| Operation | Equivalent | Result | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
148 |
+======================================+=============+=================================+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
149 |
| ``s.update(t)`` | *s* \|= *t* | return set *s* with elements | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
150 |
| | | added from *t* | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
151 |
+--------------------------------------+-------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
152 |
| ``s.intersection_update(t)`` | *s* &= *t* | return set *s* keeping only | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
153 |
| | | elements also found in *t* | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
154 |
+--------------------------------------+-------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
155 |
| ``s.difference_update(t)`` | *s* -= *t* | return set *s* after removing | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
156 |
| | | elements found in *t* | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
157 |
+--------------------------------------+-------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
158 |
| ``s.symmetric_difference_update(t)`` | *s* ^= *t* | return set *s* with elements | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
159 |
| | | from *s* or *t* but not both | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
160 |
+--------------------------------------+-------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
161 |
| ``s.add(x)`` | | add element *x* to set *s* | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
162 |
+--------------------------------------+-------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
163 |
| ``s.remove(x)`` | | remove *x* from set *s*; raises | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
164 |
| | | :exc:`KeyError` if not present | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
165 |
+--------------------------------------+-------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
166 |
| ``s.discard(x)`` | | removes *x* from set *s* if | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
167 |
| | | present | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
168 |
+--------------------------------------+-------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
169 |
| ``s.pop()`` | | remove and return an arbitrary | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
170 |
| | | element from *s*; raises | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
171 |
| | | :exc:`KeyError` if empty | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
172 |
+--------------------------------------+-------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
173 |
| ``s.clear()`` | | remove all elements from set | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
174 |
| | | *s* | |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
175 |
+--------------------------------------+-------------+---------------------------------+ |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
176 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
177 |
Note, the non-operator versions of :meth:`update`, :meth:`intersection_update`, |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
178 |
:meth:`difference_update`, and :meth:`symmetric_difference_update` will accept |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
179 |
any iterable as an argument. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
180 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
181 |
.. versionchanged:: 2.3.1 |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
182 |
Formerly all arguments were required to be sets. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
183 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
184 |
Also note, the module also includes a :meth:`union_update` method which is an |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
185 |
alias for :meth:`update`. The method is included for backwards compatibility. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
186 |
Programmers should prefer the :meth:`update` method because it is supported by |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
187 |
the builtin :class:`set()` and :class:`frozenset()` types. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
188 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
189 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
190 |
.. _set-example: |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
191 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
192 |
Example |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
193 |
------- |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
194 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
195 |
>>> from sets import Set |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
196 |
>>> engineers = Set(['John', 'Jane', 'Jack', 'Janice']) |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
197 |
>>> programmers = Set(['Jack', 'Sam', 'Susan', 'Janice']) |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
198 |
>>> managers = Set(['Jane', 'Jack', 'Susan', 'Zack']) |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
199 |
>>> employees = engineers | programmers | managers # union |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
200 |
>>> engineering_management = engineers & managers # intersection |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
201 |
>>> fulltime_management = managers - engineers - programmers # difference |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
202 |
>>> engineers.add('Marvin') # add element |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
203 |
>>> print engineers # doctest: +SKIP |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
204 |
Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack']) |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
205 |
>>> employees.issuperset(engineers) # superset test |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
206 |
False |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
207 |
>>> employees.update(engineers) # update from another set |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
208 |
>>> employees.issuperset(engineers) |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
209 |
True |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
210 |
>>> for group in [engineers, programmers, managers, employees]: # doctest: +SKIP |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
211 |
... group.discard('Susan') # unconditionally remove element |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
212 |
... print group |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
213 |
... |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
214 |
Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack']) |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
215 |
Set(['Janice', 'Jack', 'Sam']) |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
216 |
Set(['Jane', 'Zack', 'Jack']) |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
217 |
Set(['Jack', 'Sam', 'Jane', 'Marvin', 'Janice', 'John', 'Zack']) |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
218 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
219 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
220 |
.. _immutable-transforms: |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
221 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
222 |
Protocol for automatic conversion to immutable |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
223 |
---------------------------------------------- |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
224 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
225 |
Sets can only contain immutable elements. For convenience, mutable :class:`Set` |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
226 |
objects are automatically copied to an :class:`ImmutableSet` before being added |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
227 |
as a set element. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
228 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
229 |
The mechanism is to always add a :term:`hashable` element, or if it is not |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
230 |
hashable, the element is checked to see if it has an :meth:`__as_immutable__` |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
231 |
method which returns an immutable equivalent. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
232 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
233 |
Since :class:`Set` objects have a :meth:`__as_immutable__` method returning an |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
234 |
instance of :class:`ImmutableSet`, it is possible to construct sets of sets. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
235 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
236 |
A similar mechanism is needed by the :meth:`__contains__` and :meth:`remove` |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
237 |
methods which need to hash an element to check for membership in a set. Those |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
238 |
methods check an element for hashability and, if not, check for a |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
239 |
:meth:`__as_temporarily_immutable__` method which returns the element wrapped by |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
240 |
a class that provides temporary methods for :meth:`__hash__`, :meth:`__eq__`, |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
241 |
and :meth:`__ne__`. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
242 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
243 |
The alternate mechanism spares the need to build a separate copy of the original |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
244 |
mutable object. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
245 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
246 |
:class:`Set` objects implement the :meth:`__as_temporarily_immutable__` method |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
247 |
which returns the :class:`Set` object wrapped by a new class |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
248 |
:class:`_TemporarilyImmutableSet`. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
249 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
250 |
The two mechanisms for adding hashability are normally invisible to the user; |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
251 |
however, a conflict can arise in a multi-threaded environment where one thread |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
252 |
is updating a set while another has temporarily wrapped it in |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
253 |
:class:`_TemporarilyImmutableSet`. In other words, sets of mutable sets are not |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
254 |
thread-safe. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
255 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
256 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
257 |
.. _comparison-to-builtin-set: |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
258 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
259 |
Comparison to the built-in :class:`set` types |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
260 |
--------------------------------------------- |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
261 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
262 |
The built-in :class:`set` and :class:`frozenset` types were designed based on |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
263 |
lessons learned from the :mod:`sets` module. The key differences are: |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
264 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
265 |
* :class:`Set` and :class:`ImmutableSet` were renamed to :class:`set` and |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
266 |
:class:`frozenset`. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
267 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
268 |
* There is no equivalent to :class:`BaseSet`. Instead, use ``isinstance(x, |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
269 |
(set, frozenset))``. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
270 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
271 |
* The hash algorithm for the built-ins performs significantly better (fewer |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
272 |
collisions) for most datasets. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
273 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
274 |
* The built-in versions have more space efficient pickles. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
275 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
276 |
* The built-in versions do not have a :meth:`union_update` method. Instead, use |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
277 |
the :meth:`update` method which is equivalent. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
278 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
279 |
* The built-in versions do not have a ``_repr(sorted=True)`` method. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
280 |
Instead, use the built-in :func:`repr` and :func:`sorted` functions: |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
281 |
``repr(sorted(s))``. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
282 |
|
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
283 |
* The built-in version does not have a protocol for automatic conversion to |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
284 |
immutable. Many found this feature to be confusing and no one in the community |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
285 |
reported having found real uses for it. |
2fb8b9db1c86
Initial QEMU (symbian-qemu-0.9.1-12) import
martin.trojer@nokia.com
parents:
diff
changeset
|
286 |