class Net::IMAP::SequenceSet

An IMAP sequence set is a set of message sequence numbers or unique identifier numbers (“UIDs”). It contains numbers and ranges of numbers. The numbers are all non-zero unsigned 32-bit integers and one special value ("*") that represents the largest value in the mailbox.

Certain types of IMAP responses will contain a SequenceSet, for example the data for a "MODIFIED" ResponseCode. Some IMAP commands may receive a SequenceSet as an argument, for example IMAP#search, IMAP#fetch, and IMAP#store.

Creating sequence sets

SequenceSet.new may receive a single optional argument: a non-zero 32 bit unsigned integer, a range, a sequence-set formatted string, another SequenceSet, a Set (containing only numbers or *), or an Array containing any of these (array inputs may be nested).

set = Net::IMAP::SequenceSet.new(1)
set.valid_string  #=> "1"
set = Net::IMAP::SequenceSet.new(1..100)
set.valid_string  #=> "1:100"
set = Net::IMAP::SequenceSet.new(1...100)
set.valid_string  #=> "1:99"
set = Net::IMAP::SequenceSet.new([1, 2, 5..])
set.valid_string  #=> "1:2,5:*"
set = Net::IMAP::SequenceSet.new("1,2,3:7,5,6:10,2048,1024")
set.valid_string  #=> "1,2,3:7,5,6:10,2048,1024"
set = Net::IMAP::SequenceSet.new(1, 2, 3..7, 5, 6..10, 2048, 1024)
set.valid_string  #=> "1:10,55,1024:2048"

SequenceSet.new with no arguments creates an empty sequence set. Note that an empty sequence set is invalid in the IMAP grammar.

set = Net::IMAP::SequenceSet.new
set.empty?        #=> true
set.valid?        #=> false
set.valid_string  #!> raises DataFormatError
set << 1..10
set.empty?        #=> false
set.valid?        #=> true
set.valid_string  #=> "1:10"

Using SequenceSet.new with another SequenceSet input behaves the same as calling dup on the other set. The input’s string will be preserved.

input = Net::IMAP::SequenceSet.new("1,2,3:7,5,6:10,2048,1024")
copy  = Net::IMAP::SequenceSet.new(input)
input.valid_string  #=> "1,2,3:7,5,6:10,2048,1024"
copy.valid_string   #=> "1,2,3:7,5,6:10,2048,1024"
copy2 = input.dup   # same as calling new with a SequenceSet input
copy ==     input   #=> true,  same set membership
copy.eql?   input   #=> true,  same string value
copy.equal? input   #=> false, different objects

copy.normalize!
copy.valid_string   #=> "1:10,1024,2048"
copy ==   input     #=> true,  same set membership
copy.eql? input     #=> false, different string value

copy << 999
copy.valid_string   #=> "1:10,999,1024,2048"
copy ==   input     #=> false, different set membership
copy.eql? input     #=> false, different string value

Use Net::IMAP::SequenceSet() to coerce a single (optional) input. A SequenceSet input is returned without duplication, even when frozen.

set = Net::IMAP::SequenceSet()
set.string   #=> nil
set.frozen?  #=> false

# String order is preserved
set = Net::IMAP::SequenceSet("1,2,3:7,5,6:10,2048,1024")
set.valid_string  #=> "1,2,3:7,5,6:10,2048,1024"
set.frozen?       #=> false

# Other inputs are normalized
set = Net::IMAP::SequenceSet([1, 2, [3..7, 5], 6..10, 2048, 1024])
set.valid_string  #=> "1:10,1024,2048"
set.frozen?       #=> false

unfrozen = set
frozen   = set.dup.freeze
unfrozen.equal? Net::IMAP::SequenceSet(unfrozen)  #=> true
frozen.equal?   Net::IMAP::SequenceSet(frozen)    #=> true

Use ::[] to coerce one or more arguments into a valid frozen SequenceSet. A valid frozen SequenceSet is returned directly, without allocating a new object. ::[] will not create an invalid (empty) set.

Net::IMAP::SequenceSet[]     #!> raises ArgumentError
Net::IMAP::SequenceSet[nil]  #!> raises DataFormatError
Net::IMAP::SequenceSet[""]   #!> raises DataFormatError

# String order is preserved
set = Net::IMAP::SequenceSet["1,2,3:7,5,6:10,2048,1024"]
set.valid_string  #=> "1,2,3:7,5,6:10,2048,1024"
set.frozen?       #=> true

# Other inputs are normalized
set = Net::IMAP::SequenceSet[1, 2, [3..7, 5], 6..10, 2048, 1024]
set.valid_string  #=> "1:10,1024,2048"
set.frozen?       #=> true

frozen   = set
unfrozen = set.dup
frozen.equal?   Net::IMAP::SequenceSet[frozen]    #=> true
unfrozen.equal? Net::IMAP::SequenceSet[unfrozen]  #=> false

Objects which respond to to_sequence_set (such as SearchResult and ThreadMember) can be coerced to a SequenceSet with ::new, ::try_convert, ::[], or Net::IMAP::SequenceSet.

search = imap.uid_search(["SUBJECT", "hello", "NOT", "SEEN"])
seqset = Net::IMAP::SequenceSet(search) - already_fetched
fetch  = imap.uid_fetch(seqset, "FAST")

Ordered and Normalized sets

Sometimes the order of the set’s members is significant, such as with the ESORT, CONTEXT=SORT, and UIDPLUS extensions. So, when a sequence set is created from a single string (such as by the parser), that string representation is preserved. Assigning a string with string= or replace will also preserve that string. Use each_entry, entries, or each_ordered_number to enumerate the entries in their string order. Hash equality (using eql?) is based on the string representation.

Internally, SequenceSet uses a normalized uint32 set representation which sorts and de-duplicates all numbers and coalesces adjacent or overlapping entries. Many methods use this sorted set representation for O(lg n) searches. Use each_element, elements, each_range, ranges, each_number, or numbers to enumerate the set in sorted order. Basic object equality (using ==) is based on set membership, without regard to entry order or string normalization.

Most modification methods reset string to its normalized form, so that entries and elements are identical. Use append to preserve entries order while modifying a set.

Non-normalized sets store both representations of the set, which can more than double memory usage. Very large sequence sets should avoid denormalizing methods (such as append) unless order is significant.

Using *

IMAP sequence sets may contain a special value "*", which represents the largest number in use. From seq-number in RFC9051 §9:

In the case of message sequence numbers, it is the number of messages in a non-empty mailbox. In the case of unique identifiers, it is the unique identifier of the last message in the mailbox or, if the mailbox is empty, the mailbox’s current UIDNEXT value.

When creating a SequenceSet, * may be input as -1, "*", :*, an endless range, or a range ending in -1. When converting to elements, ranges, or numbers, it will output as either :* or an endless range. For example:

Net::IMAP::SequenceSet["1,3,*"].to_a      #=> [1, 3, :*]
Net::IMAP::SequenceSet["1,234:*"].to_a    #=> [1, 234..]
Net::IMAP::SequenceSet[1234..-1].to_a     #=> [1234..]
Net::IMAP::SequenceSet[1234..].to_a       #=> [1234..]

Net::IMAP::SequenceSet[1234..].to_s       #=> "1234:*"
Net::IMAP::SequenceSet[1234..-1].to_s     #=> "1234:*"

Use limit to convert "*" to a maximum value. When a range includes "*", the maximum value will always be matched:

Net::IMAP::SequenceSet["9999:*"].limit(max: 25)
#=> Net::IMAP::SequenceSet["25"]

Surprising * behavior

When a set includes *, some methods may have surprising behavior.

For example, complement treats * as its own number. This way, the intersection of a set and its complement will always be empty. And * is sorted as greater than any other number in the set. This is not how an IMAP server interprets the set: it will convert * to the number of messages in the mailbox, the UID of the last message in the mailbox, or UIDNEXT, as appropriate. Several methods have an argument for how * should be interpreted.

But, for example, this means that there may be overlap between a set and its complement after limit is applied to each:

~Net::IMAP::SequenceSet["*"]  == Net::IMAP::SequenceSet[1..(2**32-1)]
~Net::IMAP::SequenceSet[1..5] == Net::IMAP::SequenceSet["6:*"]

set = Net::IMAP::SequenceSet[1..5]
(set & ~set).empty? => true

(set.limit(max: 4) & (~set).limit(max: 4)).to_a => [4]

When counting the number of numbers in a set, * will be counted except when UINT32_MAX is also in the set:

UINT32_MAX = 2**32 - 1
Net::IMAP::SequenceSet["*"].count                   => 1
Net::IMAP::SequenceSet[1..UINT32_MAX - 1, :*].count => UINT32_MAX

Net::IMAP::SequenceSet["1:*"].count                 => UINT32_MAX
Net::IMAP::SequenceSet[UINT32_MAX, :*].count        => 1
Net::IMAP::SequenceSet[UINT32_MAX..].count          => 1

What’s here?

SequenceSet provides methods for:

Methods for Creating a SequenceSet

Methods for Comparing

Comparison to another SequenceSet:

Comparison to objects which are convertible to SequenceSet:

Methods for Querying

These methods do not modify self.

Set membership:

Minimum and maximum value elements:

Accessing value by offset in sorted set:

Accessing value by offset in ordered entries

Set cardinality:

Denormalized properties:

Methods for Iterating

Normalized (sorted and coalesced):

Order preserving:

Methods for Set Operations

These methods do not modify self.

Methods for Assigning

These methods add or replace numbers in self.

Normalized (sorted and coalesced):

These methods always update string to be fully sorted and coalesced.

Order preserving:

These methods may cause string to not be sorted or coalesced.

Methods for Deleting

These methods remove numbers from self, and update string to be fully sorted and coalesced.

Methods for IMAP String Formatting