From f77beacf015e9bf8762e9b9a9a631396b05d4d9a Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Tue, 1 Feb 2022 22:18:11 -0600 Subject: Fix minor details in the Counter docs (GH-31029) --- Doc/library/collections.rst | 13 ++++++++++--- Lib/collections/__init__.py | 4 ++++ 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index b8a717d..b97bc42 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -271,7 +271,7 @@ For example:: .. versionadded:: 3.1 .. versionchanged:: 3.7 As a :class:`dict` subclass, :class:`Counter` - Inherited the capability to remember insertion order. Math operations + inherited the capability to remember insertion order. Math operations on *Counter* objects also preserve order. Results are ordered according to when an element is first encountered in the left operand and then by the order encountered in the right operand. @@ -366,19 +366,26 @@ Several mathematical operations are provided for combining :class:`Counter` objects to produce multisets (counters that have counts greater than zero). Addition and subtraction combine counters by adding or subtracting the counts of corresponding elements. Intersection and union return the minimum and -maximum of corresponding counts. Each operation can accept inputs with signed +maximum of corresponding counts. Equality and inclusion compare +corresponding counts. Each operation can accept inputs with signed counts, but the output will exclude results with counts of zero or less. +.. doctest:: + >>> c = Counter(a=3, b=1) >>> d = Counter(a=1, b=2) >>> c + d # add two counters together: c[x] + d[x] Counter({'a': 4, 'b': 3}) >>> c - d # subtract (keeping only positive counts) Counter({'a': 2}) - >>> c & d # intersection: min(c[x], d[x]) # doctest: +SKIP + >>> c & d # intersection: min(c[x], d[x]) Counter({'a': 1, 'b': 1}) >>> c | d # union: max(c[x], d[x]) Counter({'a': 3, 'b': 2}) + >>> c == d # equality: c[x] == d[x] + False + >>> c <= d # inclusion: c[x] <= d[x] + False Unary addition and subtraction are shortcuts for adding an empty counter or subtracting from an empty counter. diff --git a/Lib/collections/__init__.py b/Lib/collections/__init__.py index fa8b309..264435c 100644 --- a/Lib/collections/__init__.py +++ b/Lib/collections/__init__.py @@ -736,6 +736,10 @@ class Counter(dict): # To strip negative and zero counts, add-in an empty counter: # c += Counter() # + # Results are ordered according to when an element is first + # encountered in the left operand and then by the order + # encountered in the right operand. + # # When the multiplicities are all zero or one, multiset operations # are guaranteed to be equivalent to the corresponding operations # for regular sets. -- cgit v0.12