net-imap 0.4.10 → 0.5.8

data/lib/net/imap/sequence_set.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set" unless defined?(::Set)
+
 module Net
   class IMAP
 
@@ -14,13 +16,6 @@ module Net
     # receive a SequenceSet as an argument, for example IMAP#search, IMAP#fetch,
     # and IMAP#store.
     #
-    # == EXPERIMENTAL API
-    #
-    # SequenceSet is currently experimental.  Only two methods, ::[] and
-    # #valid_string, are considered stable.  Although the API isn't expected to
-    # change much, any other methods may be removed or changed without
-    # deprecation.
-    #
     # == Creating sequence sets
     #
     # SequenceSet.new with no arguments creates an empty sequence set.  Note
@@ -37,7 +32,8 @@ module Net
     #
     # SequenceSet.new may receive a single optional argument: a non-zero 32 bit
     # unsigned integer, a range, a <tt>sequence-set</tt> formatted string,
-    # another sequence set, or an enumerable containing any of these.
+    # another sequence set, a Set (containing only numbers or <tt>*</tt>), or an
+    # Array containing any of these (array inputs may be nested).
     #
     #     set = Net::IMAP::SequenceSet.new(1)
     #     set.valid_string  #=> "1"
@@ -60,18 +56,20 @@ module Net
     #     set = Net::IMAP::SequenceSet[1, 2, [3..7, 5], 6..10, 2048, 1024]
     #     set.valid_string  #=> "1:10,55,1024:2048"
     #
-    # == Normalized form
+    # == Ordered and Normalized sets
     #
-    # When a sequence set is created with a single String value, that #string
-    # representation is preserved.  SequenceSet's internal representation
-    # implicitly sorts all entries, de-duplicates numbers, and coalesces
-    # adjacent or overlapping ranges.  Most enumeration methods and offset-based
-    # methods use this normalized representation.  Most modification methods
-    # will convert #string to its normalized form.
+    # Sometimes the order of the set's members is significant, such as with the
+    # +ESORT+, <tt>CONTEXT=SORT</tt>, and +UIDPLUS+ extensions.  So, when a
+    # sequence set is created by the parser or with a single string value, that
+    # #string representation is preserved.
     #
-    # In some cases the order of the string representation is significant, such
-    # as the +ESORT+, <tt>CONTEXT=SORT</tt>, and +UIDPLUS+ extensions.  Use
-    # #entries or #each_entry to enumerate the set in its original order.  To
+    # Internally, SequenceSet stores a normalized representation which sorts all
+    # entries, de-duplicates numbers, and coalesces adjacent or overlapping
+    # ranges.  Most methods use this normalized representation to achieve
+    # <tt>O(lg n)</tt> porformance.  Use #entries or #each_entry to enumerate
+    # the set in its original order.
+    #
+    # Most modification methods convert #string to its normalized form.  To
     # preserve #string order while modifying a set, use #append, #string=, or
     # #replace.
     #
@@ -110,11 +108,15 @@ module Net
     # When a set includes <tt>*</tt>, some methods may have surprising behavior.
     #
     # For example, #complement treats <tt>*</tt> as its own number.  This way,
-    # the #intersection of a set and its #complement will always be empty.
-    # This is not how an \IMAP server interprets the set: it will convert
-    # <tt>*</tt> to either the number of messages in the mailbox or +UIDNEXT+,
-    # as appropriate.  And there _will_ be overlap between a set and its
-    # complement after #limit is applied to each:
+    # the #intersection of a set and its #complement will always be empty.  And
+    # <tt>*</tt> is sorted as greater than any other number in the set.  This is
+    # not how an \IMAP server interprets the set: it will convert <tt>*</tt> 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 <tt>*</tt> 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:*"]
@@ -164,7 +166,7 @@ module Net
     # - #===:
     #   Returns whether a given object is fully contained within +self+, or
     #   +nil+ if the object cannot be converted to a compatible type.
-    # - #cover? (aliased as #===):
+    # - #cover?:
     #   Returns whether a given object is fully contained within +self+.
     # - #intersect? (aliased as #overlap?):
     #   Returns whether +self+ and a given object have any common elements.
@@ -176,39 +178,50 @@ module Net
     #
     # <i>Set membership:</i>
     # - #include? (aliased as #member?):
-    #   Returns whether a given object (nz-number, range, or <tt>*</tt>) is
+    #   Returns whether a given element (nz-number, range, or <tt>*</tt>) is
     #   contained by the set.
     # - #include_star?: Returns whether the set contains <tt>*</tt>.
     #
     # <i>Minimum and maximum value elements:</i>
-    # - #min: Returns the minimum number in the set.
-    # - #max: Returns the maximum number in the set.
-    # - #minmax: Returns the minimum and maximum numbers in the set.
+    # - #min: Returns one or more of the lowest numbers in the set.
+    # - #max: Returns one or more of the highest numbers in the set.
+    # - #minmax: Returns the lowest and highest numbers in the set.
     #
-    # <i>Accessing value by offset:</i>
+    # <i>Accessing value by offset in sorted set:</i>
     # - #[] (aliased as #slice): Returns the number or consecutive subset at a
-    #   given offset or range of offsets.
-    # - #at: Returns the number at a given offset.
-    # - #find_index: Returns the given number's offset in the set
+    #   given offset or range of offsets in the sorted set.
+    # - #at: Returns the number at a given offset in the sorted set.
+    # - #find_index: Returns the given number's offset in the sorted set.
+    #
+    # <i>Accessing value by offset in ordered entries</i>
+    # - #ordered_at: Returns the number at a given offset in the ordered entries.
+    # - #find_ordered_index: Returns the index of the given number's first
+    #   occurrence in entries.
     #
     # <i>Set cardinality:</i>
     # - #count (aliased as #size): Returns the count of numbers in the set.
+    #   Duplicated numbers are not counted.
     # - #empty?: Returns whether the set has no members.  \IMAP syntax does not
     #   allow empty sequence sets.
     # - #valid?: Returns whether the set has any members.
     # - #full?: Returns whether the set contains every possible value, including
     #   <tt>*</tt>.
     #
+    # <i>Denormalized properties:</i>
+    # - #has_duplicates?: Returns whether the ordered entries repeat any
+    #   numbers.
+    # - #count_duplicates: Returns the count of repeated numbers in the ordered
+    #   entries.
+    # - #count_with_duplicates: Returns the count of numbers in the ordered
+    #   entries, including any repeated numbers.
+    #
     # === Methods for Iterating
     #
+    # <i>Normalized (sorted and coalesced):</i>
     # - #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
@@ -218,47 +231,70 @@ module Net
     #   ranges into all of their contained numbers.
     # - #to_set: Returns a Set containing all of the #numbers in the set.
     #
+    # <i>Order preserving:</i>
+    # - #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_ordered_number: Yields each number in the ordered entries and
+    #   returns +self+.
+    #
     # === Methods for \Set Operations
     # These methods do not modify +self+.
     #
     # - #| (aliased as #union and #+): Returns a new set combining all members
-    #   from +self+ with all members from the other object.
+    #   from +self+ with all members from the other set.
     # - #& (aliased as #intersection): Returns a new set containing all members
-    #   common to +self+ and the other object.
+    #   common to +self+ and the other set.
     # - #- (aliased as #difference): Returns a copy of +self+ with all members
-    #   in the other object removed.
+    #   in the other set removed.
     # - #^ (aliased as #xor): Returns a new set containing all members from
-    #   +self+ and the other object except those common to both.
+    #   +self+ and the other set except those common to both.
     # - #~ (aliased as #complement): Returns a new set containing all members
     #   that are not in +self+
+    # - #above: Return a copy of +self+ which only contains numbers above a
+    #   given number.
+    # - #below: Return a copy of +self+ which only contains numbers below a
+    #   given value.
     # - #limit: Returns a copy of +self+ which has replaced <tt>*</tt> with a
     #   given maximum value and removed all members over that maximum.
     #
     # === Methods for Assigning
     # These methods add or replace elements in +self+.
     #
-    # - #add (aliased as #<<): Adds a given object to the set; returns +self+.
-    # - #add?: If the given object is not an element in the set, adds it and
+    # <i>Normalized (sorted and coalesced):</i>
+    #
+    # These methods always update #string to be fully sorted and coalesced.
+    #
+    # - #add (aliased as #<<): Adds a given element to the set; returns +self+.
+    # - #add?: If the given element is not fully included the set, adds it and
     #   returns +self+; otherwise, returns +nil+.
-    # - #merge: Merges multiple elements into the set; returns +self+.
-    # - #append: Adds a given object to the set, appending it to the existing
+    # - #merge: Adds all members of the given sets into this set; returns +self+.
+    # - #complement!: Replaces the contents of the set with its own #complement.
+    #
+    # <i>Order preserving:</i>
+    #
+    # These methods _may_ cause #string to not be sorted or coalesced.
+    #
+    # - #append: Adds the given entry to the set, appending it to the existing
     #   string, and returns +self+.
     # - #string=: Assigns a new #string value and replaces #elements to match.
     # - #replace: Replaces the contents of the set with the contents
     #   of a given object.
-    # - #complement!: Replaces the contents of the set with its own #complement.
     #
     # === Methods for Deleting
-    # These methods remove elements from +self+.
+    # These methods remove elements from +self+, and update #string to be fully
+    # sorted and coalesced.
     #
     # - #clear: Removes all elements in the set; returns +self+.
-    # - #delete: Removes a given object from the set; returns +self+.
-    # - #delete?: If the given object is an element in the set, removes it and
+    # - #delete: Removes a given element from the set; returns +self+.
+    # - #delete?: If the given element is included in the set, removes it and
     #   returns it; otherwise, returns +nil+.
     # - #delete_at: Removes the number at a given offset.
     # - #slice!: Removes the number or consecutive numbers at a given offset or
     #   range of offsets.
-    # - #subtract: Removes each given object from the set; returns +self+.
+    # - #subtract: Removes all members of the given sets from this set; returns
+    #   +self+.
     # - #limit!: Replaces <tt>*</tt> with a given maximum value and removes all
     #   members over that maximum; returns +self+.
     #
@@ -286,25 +322,24 @@ module Net
 
       # valid inputs for "*"
       STARS     = [:*, ?*, -1].freeze
-      private_constant :STAR_INT, :STARS
-
-      COERCIBLE = ->{ _1.respond_to? :to_sequence_set }
-      ENUMABLE  = ->{ _1.respond_to?(:each) && _1.respond_to?(:empty?) }
-      private_constant :COERCIBLE, :ENUMABLE
+      private_constant :STARS
 
       class << self
 
         # :call-seq:
-        #   SequenceSet[*values] -> valid frozen sequence set
+        #   SequenceSet[*inputs] -> valid frozen sequence set
         #
-        # Returns a frozen SequenceSet, constructed from +values+.
+        # Returns a frozen SequenceSet, constructed from +inputs+.
+        #
+        # When only a single valid frozen SequenceSet is given, that same set is
+        # returned.
         #
         # An empty SequenceSet is invalid and will raise a DataFormatError.
         #
         # Use ::new to create a mutable or empty SequenceSet.
         def [](first, *rest)
           if rest.empty?
-            if first.is_a?(SequenceSet) && set.frozen? && set.valid?
+            if first.is_a?(SequenceSet) && first.frozen? && first.valid?
               first
             else
               new(first).validate.freeze
@@ -325,7 +360,7 @@ module Net
         # raised.
         def try_convert(obj)
           return obj if obj.is_a?(SequenceSet)
-          return nil unless respond_to?(:to_sequence_set)
+          return nil unless obj.respond_to?(:to_sequence_set)
           obj = obj.to_sequence_set
           return obj if obj.is_a?(SequenceSet)
           raise DataFormatError, "invalid object returned from to_sequence_set"
@@ -389,6 +424,10 @@ module Net
       # Related: #valid_string, #normalized_string, #to_s
       def string; @string ||= normalized_string if valid? end
 
+      # Returns an array with #normalized_string when valid and an empty array
+      # otherwise.
+      def deconstruct; valid? ? [normalized_string] : [] end
+
       # Assigns a new string to #string and resets #elements to match.  It
       # cannot be set to an empty string—assign +nil+ or use #clear instead.
       # The string is validated but not normalized.
@@ -536,26 +575,52 @@ module Net
         empty? || input_to_tuples(other).none? { intersect_tuple? _1 }
       end
 
-      # :call-seq: max(star: :*) => integer or star or nil
+      # :call-seq:
+      #   max(star: :*) => integer or star or nil
+      #   max(count, star: :*) => SequenceSet
       #
       # Returns the maximum value in +self+, +star+ when the set includes
       # <tt>*</tt>, or +nil+ when the set is empty.
-      def max(star: :*)
-        (val = @tuples.last&.last) && val == STAR_INT ? star : val
+      #
+      # When +count+ is given, a new SequenceSet is returned, containing only
+      # the last +count+ numbers.  An empty SequenceSet is returned when +self+
+      # is empty.  (+star+ is ignored when +count+ is given.)
+      #
+      # Related: #min, #minmax, #slice
+      def max(count = nil, star: :*)
+        if count
+          slice(-[count, size].min..) || remain_frozen_empty
+        elsif (val = @tuples.last&.last)
+          val == STAR_INT ? star : val
+        end
       end
 
-      # :call-seq: min(star: :*) => integer or star or nil
+      # :call-seq:
+      #   min(star: :*) => integer or star or nil
+      #   min(count, star: :*) => SequenceSet
       #
       # Returns the minimum value in +self+, +star+ when the only value in the
       # set is <tt>*</tt>, or +nil+ when the set is empty.
-      def min(star: :*)
-        (val = @tuples.first&.first) && val == STAR_INT ? star : val
+      #
+      # When +count+ is given, a new SequenceSet is returned, containing only
+      # the first +count+ numbers.  An empty SequenceSet is returned when +self+
+      # is empty.  (+star+ is ignored when +count+ is given.)
+      #
+      # Related: #max, #minmax, #slice
+      def min(count = nil, star: :*)
+        if count
+          slice(0...count) || remain_frozen_empty
+        elsif (val = @tuples.first&.first)
+          val != STAR_INT ? val : star
+        end
       end
 
       # :call-seq: minmax(star: :*) => nil or [integer, integer or star]
       #
       # Returns a 2-element array containing the minimum and maximum numbers in
       # +self+, or +nil+ when the set is empty.
+      #
+      # Related: #min, #max
       def minmax(star: :*); [min(star: star), max(star: star)] unless empty? end
 
       # Returns false when the set is empty.
@@ -582,7 +647,14 @@ module Net
       #     Net::IMAP::SequenceSet["1:5"] | 2 | [4..6, 99]
       #     #=> Net::IMAP::SequenceSet["1:6,99"]
       #
-      # Related: #add, #merge
+      # Related: #add, #merge, #&, #-, #^, #~
+      #
+      # ==== Set identities
+      #
+      # <tt>lhs | rhs</tt> is equivalent to:
+      # * <tt>rhs | lhs</tt> (commutative)
+      # * <tt>~(~lhs & ~rhs)</tt> (De Morgan's Law)
+      # * <tt>(lhs & rhs) ^ (lhs ^ rhs)</tt>
       def |(other) remain_frozen dup.merge other end
       alias :+    :|
       alias union :|
@@ -601,7 +673,17 @@ module Net
       #     Net::IMAP::SequenceSet[1..5] - 2 - 4 - 6
       #     #=> Net::IMAP::SequenceSet["1,3,5"]
       #
-      # Related: #subtract
+      # Related: #subtract, #|, #&, #^, #~
+      #
+      # ==== Set identities
+      #
+      # <tt>lhs - rhs</tt> is equivalent to:
+      # * <tt>~r - ~l</tt>
+      # * <tt>lhs & ~rhs</tt>
+      # * <tt>~(~lhs | rhs)</tt>
+      # * <tt>lhs & (lhs ^ rhs)</tt>
+      # * <tt>lhs ^ (lhs & rhs)</tt>
+      # * <tt>rhs ^ (lhs | rhs)</tt>
       def -(other) remain_frozen dup.subtract other end
       alias difference :-
 
@@ -619,7 +701,17 @@ module Net
       #     Net::IMAP::SequenceSet[1..5] & [2, 4, 6]
       #     #=> Net::IMAP::SequenceSet["2,4"]
       #
-      # <tt>(seqset & other)</tt> is equivalent to <tt>(seqset - ~other)</tt>.
+      # Related: #intersect?, #|, #-, #^, #~
+      #
+      # ==== Set identities
+      #
+      # <tt>lhs & rhs</tt> is equivalent to:
+      # * <tt>rhs & lhs</tt> (commutative)
+      # * <tt>~(~lhs | ~rhs)</tt> (De Morgan's Law)
+      # * <tt>lhs - ~rhs</tt>
+      # * <tt>lhs - (lhs - rhs)</tt>
+      # * <tt>lhs - (lhs ^ rhs)</tt>
+      # * <tt>lhs ^ (lhs - rhs)</tt>
       def &(other)
         remain_frozen dup.subtract SequenceSet.new(other).complement!
       end
@@ -639,9 +731,17 @@ module Net
       #     Net::IMAP::SequenceSet[1..5] ^ [2, 4, 6]
       #     #=> Net::IMAP::SequenceSet["1,3,5:6"]
       #
-      # <tt>(seqset ^ other)</tt> is equivalent to <tt>((seqset | other) -
-      # (seqset & other))</tt>.
-      def ^(other) remain_frozen (self | other).subtract(self & other) end
+      # Related: #|, #&, #-, #~
+      #
+      # ==== Set identities
+      #
+      # <tt>lhs ^ rhs</tt> is equivalent to:
+      # * <tt>rhs ^ lhs</tt> (commutative)
+      # * <tt>~lhs ^ ~rhs</tt>
+      # * <tt>(lhs | rhs) - (lhs & rhs)</tt>
+      # * <tt>(lhs - rhs) | (rhs - lhs)</tt>
+      # * <tt>(lhs ^ other) ^ (other ^ rhs)</tt>
+      def ^(other) remain_frozen (dup | other).subtract(self & other) end
       alias xor :^
 
       # :call-seq:
@@ -658,21 +758,29 @@ module Net
       #     ~Net::IMAP::SequenceSet["6:99,223:*"]
       #     #=> Net::IMAP::SequenceSet["1:5,100:222"]
       #
-      # Related: #complement!
+      # Related: #complement!, #|, #&, #-, #^
+      #
+      # ==== Set identities
+      #
+      # <tt>~set</tt> is equivalent to:
+      # * <tt>full - set</tt>, where "full" is Net::IMAP::SequenceSet.full
       def ~; remain_frozen dup.complement! end
       alias complement :~
 
       # :call-seq:
-      #   add(object)   -> self
+      #   add(element)   -> self
       #   self << other -> self
       #
       # Adds a range or number to the set and returns +self+.
       #
       # #string will be regenerated.  Use #merge to add many elements at once.
       #
-      # Related: #add?, #merge, #union
-      def add(object)
-        tuple_add input_to_tuple object
+      # Use #append to append new elements to #string.  See
+      # Net::IMAP@Ordered+and+Normalized+Sets.
+      #
+      # Related: #add?, #merge, #union, #append
+      def add(element)
+        tuple_add input_to_tuple element
         normalize!
       end
       alias << add
@@ -681,27 +789,33 @@ module Net
       #
       # 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.
-      def append(object)
-        tuple = input_to_tuple object
+      #
+      # See Net::IMAP@Ordered+and+Normalized+Sets.
+      #
+      # Related: #add, #merge, #union
+      def append(entry)
+        modifying!
+        tuple = input_to_tuple entry
         entry = tuple_to_str tuple
+        string unless empty? # write @string before tuple_add
         tuple_add tuple
-        @string = -(string ? "#{@string},#{entry}" : entry)
+        @string = -(@string ? "#{@string},#{entry}" : entry)
         self
       end
 
-      # :call-seq: add?(object) -> self or nil
+      # :call-seq: add?(element) -> self or nil
       #
       # Adds a range or number to the set and returns +self+.  Returns +nil+
-      # when the object is already included in the set.
+      # when the element is already included in the set.
       #
       # #string will be regenerated.  Use #merge to add many elements at once.
       #
       # Related: #add, #merge, #union, #include?
-      def add?(object)
-        add object unless include? object
+      def add?(element)
+        add element unless include? element
       end
 
-      # :call-seq: delete(object) -> self
+      # :call-seq: delete(element) -> self
       #
       # Deletes the given range or number from the set and returns +self+.
       #
@@ -709,8 +823,8 @@ module Net
       # many elements at once.
       #
       # Related: #delete?, #delete_at, #subtract, #difference
-      def delete(object)
-        tuple_subtract input_to_tuple object
+      def delete(element)
+        tuple_subtract input_to_tuple element
         normalize!
       end
 
@@ -746,8 +860,8 @@ module Net
       # #string will be regenerated after deletion.
       #
       # Related: #delete, #delete_at, #subtract, #difference, #disjoint?
-      def delete?(object)
-        tuple = input_to_tuple object
+      def delete?(element)
+        tuple = input_to_tuple element
         if tuple.first == tuple.last
           return unless include_tuple? tuple
           tuple_subtract tuple
@@ -791,33 +905,31 @@ module Net
         deleted
       end
 
-      # Merges all of the elements that appear in any of the +inputs+ into the
+      # Merges all of the elements that appear in any of the +sets+ into the
       # set, and returns +self+.
       #
-      # The +inputs+ may be any objects that would be accepted by ::new:
-      # non-zero 32 bit unsigned integers, ranges, <tt>sequence-set</tt>
-      # formatted strings, other sequence sets, or enumerables containing any of
-      # these.
+      # The +sets+ may be any objects that would be accepted by ::new: non-zero
+      # 32 bit unsigned integers, ranges, <tt>sequence-set</tt> formatted
+      # strings, other sequence sets, or enumerables containing any of these.
       #
-      # #string will be regenerated after all inputs have been merged.
+      # #string will be regenerated after all sets have been merged.
       #
       # Related: #add, #add?, #union
-      def merge(*inputs)
-        tuples_add input_to_tuples inputs
+      def merge(*sets)
+        tuples_add input_to_tuples sets
         normalize!
       end
 
-      # Removes all of the elements that appear in any of the given +objects+
-      # from the set, and returns +self+.
+      # Removes all of the elements that appear in any of the given +sets+ from
+      # the set, and returns +self+.
       #
-      # The +objects+ may be any objects that would be accepted by ::new:
-      # non-zero 32 bit unsigned integers, ranges, <tt>sequence-set</tt>
-      # formatted strings, other sequence sets, or enumerables containing any of
-      # these.
+      # The +sets+ may be any objects that would be accepted by ::new: non-zero
+      # 32 bit unsigned integers, ranges, <tt>sequence-set</tt> formatted
+      # strings, other sequence sets, or enumerables containing any of these.
       #
       # Related: #difference
-      def subtract(*objects)
-        tuples_subtract input_to_tuples objects
+      def subtract(*sets)
+        tuples_subtract input_to_tuples sets
         normalize!
       end
 
@@ -829,21 +941,21 @@ module Net
       # This is useful when the given order is significant, for example in a
       # ESEARCH response to IMAP#sort.
       #
+      # See Net::IMAP@Ordered+and+Normalized+Sets.
+      #
       # 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.
+      # #string is not.  <tt>*</tt> will sort last.  See #normalize,
+      # Net::IMAP@Ordered+and+Normalized+Sets.
       #
       # By itself, <tt>*</tt> translates to <tt>:*</tt>.  A range containing
       # <tt>*</tt> translates to an endless range.  Use #limit to translate both
       # cases to a maximum value.
       #
-      # If the original input was unordered or contains overlapping ranges, the
-      # returned ranges will be ordered and coalesced.
-      #
       #   Net::IMAP::SequenceSet["2,5:9,6,*,12:11"].elements
       #   #=> [2, 5..9, 11..12, :*]
       #
@@ -854,15 +966,13 @@ module Net
       # Returns an array of ranges
       #
       # The returned elements are sorted and coalesced, even when the input
-      # #string is not.  <tt>*</tt> will sort last.  See #normalize.
+      # #string is not.  <tt>*</tt> will sort last.  See #normalize,
+      # Net::IMAP@Ordered+and+Normalized+Sets.
       #
       # <tt>*</tt> translates to an endless range.  By itself, <tt>*</tt>
       # translates to <tt>:*..</tt>.  Use #limit to set <tt>*</tt> to a maximum
       # value.
       #
-      # The returned ranges will be ordered and coalesced, even when the input
-      # #string is not.  <tt>*</tt> will sort last.  See #normalize.
-      #
       #   Net::IMAP::SequenceSet["2,5:9,6,*,12:11"].ranges
       #   #=> [2..2, 5..9, 11..12, :*..]
       #   Net::IMAP::SequenceSet["123,999:*,456:789"].ranges
@@ -874,7 +984,7 @@ module Net
       # Returns a sorted array of all of the number values in the sequence set.
       #
       # The returned numbers are sorted and de-duplicated, even when the input
-      # #string is not.  See #normalize.
+      # #string is not.  See #normalize, Net::IMAP@Ordered+and+Normalized+Sets.
       #
       #   Net::IMAP::SequenceSet["2,5:9,6,12:11"].numbers
       #   #=> [2, 5, 6, 7, 8, 9, 11, 12]
@@ -902,23 +1012,23 @@ module Net
       # Yields each number or range in #string to the block and returns +self+.
       # Returns an enumerator when called without a block.
       #
-      # The entries are yielded in the same order they appear in #tring, with no
-      # sorting, deduplication, or coalescing.  When #string is in its
+      # The entries are yielded in the same order they appear in #string, with
+      # no sorting, deduplication, or coalescing.  When #string is in its
       # normalized form, this will yield the same values as #each_element.
       #
+      # See Net::IMAP@Ordered+and+Normalized+Sets.
+      #
       # Related: #entries, #each_element
       def each_entry(&block) # :yields: integer or range or :*
         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
+        each_entry_tuple do yield tuple_to_entry _1 end
       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.
+      # #string is not.  See #normalize, Net::IMAP@Ordered+and+Normalized+Sets.
       #
       # Related: #elements, #each_entry
       def each_element # :yields: integer or range or :*
@@ -929,6 +1039,16 @@ module Net
 
       private
 
+      def each_entry_tuple(&block)
+        return to_enum(__method__) unless block_given?
+        if @string
+          @string.split(",") do block.call str_to_tuple _1 end
+        else
+          @tuples.each(&block)
+        end
+        self
+      end
+
       def tuple_to_entry((min, max))
         if    min == STAR_INT then :*
         elsif max == STAR_INT then min..
@@ -960,19 +1080,36 @@ module Net
       # Returns an enumerator when called without a block (even if the set
       # contains <tt>*</tt>).
       #
-      # Related: #numbers
+      # Related: #numbers, #each_ordered_number
       def each_number(&block) # :yields: integer
         return to_enum(__method__) unless block_given?
         raise RangeError, '%s contains "*"' % [self.class] if include_star?
-        each_element do |elem|
-          case elem
-          when Range   then elem.each(&block)
-          when Integer then block.(elem)
-          end
-        end
+        @tuples.each do each_number_in_tuple _1, _2, &block end
         self
       end
 
+      # Yields each number in #entries to the block and returns self.
+      # If the set contains a <tt>*</tt>, RangeError will be raised.
+      #
+      # Returns an enumerator when called without a block (even if the set
+      # contains <tt>*</tt>).
+      #
+      # Related: #entries, #each_number
+      def each_ordered_number(&block)
+        return to_enum(__method__) unless block_given?
+        raise RangeError, '%s contains "*"' % [self.class] if include_star?
+        each_entry_tuple do each_number_in_tuple _1, _2, &block end
+      end
+
+      private def each_number_in_tuple(min, max, &block)
+        if    min == STAR_INT then yield :*
+        elsif min == max      then yield min
+        elsif max != STAR_INT then (min..max).each(&block)
+        else
+          raise RangeError, "#{SequenceSet} cannot enumerate range with '*'"
+        end
+      end
+
       # Returns a Set with all of the #numbers in the sequence set.
       #
       # If the set contains a <tt>*</tt>, RangeError will be raised.
@@ -984,8 +1121,10 @@ module Net
 
       # Returns the count of #numbers in the set.
       #
-      # If <tt>*</tt> and <tt>2**32 - 1</tt> (the maximum 32-bit unsigned
-      # integer value) are both in the set, they will only be counted once.
+      # <tt>*</tt> will be counted as <tt>2**32 - 1</tt> (the maximum 32-bit
+      # unsigned integer value).
+      #
+      # Related: #count_with_duplicates
       def count
         @tuples.sum(@tuples.count) { _2 - _1 } +
           (include_star? && include?(UINT32_MAX) ? -1 : 0)
@@ -993,33 +1132,87 @@ module Net
 
       alias size count
 
-      # Returns the index of +number+ in the set, or +nil+ if +number+ isn't in
-      # the set.
+      # Returns the count of numbers in the ordered #entries, including any
+      # repeated numbers.
+      #
+      # <tt>*</tt> will be counted as <tt>2**32 - 1</tt> (the maximum 32-bit
+      # unsigned integer value).
+      #
+      # When #string is normalized, this behaves the same as #count.
+      #
+      # Related: #entries, #count_duplicates, #has_duplicates?
+      def count_with_duplicates
+        return count unless @string
+        each_entry_tuple.sum {|min, max|
+          max - min + ((max == STAR_INT && min != STAR_INT) ? 0 : 1)
+        }
+      end
+
+      # Returns the count of repeated numbers in the ordered #entries, the
+      # difference between #count_with_duplicates and #count.
+      #
+      # When #string is normalized, this is zero.
+      #
+      # Related: #entries, #count_with_duplicates, #has_duplicates?
+      def count_duplicates
+        return 0 unless @string
+        count_with_duplicates - count
+      end
+
+      # :call-seq: has_duplicates? -> true | false
+      #
+      # Returns whether or not the ordered #entries repeat any numbers.
       #
-      # Related: #[]
+      # Always returns +false+ when #string is normalized.
+      #
+      # Related: #entries, #count_with_duplicates, #count_duplicates?
+      def has_duplicates?
+        return false unless @string
+        count_with_duplicates != count
+      end
+
+      # Returns the (sorted and deduplicated) index of +number+ in the set, or
+      # +nil+ if +number+ isn't in the set.
+      #
+      # Related: #[], #at, #find_ordered_index
       def find_index(number)
         number = to_tuple_int number
-        each_tuple_with_index do |min, max, idx_min|
+        each_tuple_with_index(@tuples) do |min, max, idx_min|
           number <  min and return nil
           number <= max and return from_tuple_int(idx_min + (number - min))
         end
         nil
       end
 
+      # Returns the first index of +number+ in the ordered #entries, or
+      # +nil+ if +number+ isn't in the set.
+      #
+      # Related: #find_index
+      def find_ordered_index(number)
+        number = to_tuple_int number
+        each_tuple_with_index(each_entry_tuple) do |min, max, idx_min|
+          if min <= number && number <= max
+            return from_tuple_int(idx_min + (number - min))
+          end
+        end
+        nil
+      end
+
       private
 
-      def each_tuple_with_index
+      def each_tuple_with_index(tuples)
         idx_min = 0
-        @tuples.each do |min, max|
-          yield min, max, idx_min, (idx_max = idx_min + (max - min))
+        tuples.each do |min, max|
+          idx_max = idx_min + (max - min)
+          yield min, max, idx_min, idx_max
           idx_min = idx_max + 1
         end
         idx_min
       end
 
-      def reverse_each_tuple_with_index
+      def reverse_each_tuple_with_index(tuples)
         idx_max = -1
-        @tuples.reverse_each do |min, max|
+        tuples.reverse_each do |min, max|
           yield min, max, (idx_min = idx_max - (max - min)), idx_max
           idx_max = idx_min - 1
         end
@@ -1030,18 +1223,38 @@ module Net
 
       # :call-seq: at(index) -> integer or nil
       #
-      # Returns a number from +self+, without modifying the set.  Behaves the
-      # same as #[], except that #at only allows a single integer argument.
+      # Returns the number at the given +index+ in the sorted set, without
+      # modifying the set.
       #
-      # Related: #[], #slice
+      # +index+ is interpreted the same as in #[], except that #at only allows a
+      # single integer argument.
+      #
+      # Related: #[], #slice, #ordered_at
       def at(index)
+        lookup_number_by_tuple_index(tuples, index)
+      end
+
+      # :call-seq: ordered_at(index) -> integer or nil
+      #
+      # Returns the number at the given +index+ in the ordered #entries, without
+      # modifying the set.
+      #
+      # +index+ is interpreted the same as in #at (and #[]), except that
+      # #ordered_at applies to the ordered #entries, not the sorted set.
+      #
+      # Related: #[], #slice, #ordered_at
+      def ordered_at(index)
+        lookup_number_by_tuple_index(each_entry_tuple, index)
+      end
+
+      private def lookup_number_by_tuple_index(tuples, index)
         index = Integer(index.to_int)
         if index.negative?
-          reverse_each_tuple_with_index do |min, max, idx_min, idx_max|
+          reverse_each_tuple_with_index(tuples) do |min, max, idx_min, idx_max|
             idx_min <= index and return from_tuple_int(min + (index - idx_min))
           end
         else
-          each_tuple_with_index do |min, _, idx_min, idx_max|
+          each_tuple_with_index(tuples) do |min, _, idx_min, idx_max|
             index <= idx_max and return from_tuple_int(min + (index - idx_min))
           end
         end
@@ -1056,17 +1269,18 @@ module Net
       #    seqset[range]         -> sequence set or nil
       #    slice(range)          -> sequence set or nil
       #
-      # Returns a number or a subset from +self+, without modifying the set.
+      # Returns a number or a subset from the _sorted_ set, without modifying
+      # the set.
       #
       # When an Integer argument +index+ is given, the number at offset +index+
-      # is returned:
+      # in the sorted set is returned:
       #
       #     set = Net::IMAP::SequenceSet["10:15,20:23,26"]
       #     set[0]   #=> 10
       #     set[5]   #=> 15
       #     set[10]  #=> 26
       #
-      # If +index+ is negative, it counts relative to the end of +self+:
+      # If +index+ is negative, it counts relative to the end of the sorted set:
       #     set = Net::IMAP::SequenceSet["10:15,20:23,26"]
       #     set[-1]  #=> 26
       #     set[-3]  #=> 22
@@ -1078,13 +1292,14 @@ module Net
       #     set[11]  #=> nil
       #     set[-12] #=> nil
       #
-      # The result is based on the normalized set—sorted and de-duplicated—not
-      # on the assigned value of #string.
+      # The result is based on the sorted and de-duplicated set, not on the
+      # ordered #entries in #string.
       #
       #     set = Net::IMAP::SequenceSet["12,20:23,11:16,21"]
       #     set[0]   #=> 11
       #     set[-1]  #=> 23
       #
+      # Related: #at
       def [](index, length = nil)
         if    length              then slice_length(index, length)
         elsif index.is_a?(Range)  then slice_range(index)
@@ -1107,20 +1322,76 @@ module Net
       def slice_range(range)
         first = range.begin ||  0
         last  = range.end   || -1
-        last -= 1 if range.exclude_end? && range.end && last != STAR_INT
+        if range.exclude_end?
+          return remain_frozen_empty if last.zero?
+          last -= 1 if range.end && last != STAR_INT
+        end
         if (first * last).positive? && last < first
-          SequenceSet.empty
+          remain_frozen_empty
         elsif (min = at(first))
           max = at(last)
+          max = :* if max.nil?
           if    max == :*  then self & (min..)
           elsif min <= max then self & (min..max)
-          else                  SequenceSet.empty
+          else                  remain_frozen_empty
           end
         end
       end
 
       public
 
+      # Returns a copy of +self+ which only contains the numbers above +num+.
+      #
+      #   Net::IMAP::SequenceSet["5,10:22,50"].above(10) # to_s => "11:22,50"
+      #   Net::IMAP::SequenceSet["5,10:22,50"].above(20) # to_s => "21:22,50
+      #   Net::IMAP::SequenceSet["5,10:22,50"].above(30) # to_s => "50"
+      #
+      # This returns the same result as #intersection with <tt>((num+1)..)</tt>
+      # or #difference with <tt>(..num)</tt>.
+      #
+      #   Net::IMAP::SequenceSet["5,10:22,50"] & (11..)   # to_s => "11:22,50"
+      #   Net::IMAP::SequenceSet["5,10:22,50"] - (..10)   # to_s => "11:22,50"
+      #   Net::IMAP::SequenceSet["5,10:22,50"] & (21..)   # to_s => "21:22,50"
+      #   Net::IMAP::SequenceSet["5,10:22,50"] - (..20)   # to_s => "21:22,50"
+      #
+      # Related: #above, #-, #&
+      def above(num)
+        NumValidator.valid_nz_number?(num) or
+          raise ArgumentError, "not a valid sequence set number"
+        difference(..num)
+      end
+
+      # Returns a copy of +self+ which only contains numbers below +num+.
+      #
+      #   Net::IMAP::SequenceSet["5,10:22,50"].below(10) # to_s => "5"
+      #   Net::IMAP::SequenceSet["5,10:22,50"].below(20) # to_s => "5,10:19"
+      #   Net::IMAP::SequenceSet["5,10:22,50"].below(30) # to_s => "5,10:22"
+      #
+      # This returns the same result as #intersection with <tt>(..(num-1))</tt>
+      # or #difference with <tt>(num..)</tt>.
+      #
+      #   Net::IMAP::SequenceSet["5,10:22,50"] & (..9)    # to_s => "5"
+      #   Net::IMAP::SequenceSet["5,10:22,50"] - (10..)   # to_s => "5"
+      #   Net::IMAP::SequenceSet["5,10:22,50"] & (..19)   # to_s => "5,10:19"
+      #   Net::IMAP::SequenceSet["5,10:22,50"] - (20..)   # to_s => "5,10:19"
+      #
+      # When the set does not contain <tt>*</tt>, #below is identical to #limit
+      # with <tt>max: num - 1</tt>.  When the set does contain <tt>*</tt>,
+      # #below always drops it from the result.  Use #limit when the IMAP
+      # semantics for <tt>*</tt> must be enforced.
+      #
+      #   Net::IMAP::SequenceSet["5,10:22,50"].below(30)      # to_s => "5,10:22"
+      #   Net::IMAP::SequenceSet["5,10:22,50"].limit(max: 29) # to_s => "5,10:22"
+      #   Net::IMAP::SequenceSet["5,10:22,*"].below(30)       # to_s => "5,10:22"
+      #   Net::IMAP::SequenceSet["5,10:22,*"].limit(max: 29)  # to_s => "5,10:22,29"
+      #
+      # Related: #above, #-, #&, #limit
+      def below(num)
+        NumValidator.valid_nz_number?(num) or
+          raise ArgumentError, "not a valid sequence set number"
+        difference(num..)
+      end
+
       # Returns a frozen SequenceSet with <tt>*</tt> converted to +max+, numbers
       # and ranges over +max+ removed, and ranges containing +max+ converted to
       # end at +max+.
@@ -1138,6 +1409,7 @@ module Net
       #   Net::IMAP::SequenceSet["500:*"].limit(max: 37)
       #   #=> Net::IMAP::SequenceSet["37"]
       #
+      # Related: #limit!
       def limit(max:)
         max = to_tuple_int(max)
         if    empty?                      then self.class.empty
@@ -1179,6 +1451,7 @@ module Net
       #
       # The returned set's #string is sorted and deduplicated.  Adjacent or
       # overlapping elements will be merged into a single larger range.
+      # See Net::IMAP@Ordered+and+Normalized+Sets.
       #
       #   Net::IMAP::SequenceSet["1:5,3:7,10:9,10:11"].normalize
       #   #=> Net::IMAP::SequenceSet["1:7,9:11"]
@@ -1191,7 +1464,7 @@ module Net
       end
 
       # Resets #string to be sorted, deduplicated, and coalesced.  Returns
-      # +self+.
+      # +self+.  See Net::IMAP@Ordered+and+Normalized+Sets.
       #
       # Related: #normalize, #normalized_string
       def normalize!
@@ -1201,11 +1474,13 @@ module Net
 
       # Returns a normalized +sequence-set+ string representation, sorted
       # and deduplicated.  Adjacent or overlapping elements will be merged into
-      # a single larger range.  Returns +nil+ when the set is empty.
+      # a single larger range.  See Net::IMAP@Ordered+and+Normalized+Sets.
       #
       #   Net::IMAP::SequenceSet["1:5,3:7,10:9,10:11"].normalized_string
       #   #=> "1:7,9:11"
       #
+      # Returns +nil+ when the set is empty.
+      #
       # Related: #normalize!, #normalize
       def normalized_string
         @tuples.empty? ? nil : -@tuples.map { tuple_to_str _1 }.join(",")
@@ -1235,6 +1510,18 @@ module Net
         imap.__send__(:put_string, valid_string)
       end
 
+      # For YAML serialization
+      def encode_with(coder) # :nodoc:
+        # we can perfectly reconstruct from the string
+        coder['string'] = to_s
+      end
+
+      # For YAML deserialization
+      def init_with(coder) # :nodoc:
+        @tuples = []
+        self.string = coder['string']
+      end
+
       protected
 
       attr_reader :tuples # :nodoc:
@@ -1242,6 +1529,7 @@ module Net
       private
 
       def remain_frozen(set) frozen? ? set.freeze : set end
+      def remain_frozen_empty; frozen? ? SequenceSet.empty : SequenceSet.new end
 
       # frozen clones are shallow copied
       def initialize_clone(other)
@@ -1254,29 +1542,30 @@ module Net
         super
       end
 
-      def input_to_tuple(obj)
-        obj = input_try_convert obj
-        case obj
-        when *STARS, Integer then [int = to_tuple_int(obj), int]
-        when Range           then range_to_tuple(obj)
-        when String          then str_to_tuple(obj)
+      def input_to_tuple(entry)
+        entry = input_try_convert entry
+        case entry
+        when *STARS, Integer then [int = to_tuple_int(entry), int]
+        when Range           then range_to_tuple(entry)
+        when String          then str_to_tuple(entry)
         else
-          raise DataFormatError, "expected number or range, got %p" % [obj]
+          raise DataFormatError, "expected number or range, got %p" % [entry]
         end
       end
 
-      def input_to_tuples(obj)
-        obj = input_try_convert obj
-        case obj
-        when *STARS, Integer, Range then [input_to_tuple(obj)]
-        when String      then str_to_tuples obj
-        when SequenceSet then obj.tuples
-        when ENUMABLE    then obj.flat_map { input_to_tuples _1 }
+      def input_to_tuples(set)
+        set = input_try_convert set
+        case set
+        when *STARS, Integer, Range then [input_to_tuple(set)]
+        when String      then str_to_tuples set
+        when SequenceSet then set.tuples
+        when Set         then set.map      { [to_tuple_int(_1)] * 2 }
+        when Array       then set.flat_map { input_to_tuples _1 }
         when nil         then []
         else
           raise DataFormatError,
                 "expected nz-number, range, string, or enumerable; " \
-                "got %p" % [obj]
+                "got %p" % [set]
         end
       end
 
@@ -1284,8 +1573,7 @@ module Net
       # String, Set, Array, or... any type of object.
       def input_try_convert(input)
         SequenceSet.try_convert(input) ||
-          # Integer.try_convert(input) || # ruby 3.1+
-          input.respond_to?(:to_int) && Integer(input.to_int) ||
+          Integer.try_convert(input) ||
           String.try_convert(input) ||
           input
       end
@@ -1317,6 +1605,12 @@ module Net
           range.include?(min) || range.include?(max) || (min..max).cover?(range)
       end
 
+      def modifying!
+        if frozen?
+          raise FrozenError, "can't modify frozen #{self.class}: %p" % [self]
+        end
+      end
+
       def tuples_add(tuples)      tuples.each do tuple_add _1      end; self end
       def tuples_subtract(tuples) tuples.each do tuple_subtract _1 end; self end
 
@@ -1331,10 +1625,11 @@ module Net
       #   ---------??===lower==|--|==|----|===upper===|-- join until upper
       #   ---------??===lower==|--|==|--|=====upper===|-- join to upper
       def tuple_add(tuple)
+        modifying!
         min, max = tuple
         lower, lower_idx = tuple_gte_with_index(min - 1)
-        if    lower.nil?              then tuples << tuple
-        elsif (max + 1) < lower.first then tuples.insert(lower_idx, tuple)
+        if    lower.nil?              then tuples << [min, max]
+        elsif (max + 1) < lower.first then tuples.insert(lower_idx, [min, max])
         else  tuple_coalesce(lower, lower_idx, min, max)
         end
       end
@@ -1367,6 +1662,7 @@ module Net
       # -------??=====lower====|--|====|---|====upper====|-- 7. delete until
       # -------??=====lower====|--|====|--|=====upper====|-- 8. delete and trim
       def tuple_subtract(tuple)
+        modifying!
         min, max = tuple
         lower, idx = tuple_gte_with_index(min)
         if    lower.nil?        then nil # case 1.
@@ -1407,12 +1703,11 @@ module Net
       end
 
       def nz_number(num)
-        case num
-        when Integer, /\A[1-9]\d*\z/ then num = Integer(num)
-        else raise DataFormatError, "%p is not a valid nz-number" % [num]
-        end
-        NumValidator.ensure_nz_number(num)
-        num
+        String === num && !/\A[1-9]\d*\z/.match?(num) and
+          raise DataFormatError, "%p is not a valid nz-number" % [num]
+        NumValidator.ensure_nz_number Integer num
+      rescue TypeError # To catch errors from Integer()
+        raise DataFormatError, $!.message
       end
 
       # intentionally defined after the class implementation