From 44340e6d78536542efe9dff48c5789a2d3e530ce Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Mon, 12 Apr 2010 21:12:06 +0000 Subject: [PATCH] Add usage notes for collections.Counter(). --- Doc/library/collections.rst | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index 075b0157fa7..dd3e5a49f70 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -285,6 +285,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 `_