Tighten-up the docs for Counter().
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index 2c4de2e..4cf3a48 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -146,10 +146,9 @@
A counter tool is provided to support convenient and rapid tallies.
For example::
- # Tally repeated words in a list
- >>> words = ['red', 'blue', 'red', 'green', 'blue', 'blue']
+ # Tally occurrences of words in a list
>>> cnt = Counter()
- >>> for word in words:
+ >>> for word in ['red', 'blue', 'red', 'green', 'blue', 'blue']:
... cnt[word] += 1
>>> cnt
Counter({'blue': 3, 'red': 2, 'green': 1})
@@ -163,7 +162,7 @@
.. class:: Counter([iterable-or-mapping])
- A :class:`Counter` is a :class:`dict` subclass for counting hashable items.
+ A :class:`Counter` is a :class:`dict` subclass for counting hashable objects.
It is an unordered collection where elements are stored as dictionary keys
and their counts are stored as dictionary values. Counts are allowed to be
any integer value including zero or negative counts. The :class:`Counter`
@@ -177,16 +176,15 @@
>>> 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
- dictionary would)::
+ Counter objects have a dictionary interface except that they return a zero
+ count for missing items instead of raising a :exc:`KeyError`::
>>> c = Counter(['egg', 'ham'])
>>> c['bacon'] # count of a missing element is zero
0
- Assigning a count of zero or reducing the count to zero leaves the
- element in the dictionary. Use ``del`` to remove the entry entirely:
+ Setting a count to zero still leaves an element in the dictionary. Use
+ ``del`` to remove it entirely:
>>> c = Counter(['arthur', 'gwain'])
>>> c['arthur'] = 0 # set the count of 'arthur' to zero
@@ -202,9 +200,9 @@
.. method:: elements()
- Return an iterator over elements repeating each as many times as its count.
- 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.
+ Return an iterator over elements repeating each as many times as its
+ count. Elements are returned in arbitrary order. If an element's count
+ is less than one, :meth:`elements` will ignore it.
>>> c = Counter(a=4, b=2, c=0, d=-2)
>>> list(c.elements())
@@ -220,20 +218,18 @@
>>> Counter('abracadabra').most_common(3)
[('a', 5), ('r', 2), ('b', 2)]
- The usual dictionary methods are available for :class:`Counter` objects.
- All of those work the same as they do for dictionaries except for two
- which work differently for counters.
+ The usual dictionary methods are available for :class:`Counter` objects
+ except for two which work differently for counters.
.. method:: fromkeys(iterable)
- There is no equivalent class method for :class:`Counter` objects.
- Raises a :exc:`NotImplementedError` when called.
+ This class method is not implemented for :class:`Counter` objects.
.. method:: update([iterable-or-mapping])
Elements are counted from an *iterable* or added-in from another
*mapping* (or counter). Like :meth:`dict.update` but adds-in counts
- instead of replacing them, and the *iterable* is expected to be a
+ instead of replacing them. Also, the *iterable* is expected to be a
sequence of elements, not a sequence of ``(key, value)`` pairs::
>>> c = Counter('which')
@@ -261,7 +257,7 @@
subtraction combine counters by adding or subtracting the counts of
corresponding elements. Intersection and union return the minimum and maximum
of corresponding counts. All four multiset operations exclude results with
-zero or negative counts::
+counts less than one::
>>> c = Counter(a=3, b=1)
>>> d = Counter(a=1, b=2)
@@ -279,9 +275,9 @@
* `Bag class <http://www.gnu.org/software/smalltalk/manual-base/html_node/Bag.html>`_
in Smalltalk.
- * An early Python `Bag recipe <http://code.activestate.com/recipes/259174/>`_
- for Python 2.4 and a `Counter <http://code.activestate.com/recipes/576611/>`_
- comformant recipe for Python 2.5 and later.
+ * A `Counter <http://code.activestate.com/recipes/576611/>`_ conformant
+ recipe for Python 2.5 and an early Python `Bag recipe
+ <http://code.activestate.com/recipes/259174/>`_ for Python 2.4.
* Wikipedia entry for `Multisets <http://en.wikipedia.org/wiki/Multiset>`_\.
@@ -292,9 +288,9 @@
*Knuth, Donald. The Art of Computer Programming Volume II,
Section 4.6.3, Exercise 19*\.
- * To enumerate all possible distinct multisets of a given size over a given
- set of inputs, see the :func:`combinations_with_replacement` function in
- the :ref:`itertools-recipes` for itertools::
+ * To enumerate all distinct multisets of a given size over a given set of
+ elements, see the :func:`combinations_with_replacement` function in the
+ :ref:`itertools-recipes` for itertools::
map(Counter, combinations_with_replacement('abc', 2)) --> AA AB AC BB BC CC