From: Raymond Hettinger Date: Mon, 12 Apr 2010 21:47:14 +0000 (+0000) Subject: Add usage notes for collections.Counter() X-Git-Tag: v3.1.3rc1~953 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=4c4d3b1dddb249cd97aec976c5ef7b4ee84db60f;p=python Add usage notes for collections.Counter() --- diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index ebb35b1eab..b19af9c730 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -258,6 +258,33 @@ counts, but the output will exclude results with counts of zero or less. >>> 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 `_