♻️ Coalesce entries in SequenceSet#append

You can build an ordered set from an enumarable input as simply as
`enum.inject(Net::IMAP::SequenceSet.new, &:append)`.  But, prior to this
change, that could easily give you very inefficient output, e.g: it
might return `9,1,2,3,4,5,6,7,8`.  With this change, the same input will
return `9,1:8`.

This also short-circuits whenever `@string` is `nil`, avoiding string
generation.  This significantly improves performance when the set
remains monotonically sorted.

Author: nevans

lib/net/imap/sequence_set.rb

@@ -954,16 +954,52 @@ def add(element)
       # Unlike #add, #merge, or #union, the new value is appended to #string.
       # This may result in a #string which has duplicates or is out-of-order.
       #
+      #    set = Net::IMAP::SequenceSet.new
+      #    set.append(1..2)  # => Net::IMAP::SequenceSet("1:2")
+      #    set.append(5)     # => Net::IMAP::SequenceSet("1:2,5")
+      #    set.append(4)     # => Net::IMAP::SequenceSet("1:2,5,4")
+      #    set.append(3)     # => Net::IMAP::SequenceSet("1:2,5,4,3")
+      #    set.append(2)     # => Net::IMAP::SequenceSet("1:2,5,4,3,2")
+      #
+      # If +entry+ is a string, it will be converted into normal form.
+      #
+      #    set = Net::IMAP::SequenceSet("4:5,1:2")
+      #    set.append("6:6") # => Net::IMAP::SequenceSet("4:5,1:2,6")
+      #    set.append("9:8") # => Net::IMAP::SequenceSet("4:5,1:2,6,8:9")
+      #
+      # If +entry+ adjacently follows the last entry, they will coalesced:
+      #    set = Net::IMAP::SequenceSet.new("2,1,9:10")
+      #    set.append(11..12) # => Net::IMAP::SequenceSet("2,1,9:12")
+      #
       # See SequenceSet@Ordered+and+Normalized+sets.
       #
       # Related: #add, #merge, #union
       def append(entry)
         modifying! # short-circuit before input_to_tuple
         tuple = input_to_tuple entry
+        adj = tuple.first - 1
+        if @string.nil? && (@tuples.empty? || tuples.last.last <= adj)
+          # append to elements or coalesce with last element
+          tuple_add tuple
+          return self
+        elsif @string.nil?
+          # generate string for out-of-order append
+          head, comma = normalized_string, ","
+        else
+          # @string already exists... maybe coalesce with last entry
+          head, comma, last_entry = @string.rpartition(",")
+          last_min, last_max = input_to_tuple last_entry
+          if last_max == adj
+            # coalesce with last entry
+            tuple[0] = last_min
+          else
+            # append to existing string
+            head, comma = @string, ","
+          end
+        end
         entry = tuple_to_str tuple
-        string unless empty? # write @string before tuple_add
         tuple_add tuple
-        @string = -(@string ? "#{@string},#{entry}" : entry)
+        @string = -"#{head}#{comma}#{entry}"
         self
       end
 

test/net/imap/test_sequence_set.rb

@@ -661,15 +661,27 @@ def obj.to_sequence_set; 192_168.001_255 end
     assert_equal "1,5",     SequenceSet.new("1").append("5").string
     assert_equal "*,1",     SequenceSet.new("*").append(1).string
     assert_equal "1:6,4:9", SequenceSet.new("1:6").append("4:9").string
-    assert_equal "1:4,5:*", SequenceSet.new("1:4").append(5..).string
     assert_equal "5:*,1:4", SequenceSet.new("5:*").append(1..4).string
+    # also works when previous string was not normal
+    assert_equal "3:1,8:9", SequenceSet.new("3:1").append("9:8").string
+    # coalesces adjacent entries (when previously normalized)
+    assert_equal "1:9",     SequenceSet.new("1:3").append("4:9").string
+    assert_equal "1:9",     SequenceSet.new("1:3").append("9:4").string
+    assert_equal "1:*",     SequenceSet.new("1:4").append(5..).string
+    # coalesces adjacent entries (when _not_ previously normalized)
+    assert_equal "1:9",     SequenceSet.new("3:1").append("4:9").string
+    assert_equal "4,1:*",   SequenceSet.new("4,1").append(2..).string
+    # assert_equal "3:1,4:9", SequenceSet.new("3:1").append("4:9").string
+    # a non-normal appended string will be normalized
+    assert_equal "1:6,4:9", SequenceSet.new("1:6").append("9:4").string
+    assert_equal "1:6,999", SequenceSet.new("1:6").append("999:999").string
     # also works from empty
     assert_equal "5,1",     SequenceSet.new.append(5).append(1).string
     # also works when *previously* input was non-strings
     assert_equal "*,1",     SequenceSet.new(:*).append(1).string
     assert_equal "1,5",     SequenceSet.new(1).append("5").string
     assert_equal "1:6,4:9", SequenceSet.new(1..6).append(4..9).string
-    assert_equal "1:4,5:*", SequenceSet.new(1..4).append(5..).string
+    assert_equal "1:*",     SequenceSet.new(1..4).append(5..).string
     assert_equal "5:*,1:4", SequenceSet.new(5..).append(1..4).string
   end