summaryrefslogtreecommitdiffstats
path: root/Doc/library
diff options
context:
space:
mode:
authorRaymond Hettinger <python@rcn.com>2009-01-21 20:36:27 (GMT)
committerRaymond Hettinger <python@rcn.com>2009-01-21 20:36:27 (GMT)
commite0d1b9f11fc10cc2fb797606dc55967a66821529 (patch)
tree2a8ae4cab2ea1614a2ef2f7f3c6557b08862fd20 /Doc/library
parent63b3a97a2a7277fb05e2aeaee9890a25fb385702 (diff)
downloadcpython-e0d1b9f11fc10cc2fb797606dc55967a66821529.zip
cpython-e0d1b9f11fc10cc2fb797606dc55967a66821529.tar.gz
cpython-e0d1b9f11fc10cc2fb797606dc55967a66821529.tar.bz2
Simplify explanation of multiset operations by removing restrictions on negative inputs.
Diffstat (limited to 'Doc/library')
-rw-r--r--Doc/library/collections.rst20
1 files changed, 6 insertions, 14 deletions
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index c231af0..2c4de2e 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -253,16 +253,18 @@ Common patterns for working with :class:`Counter` objects::
c.items() # convert to a list of (elem, cnt) pairs
Counter(dict(list_of_pairs)) # convert from a list of (elem, cnt) pairs
c.most_common()[:-n:-1] # n least common elements
+ c += Counter() # remove zero and negative counts
Several multiset mathematical operations are provided for combining
-:class:`Counter` objects. Multisets are like regular sets but allowed to
+:class:`Counter` objects. Multisets are like regular sets but are allowed to
contain repeated elements (with counts of one or more). Addition and
subtraction combine counters by adding or subtracting the counts of
corresponding elements. Intersection and union return the minimum and maximum
-of corresponding counts::
+of corresponding counts. All four multiset operations exclude results with
+zero or negative counts::
- >>> c = Counter({'a': 3, 'b': 1})
- >>> d = Counter({'a': 1, 'b': 2})
+ >>> c = Counter(a=3, b=1)
+ >>> d = Counter(a=1, b=2)
>>> c + d # add two counters together: c[x] + d[x]
Counter({'a': 4, 'b': 3})
>>> c - d # subtract (keeping only positive counts)
@@ -272,16 +274,6 @@ of corresponding counts::
>>> c | d # union: max(c[x], d[x])
Counter({'a': 3, 'b': 2})
-All four multiset operations produce only positive counts (negative and zero
-results are skipped). If inputs include negative counts, addition will sum
-both counts and then exclude non-positive results. The other three operations
-are undefined for negative inputs::
-
- >>> e = Counter(a=8, b=-2, c=0)
- >>> e += Counter() # remove zero and negative counts
- >>> e
- Counter({'a': 8})
-
.. seealso::
* `Bag class <http://www.gnu.org/software/smalltalk/manual-base/html_node/Bag.html>`_