✨ Add SequenceSet#cardinality method

Unlike `#count`, `#cardinality` handles `*` the way you would expect a
set to handle it, as its own distinct member.

Author: nevans

lib/net/imap/sequence_set.rb

@@ -275,8 +275,10 @@ class IMAP
     #   occurrence in entries.
     #
     # <i>Set cardinality:</i>
-    # - #count (aliased as #size): Returns the count of numbers in the set.
-    #   Duplicated numbers are not counted.
+    # - #cardinality: Returns the number of distinct members in the set.
+    #   <tt>*</tt> is counted as its own entry, distinct from UINT32_MAX.
+    # - #count (aliased as #size): Returns the count of distinct numbers in the
+    #   set.  <tt>*</tt> is counted as UINT32_MAX.
     # - #empty?: Returns whether the set has no members.  \IMAP syntax does not
     #   allow empty sequence sets.
     # - #valid?: Returns whether the set has any members.
@@ -1336,28 +1338,71 @@ def each_ordered_number(&block)
       # Related: #elements, #ranges, #numbers
       def to_set; Set.new(numbers) end
 
+      # Returns the number of members in the set.
+      #
+      # Unlike #count, <tt>"*"</tt> is considered to be distinct from
+      # <tt>2³² - 1</tt> (the maximum 32-bit unsigned integer value).
+      #
+      #     set = Net::IMAP::SequenceSet[1..10]
+      #     set.count        #=> 10
+      #     set.cardinality  #=> 10
+      #
+      #     set = Net::IMAP::SequenceSet["4294967295,*"]
+      #     set.count        #=> 1
+      #     set.cardinality  #=> 2
+      #
+      #     set = Net::IMAP::SequenceSet[1..]
+      #     set.count        #=> 4294967295
+      #     set.cardinality  #=> 4294967296
+      #
+      # Related: #count, #count_with_duplicates
+      def cardinality = minmaxes.sum(@set_data.count) { _2 - _1 }
+
       # Returns the count of #numbers in the set.
       #
-      # <tt>*</tt> will be counted as <tt>2**32 - 1</tt> (the maximum 32-bit
-      # unsigned integer value).
+      # Unlike #cardinality, <tt>"*"</tt> is considered to be equal to
+      # <tt>2³² - 1</tt> (the maximum 32-bit unsigned integer value).
+      #
+      #     set = Net::IMAP::SequenceSet[1..10]
+      #     set.count        #=> 10
+      #     set.cardinality  #=> 10
+      #
+      #     set = Net::IMAP::SequenceSet["4294967295,*"]
+      #     set.count        #=> 1
+      #     set.cardinality  #=> 2
       #
-      # Related: #count_with_duplicates
+      #     set = Net::IMAP::SequenceSet[1..]
+      #     set.count        #=> 4294967295
+      #     set.cardinality  #=> 4294967296
+      #
+      # Related: #cardinality, #count_with_duplicates
       def count
-        minmaxes.sum(minmaxes.count) { _2 - _1 } +
-          (include_star? && include?(UINT32_MAX) ? -1 : 0)
+        cardinality + (include_star? && include?(UINT32_MAX) ? -1 : 0)
       end
 
       alias size count
 
       # Returns the count of numbers in the ordered #entries, including any
       # repeated numbers.
       #
-      # <tt>*</tt> will be counted as <tt>2**32 - 1</tt> (the maximum 32-bit
-      # unsigned integer value).
+      # When #string is normalized, this returns the same as #count.
+      # Like #count, <tt>"*"</tt> is be considered to be equal to
+      # <tt>2³² - 1</tt> (the maximum 32-bit unsigned integer value).
+      #
+      # In a range, <tt>"*"</tt> is _not_ considered a duplicate:
+      #     set = Net::IMAP::SequenceSet["4294967295:*"]
+      #     set.count_with_duplicates  #=> 1
+      #     set.count                  #=> 1
+      #     set.cardinality            #=> 2
       #
-      # When #string is normalized, this behaves the same as #count.
+      # In a separate entry, <tt>"*"</tt> _is_ considered a duplicate:
+      #     set = Net::IMAP::SequenceSet["4294967295,*"]
+      #     set.count_with_duplicates  #=> 2
+      #     set.count                  #=> 1
+      #     set.cardinality            #=> 2
       #
-      # Related: #entries, #count_duplicates, #has_duplicates?
+      # Related: #count, #cardinality, #count_duplicates, #has_duplicates?,
+      # #entries
       def count_with_duplicates
         return count unless @string
         each_entry_minmax.sum {|min, max|
@@ -1382,7 +1427,7 @@ def count_duplicates
       #
       # Always returns +false+ when #string is normalized.
       #
-      # Related: #entries, #count_with_duplicates, #count_duplicates?
+      # Related: #entries, #count_with_duplicates, #count_duplicates
       def has_duplicates?
         return false unless @string
         count_with_duplicates != count

test/net/imap/test_sequence_set.rb

@@ -441,6 +441,7 @@ def obj.to_sequence_set; 192_168.001_255 end
   test "#[start, length]" do
     assert_equal SequenceSet[10..99], SequenceSet.full[9, 90]
     assert_equal 90, SequenceSet.full[9, 90].count
+    assert_equal 90, SequenceSet.full[9, 90].cardinality
     assert_equal SequenceSet[1000..1099],
                  SequenceSet[1..100, 1000..1111][100, 100]
     assert_equal SequenceSet[11, 21, 31, 41],
@@ -1065,6 +1066,7 @@ def test_inspect((expected, input, freeze))
     to_s:       "4294967000:*",
     normalize:  "4294967000:*",
     count:      2**32 - 4_294_967_000,
+    cardinality: 2**32 - 4_294_967_000 + 1,
     complement: "1:4294966999",
   }, keep: true
 
@@ -1143,6 +1145,7 @@ def test_inspect((expected, input, freeze))
     normalize:  "2:*",
     count:      2**32 - 2,
     count_dups: 2**32 - 2,
+    cardinality: 2**32 - 1,
     complement: "1",
   }, keep: true
 
@@ -1329,6 +1332,15 @@ def assert_seqset_enum(expected, seqset, enum)
     assert_equal data[:count], SequenceSet.new(data[:input]).count
   end
 
+  test "#size" do |data|
+    assert_equal data[:count], SequenceSet.new(data[:input]).size
+  end
+
+  test "#cardinality" do |data|
+    expected = data[:cardinality] || data[:count]
+    assert_equal expected, SequenceSet.new(data[:input]).cardinality
+  end
+
   test "#count_with_duplicates" do |data|
     dups = data[:count_dups] || 0
     count = data[:count] + dups