[Python-checkins] r80020 - python/branches/py3k/Doc/library/collections.rst

[raymond.hettinger]

Author: raymond.hettinger
Date: Mon Apr 12 23:45:14 2010
New Revision: 80020

Log:
Add usage notes for collections.Counter()

Modified:
   python/branches/py3k/Doc/library/collections.rst

Modified: python/branches/py3k/Doc/library/collections.rst
==============================================================================
--- python/branches/py3k/Doc/library/collections.rst	(original)
+++ python/branches/py3k/Doc/library/collections.rst	Mon Apr 12 23:45:14 2010
@@ -271,6 +271,33 @@
     >>> c | d                       # union:  max(c[x], d[x])
     Counter({'a': 3, 'b': 2})
 
+.. note::
+
+   Counters were primarily designed to work with positive integers to represent
+   running counts; however, care was taken to not unnecessarily preclude use
+   cases needing other types or negative values.  To help with those use cases,
+   this section documents the minimum range and type restrictions.
+
+   * The :class:`Counter` class itself is a dictionary subclass with no
+     restrictions on its keys and values.  The values are intended to be numbers
+     representing counts, but you *could* store anything in the value field.
+
+   * The :meth:`most_common` method requires only that the values be orderable.
+
+   * For in-place operations such as ``c[key] += 1``, the value type need only
+     support addition and subtraction.  So fractions, floats, and decimals would
+     work and negative values are supported.  The same is also true for
+     :meth:`update` and :meth:`subtract` which allow negative and zero values
+     for both inputs and outputs.
+
+   * The multiset methods are designed only for use cases with positive values.
+     The inputs may be negative or zero, but only outputs with positive values
+     are created.  There are no type restrictions, but the value type needs to
+     support support addition, subtraction, and comparison.
+
+   * The :meth:`elements` method requires integer counts.  It ignores zero and
+     negative counts.
+
 .. seealso::
 
     * `Counter class <http://code.activestate.com/recipes/576611/>`_