✨ Add ESearchResult#to_sequence_set

Similar to `SearchResult`, this method allows ESearchResult to be used
as an argument where a SequenceSet is required, such as with `#fetch`.

This also updates `ESearchResult#to_a` to use `to_sequence_set.numbers`.

Author: nevans

lib/net/imap/esearch_result.rb

@@ -39,12 +39,32 @@ def initialize(tag: nil, uid: nil, data: nil)
       # numbers or UIDs, +to_a+ returns that set as an array of integers.
       #
       # When both #all and #partial are +nil+, either because the server
-      # returned no results or because +ALL+ and +PARTIAL+ were not included in
-      # the IMAP#search +RETURN+ options, #to_a returns an empty array.
+      # returned no results or because neither +ALL+ or +PARTIAL+ were included
+      # in the IMAP#search +RETURN+ options, #to_a returns an empty array.
       #
       # Note that SearchResult also implements +to_a+, so it can be used without
       # checking if the server returned +SEARCH+ or +ESEARCH+ data.
-      def to_a; all&.numbers || partial&.to_a || [] end
+      #
+      # Related: #to_sequence_set, #all, #partial
+      def to_a; to_sequence_set.numbers end
+
+      # :call-seq: to_sequence_set -> SequenceSet or nil
+      #
+      # When either #all or #partial contains a SequenceSet of message sequence
+      # numbers or UIDs, +to_sequence_set+ returns that sequence set.
+      #
+      # When both #all and #partial are +nil+, either because the server
+      # returned no results or because neither +ALL+ or +PARTIAL+ were included
+      # in the IMAP#search +RETURN+ options, #to_sequence_set returns
+      # SequenceSet.empty.
+      #
+      # Note that SearchResult also implements +to_sequence_set+, so it can be
+      # used without checking if the server returned +SEARCH+ or +ESEARCH+ data.
+      #
+      # Related: #to_a, #all, #partial
+      def to_sequence_set
+        all || partial&.to_sequence_set || SequenceSet.empty
+      end
 
       ##
       # attr_reader: tag
@@ -161,6 +181,8 @@ def initialize(range:, results:)
         #
         # See also: ESearchResult#to_a.
         def to_a; results&.numbers || [] end
+
+        alias to_sequence_set results
       end
 
       # :call-seq: partial -> PartialResult or nil

test/net/imap/test_esearch_result.rb

@@ -8,6 +8,19 @@ class ESearchResultTest < Test::Unit::TestCase
   SequenceSet   = Net::IMAP::SequenceSet
   ExtensionData = Net::IMAP::ExtensionData
 
+  test "#to_sequence_set" do
+    esearch = ESearchResult.new(nil, true, [])
+    assert_equal SequenceSet.empty, esearch.to_sequence_set
+    esearch = ESearchResult.new(nil, false, [])
+    assert_equal SequenceSet.empty, esearch.to_sequence_set
+    esearch = ESearchResult.new(nil, false, [["ALL", SequenceSet["1,5:8"]]])
+    assert_equal SequenceSet[1, 5, 6, 7, 8], esearch.to_sequence_set
+    esearch = ESearchResult.new(nil, false, [
+      ["PARTIAL", ESearchResult::PartialResult[1..5, "1,5:8"]]
+    ])
+    assert_equal SequenceSet[1, 5, 6, 7, 8], esearch.to_sequence_set
+  end
+
   test "#to_a" do
     esearch = ESearchResult.new(nil, true, [])
     assert_equal [], esearch.to_a