✨ Add SequenceSet#min(count) and #max(count)

When `count` is given to either of these methods, a new `SequenceSet` is
returned, containing only the last `count` numbers.  An empty
SequenceSet is returned when `self` is empty.

The goal is for these to behave similarly to `Array#min`/`#max` when
they are given a count.

Author: nevans

lib/net/imap/sequence_set.rb

@@ -179,8 +179,8 @@ class IMAP
     # - #include_star?: Returns whether the set contains <tt>*</tt>.
     #
     # <i>Minimum and maximum value elements:</i>
-    # - #min: Returns the minimum number in the set.
-    # - #max: Returns the maximum number in the set.
+    # - #min: Returns one or more minimum numbers in the set.
+    # - #max: Returns one or more maximum numbers in the set.
     # - #minmax: Returns the minimum and maximum numbers in the set.
     #
     # <i>Accessing value by offset in sorted set:</i>
@@ -567,24 +567,44 @@ def disjoint?(other)
         empty? || input_to_tuples(other).none? { intersect_tuple? _1 }
       end
 
-      # :call-seq: max(star: :*) => integer or star or nil
+      # :call-seq:
+      #   max(star: :*) => integer or star or nil
+      #   max(count, star: :*) => SequenceSet
       #
       # Returns the maximum value in +self+, +star+ when the set includes
       # <tt>*</tt>, or +nil+ when the set is empty.
       #
-      # Related: #min, #minmax
-      def max(star: :*)
-        (val = @tuples.last&.last) && val == STAR_INT ? star : val
+      # When +count+ is given, a new SequenceSet is returned, containing only
+      # the last +count+ numbers.  An empty SequenceSet is returned when +self+
+      # is empty.  (+star+ is ignored when +count+ is given.)
+      #
+      # Related: #min, #minmax, #slice
+      def max(count = nil, star: :*)
+        if count
+          slice(-[count, size].min..) || remain_frozen_empty
+        elsif (val = @tuples.last&.last)
+          val == STAR_INT ? star : val
+        end
       end
 
-      # :call-seq: min(star: :*) => integer or star or nil
+      # :call-seq:
+      #   min(star: :*) => integer or star or nil
+      #   min(count, star: :*) => SequenceSet
       #
       # Returns the minimum value in +self+, +star+ when the only value in the
       # set is <tt>*</tt>, or +nil+ when the set is empty.
-      def min(star: :*)
-        (val = @tuples.first&.first) && val == STAR_INT ? star : val
       #
-      # Related: #max, #minmax
+      # When +count+ is given, a new SequenceSet is returned, containing only
+      # the first +count+ numbers.  An empty SequenceSet is returned when +self+
+      # is empty.  (+star+ is ignored when +count+ is given.)
+      #
+      # Related: #max, #minmax, #slice
+      def min(count = nil, star: :*)
+        if count
+          slice(0...count) || remain_frozen_empty
+        elsif (val = @tuples.first&.first)
+          val != STAR_INT ? val : star
+        end
       end
 
       # :call-seq: minmax(star: :*) => nil or [integer, integer or star]

test/net/imap/test_sequence_set.rb

@@ -82,6 +82,8 @@ def compare_to_reference_set(nums, set, seqset)
     end
   end
 
+  data "#min(count)",      {transform: ->{ _1.min(10)         }, }
+  data "#max(count)",      {transform: ->{ _1.max(10)         }, }
   data "#slice(length)",   {transform: ->{ _1.slice(0, 10)    }, }
   data "#slice(range)",    {transform: ->{ _1.slice(0...10)   }, }
   data "#slice => empty",  {transform: ->{ _1.slice(0...0)    }, }
@@ -580,6 +582,11 @@ def obj.to_sequence_set; 192_168.001_255 end
     assert_equal   3, SequenceSet.new("34:3").min
     assert_equal 345, SequenceSet.new("345,678").min
     assert_nil        SequenceSet.new.min
+    # with a count
+    assert_equal SequenceSet["3:6"],     SequenceSet["34:3"].min(4)
+    assert_equal SequenceSet["345"],     SequenceSet["345,678"].min(1)
+    assert_equal SequenceSet["345,678"], SequenceSet["345,678"].min(222)
+    assert_equal SequenceSet.empty,      SequenceSet.new.min(5)
   end
 
   test "#max" do
@@ -590,6 +597,11 @@ def obj.to_sequence_set; 192_168.001_255 end
     assert_equal nil, SequenceSet["345:*"].max(star: nil)
     assert_equal "*", SequenceSet["345:*"].max(star: "*")
     assert_nil SequenceSet.new.max(star: "ignored")
+    # with a count
+    assert_equal SequenceSet["31:34"],   SequenceSet["34:3"].max(4)
+    assert_equal SequenceSet["678"],     SequenceSet["345,678"].max(1)
+    assert_equal SequenceSet["345,678"], SequenceSet["345,678"].max(222)
+    assert_equal SequenceSet.empty,      SequenceSet.new.max(5)
   end
 
   test "#minmax" do