mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-03 19:34:08 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

Simplify explanation of multiset operations by removing restrictions on negative inputs.

Browse source
This commit is contained in:
Raymond Hettinger 2009-01-21 20:36:27 +00:00
parent 63b3a97a2a
commit e0d1b9f11f
3 changed files with 17 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

20
Doc/library/collections.rst
View file

@ -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>`_