diff options
Diffstat (limited to 'Doc/library/collections.rst')
| -rw-r--r-- | Doc/library/collections.rst | 37 |
1 files changed, 33 insertions, 4 deletions
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index 816d814..0984751 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -177,6 +177,7 @@ For example:: >>> c = Counter() # a new, empty counter >>> c = Counter('gallahad') # a new counter from an iterable >>> c = Counter({'red': 4, 'blue': 2}) # a new counter from a mapping + >>> c = Counter(spam=8, eggs=1) # a new counter from keyword args The returned object has a dictionary style interface except that it returns a zero count for missing items (instead of raising a :exc:`KeyError` like a @@ -207,7 +208,7 @@ For example:: Elements are returned in arbitrary order. If an element's count has been set to zero or a negative number, :meth:`elements` will ignore it. - >>> c = Counter({'a': 4, 'b': 2, 'd': 0, 'e': -2}) + >>> c = Counter(a=4, b=2, c=0, d=-2) >>> list(c.elements()) ['a', 'a', 'a', 'a', 'b', 'b'] @@ -232,10 +233,10 @@ For example:: .. method:: update([iterable-or-mapping]) - Like :meth:`dict.update` but adds-in counts instead of replacing them. - Elements are counted from an *iterable* or added-in from another - *mapping* (or counter):: + *mapping* (or counter). Like :meth:`dict.update` but adds-in counts + instead of replacing them, and the *iterable* is expected to be a + sequence of elements, not a sequence of ``(key, value)`` pairs:: >>> c = Counter('which') >>> c.update('witch') # add elements from another iterable @@ -255,6 +256,34 @@ Common patterns for working with :class:`Counter` objects:: Counter(dict(list_of_pairs)) # convert from a list of (elem, cnt) pairs c.most_common()[:-n:-1] # n least common elements +Several multiset mathematical operations are provided for combining +:class:`Counter` objects. Multisets are like regular sets but 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:: + + >>> 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) + Counter({'a': 2}) + >>> c & d # interection: min(c[x], d[x]) + Counter({'a': 1, 'b': 1}) + >>> 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}) + **References**: * Wikipedia entry for `Multisets <http://en.wikipedia.org/wiki/Multiset>`_ |