Add subtract() method to collections.Counter() objects.

1 files changed, 11 insertions, 0 deletions

diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index a3bbc63..5a6f0de 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -230,6 +230,17 @@ For example::
             >>> Counter('abracadabra').most_common(3)
             [('a', 5), ('r', 2), ('b', 2)]
 
+   .. method:: subtract([iterable-or-mapping])
+
+      Elements are subtracted from an *iterable* or from another *mapping*
+      (or counter).  Like :meth:`dict.update` but subtracts counts instead
+      of replacing them.  Both inputs and outputs may be zero or negative.
+
+            >>> c = Counter(a=4, b=2, c=0, d=-2)
+            >>> d = Counter(a=1, b=2, c=3, d=4)
+            >>> c.subtract(d)
+            Counter({'a': 3, 'b': 0, 'c': -3, 'd': -6})
+
    The usual dictionary methods are available for :class:`Counter` objects
    except for two which work differently for counters.