✨ Add SequenceSet#entries for unsorted iteration

Unsorted access is especially important for using with the ESORT or
CONTEXT=SORT extensions.

Author: nevans

lib/net/imap/sequence_set.rb

@@ -186,10 +186,14 @@ class IMAP
     #
     # === Methods for Iterating
     #
-    # - #each_element: Yields each number and range in the set and returns
-    #   +self+.
-    # - #elements (aliased as #to_a):
-    #   Returns an Array of every number and range in the set.
+    # - #each_element: Yields each number and range in the set, sorted and
+    #   coalesced, and returns +self+.
+    # - #elements (aliased as #to_a): Returns an Array of every number and range
+    #   in the set, sorted and coalesced.
+    # - #each_entry: Yields each number and range in the set, unsorted and
+    #   without deduplicating numbers or coalescing ranges, and returns +self+.
+    # - #entries: Returns an Array of every number and range in the set,
+    #   unsorted and without deduplicating numbers or coalescing ranges.
     # - #each_range:
     #   Yields each element in the set as a Range and returns +self+.
     # - #ranges: Returns an Array of every element in the set, converting
@@ -788,7 +792,18 @@ def subtract(*objects)
         normalize!
       end
 
-      # Returns an array of ranges and integers.
+      # Returns an array of ranges and integers and <tt>:*</tt>.
+      #
+      # The entries are in the same order they appear in #string, with no
+      # sorting, deduplication, or coalescing.  When #string is in its
+      # normalized form, this will return the same result as #elements.
+      # This is useful when the given order is significant, for example in a
+      # ESEARCH response to IMAP#sort.
+      #
+      # Related: #each_entry, #elements
+      def entries; each_entry.to_a end
+
+      # Returns an array of ranges and integers and <tt>:*</tt>.
       #
       # The returned elements are sorted and coalesced, even when the input
       # #string is not.  <tt>*</tt> will sort last.  See #normalize.
@@ -855,22 +870,42 @@ def ranges; each_range.to_a end
       # Related: #elements, #ranges, #to_set
       def numbers; each_number.to_a end
 
-      # Yields each number or range in #elements to the block and returns self.
+      # Yields each number or range in #string to the block and returns +self+.
       # Returns an enumerator when called without a block.
       #
-      # Related: #elements
+      # The entries are yielded in the same order they appear in #tring, with no
+      # sorting, deduplication, or coalescing.  When #string is in its
+      # normalized form, this will yield the same values as #each_element.
+      #
+      # Related: #entries, #each_element
+      def each_entry(&block)
+        return to_enum(__method__) unless block_given?
+        return each_element(&block) unless @string
+        @string.split(",").each do yield tuple_to_entry str_to_tuple _1 end
+        self
+      end
+
+      # Yields each number or range (or <tt>:*</tt>) in #elements to the block
+      # and returns self.  Returns an enumerator when called without a block.
+      #
+      # The returned numbers are sorted and de-duplicated, even when the input
+      # #string is not.  See #normalize.
+      #
+      # Related: #elements, #each_entry
       def each_element # :yields: integer or range or :*
         return to_enum(__method__) unless block_given?
-        @tuples.each do |min, max|
-          if    min == STAR_INT then yield :*
-          elsif max == STAR_INT then yield min..
-          elsif min == max      then yield min
-          else                       yield min..max
-          end
-        end
+        @tuples.each do yield tuple_to_entry _1 end
         self
       end
 
+      private def tuple_to_entry((min, max))
+        if    min == STAR_INT then :*
+        elsif max == STAR_INT then min..
+        elsif min == max      then min
+        else                       min..max
+        end
+      end
+
       # Yields each range in #ranges to the block and returns self.
       # Returns an enumerator when called without a block.
       #

test/net/imap/test_sequence_set.rb

@@ -525,6 +525,7 @@ def test_inspect((expected, input, freeze))
   data "single number", {
     input:      "123456",
     elements:   [123_456],
+    entries:    [123_456],
     ranges:     [123_456..123_456],
     numbers:    [123_456],
     to_s:       "123456",
@@ -536,6 +537,7 @@ def test_inspect((expected, input, freeze))
   data "single range", {
     input:      "1:3",
     elements:   [1..3],
+    entries:    [1..3],
     ranges:     [1..3],
     numbers:    [1, 2, 3],
     to_s:       "1:3",
@@ -547,6 +549,7 @@ def test_inspect((expected, input, freeze))
   data "simple numbers list", {
     input:      "1,3,5",
     elements:   [   1,    3,    5],
+    entries:    [   1,    3,    5],
     ranges:     [1..1, 3..3, 5..5],
     numbers:    [   1,    3,    5],
     to_s:       "1,3,5",
@@ -558,6 +561,7 @@ def test_inspect((expected, input, freeze))
   data "numbers and ranges list", {
     input:      "1:3,5,7:9,46",
     elements:   [1..3,    5, 7..9,     46],
+    entries:    [1..3,    5, 7..9,     46],
     ranges:     [1..3, 5..5, 7..9, 46..46],
     numbers:    [1, 2, 3, 5, 7, 8, 9,  46],
     to_s:       "1:3,5,7:9,46",
@@ -569,6 +573,7 @@ def test_inspect((expected, input, freeze))
   data "just *", {
     input:      "*",
     elements:   [:*],
+    entries:    [:*],
     ranges:     [:*..],
     numbers:    RangeError,
     to_s:       "*",
@@ -580,6 +585,7 @@ def test_inspect((expected, input, freeze))
   data "range with *", {
     input:      "4294967000:*",
     elements:   [4_294_967_000..],
+    entries:    [4_294_967_000..],
     ranges:     [4_294_967_000..],
     numbers:    RangeError,
     to_s:       "4294967000:*",
@@ -591,6 +597,7 @@ def test_inspect((expected, input, freeze))
   data "* sorts last", {
     input:      "5,*,7",
     elements:   [5, 7, :*],
+    entries:    [5, :*, 7],
     ranges:     [5..5, 7..7, :*..],
     numbers:    RangeError,
     to_s:       "5,*,7",
@@ -602,6 +609,7 @@ def test_inspect((expected, input, freeze))
   data "out of order", {
     input:      "46,7:6,15,3:1",
     elements:   [1..3, 6..7, 15, 46],
+    entries:    [46, 6..7, 15, 1..3],
     ranges:     [1..3, 6..7, 15..15, 46..46],
     numbers:    [1, 2, 3, 6, 7, 15, 46],
     to_s:       "46,7:6,15,3:1",
@@ -613,6 +621,7 @@ def test_inspect((expected, input, freeze))
   data "adjacent", {
     input:      "1,2,3,5,7:9,10:11",
     elements:   [1..3, 5,    7..11],
+    entries:    [1, 2, 3, 5, 7..9, 10..11],
     ranges:     [1..3, 5..5, 7..11],
     numbers:    [1, 2, 3, 5, 7, 8, 9, 10, 11],
     to_s:       "1,2,3,5,7:9,10:11",
@@ -624,6 +633,7 @@ def test_inspect((expected, input, freeze))
   data "overlapping", {
     input:      "1:5,3:7,10:9,10:11",
     elements:   [1..7, 9..11],
+    entries:    [1..5, 3..7, 9..10, 10..11],
     ranges:     [1..7, 9..11],
     numbers:    [1, 2, 3, 4, 5, 6, 7,  9, 10, 11],
     to_s:       "1:5,3:7,10:9,10:11",
@@ -635,6 +645,7 @@ def test_inspect((expected, input, freeze))
   data "contained", {
     input:      "1:5,3:4,9:11,10",
     elements:   [1..5, 9..11],
+    entries:    [1..5, 3..4, 9..11, 10],
     ranges:     [1..5, 9..11],
     numbers:    [1, 2, 3, 4, 5, 9, 10, 11],
     to_s:       "1:5,3:4,9:11,10",
@@ -646,6 +657,7 @@ def test_inspect((expected, input, freeze))
   data "array", {
     input:      ["1:5,3:4", 9..11, "10", 99, :*],
     elements:   [1..5, 9..11, 99, :*],
+    entries:    [1..5, 9..11, 99, :*],
     ranges:     [1..5, 9..11, 99..99, :*..],
     numbers:    RangeError,
     to_s:       "1:5,9:11,99,*",
@@ -657,6 +669,7 @@ def test_inspect((expected, input, freeze))
   data "nested array", {
     input:      [["1:5", [3..4], [[[9..11, "10"], 99], :*]]],
     elements:   [1..5, 9..11, 99, :*],
+    entries:    [1..5, 9..11, 99, :*],
     ranges:     [1..5, 9..11, 99..99, :*..],
     numbers:    RangeError,
     to_s:       "1:5,9:11,99,*",
@@ -668,6 +681,7 @@ def test_inspect((expected, input, freeze))
   data "empty", {
     input:      nil,
     elements:   [],
+    entries:    [],
     ranges:     [],
     numbers:    [],
     to_s:       "",
@@ -680,6 +694,26 @@ def test_inspect((expected, input, freeze))
     assert_equal data[:elements], SequenceSet.new(data[:input]).elements
   end
 
+  test "#each_element" do |data|
+    seqset = SequenceSet.new(data[:input])
+    array = []
+    assert_equal seqset, seqset.each_element { array << _1 }
+    assert_equal data[:elements], array
+    assert_equal data[:elements], seqset.each_element.to_a
+  end
+
+  test "#entries" do |data|
+    assert_equal data[:entries], SequenceSet.new(data[:input]).entries
+  end
+
+  test "#each_entry" do |data|
+    seqset = SequenceSet.new(data[:input])
+    array = []
+    assert_equal seqset, seqset.each_entry { array << _1 }
+    assert_equal data[:entries], array
+    assert_equal data[:entries], seqset.each_entry.to_a
+  end
+
   test "#ranges" do |data|
     assert_equal data[:ranges], SequenceSet.new(data[:input]).ranges
   end