💥 Replace MessageSet with SequenceSet

[nevans]

There are some small differences in how MessageSet and SequenceSet behave. I'll add a backward incompatibility warning to the release notes.

But, although the following list of changes does seem long, I don't think the changes should break much (if any) existing code. Most of the changes are bugfixes or allow something new to work that didn't work before.

These are the differences that I've noted (there may be others):

Validation

SequenceSet does almost all of its validation during construction. The only invalid SequenceSet is an empty SequenceSet. MessageSet only validates when validate is called. In practice, this shouldn't make much of a difference.

MessageSet does not validate ranges at all. This can result in exceptions while sending the data, which might leave the connection in a weird state, with a partially sent command. It can also result in invalid ranges being sent, e.g: MessageSet.new("foo".."bar").

Invalid inputs to MessageSet

Fail to validate

Some values can be formatted by MessageSet, but raise an exception when validating. SequenceSet allows these:

• -1 by itself or in array (MessageSet only allows -1 to validate in a range)

Fail to validate or format

SequenceSet allows inputs that MessageSet doesn't:

• Set of numbers or nz-number formatted strings
• * can be input as a Symbol, in addition to a string or -1
• Range
  • begin and end may be nz-number formatted strings, :*, or "*"
  • beginless ranges => "1:#{range.end}"
  • endless ranges => "#{range.begin}:*"
• Net::IMAP::SearchResult implements #to_sequence_set

Buggy MessageSet formatting

The MessageSet handling for Net::IMAP::ThreadMember is not quite right, and it has no tests. ThreadMember#to_sequence_set has a test that covers these bugs, and I believe it has the correct behavior.

Since ranges are not validated, and integers aren't re-validated during formatting, zero and negative numbers in a range will be output directly. Only -1 is special-cased.

Invalid inputs to SequenceSet

SequenceSet raises an exception for backwards ranges, e.g: 5..3 or -1..55. While these are syntactically similar to IMAP sequence-set, the semantics are very different:

• In IMAP, the order is insignificant, for both membership and order within the set, so 5:3 is the same as 3,4,5
• In Ruby, the order is significant, so (5..3).to_a is empty.

Normalization

Normalized form is semantically equivalent, except when the order of entries is significant.

• MessageSet outputs everything you give it in the same order it was given.
• SequenceSet preserves the form for a simple string input. When the input is more complex (arrays, sets, etc), SequenceSet automatically normalizes the output string. It will be sorted, its numbers deduplicated, and its ranges coalesced.

Note that Net::IMAP::UIDPlusData still uses arrays instead of SequenceSet, and Net::IMAP::ResponseParser preserves any response's sequence-set order.