net-imap 0.5.6 → 0.5.9

data/lib/net/imap/sequence_set.rb

@@ -18,21 +18,9 @@ module Net
     #
     # == Creating sequence sets
     #
-    # 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"
-    #
     # 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, a Set (containing only numbers or <tt>*</tt>), or an
+    # another SequenceSet, 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)
@@ -48,30 +36,114 @@ module Net
     #     set = Net::IMAP::SequenceSet.new(1, 2, 3..7, 5, 6..10, 2048, 1024)
     #     set.valid_string  #=> "1:10,55,1024:2048"
     #
-    # Use ::[] with one or more arguments to create a frozen SequenceSet.  An
-    # invalid (empty) set cannot be created with ::[].
+    # 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,55,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,55,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+, <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.
+    # 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 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.
+    # 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 <tt>O(lg
+    # n)</tt> 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 convert #string to its normalized form.  To
-    # preserve #string order while modifying a set, use #append, #string=, or
-    # #replace.
+    # 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.
     #
     # == Using <tt>*</tt>
     #
@@ -108,11 +180,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:*"]
@@ -149,6 +225,7 @@ module Net
     # * ::new: Creates a new mutable sequence set, which may be empty (invalid).
     # * ::try_convert: Calls +to_sequence_set+ on an object and verifies that
     #   the result is a SequenceSet.
+    # * Net::IMAP::SequenceSet(): Coerce an input using ::try_convert or ::new.
     # * ::empty: Returns a frozen empty (invalid) SequenceSet.
     # * ::full: Returns a frozen SequenceSet containing every possible number.
     #
@@ -174,14 +251,13 @@ module Net
     #
     # <i>Set membership:</i>
     # - #include? (aliased as #member?):
-    #   Returns whether a given object (nz-number, range, or <tt>*</tt>) is
-    #   contained by the set.
+    #   Returns whether a given element 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 in sorted set:</i>
     # - #[] (aliased as #slice): Returns the number or consecutive subset at a
@@ -239,15 +315,19 @@ module Net
     # 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.
     #
@@ -258,17 +338,17 @@ module Net
     #
     # These methods always update #string to be fully sorted and coalesced.
     #
-    # - #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
+    # - #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+.
+    # - #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 a given object to the set, appending it to the existing
+    # - #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
@@ -279,13 +359,14 @@ module Net
     # 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+.
     #
@@ -318,20 +399,22 @@ module Net
       class << self
 
         # :call-seq:
-        #   SequenceSet[*values] -> valid frozen sequence set
+        #   SequenceSet[*inputs] -> valid frozen sequence set
+        #
+        # Returns a frozen SequenceSet, constructed from +inputs+.
         #
-        # Returns a frozen SequenceSet, constructed from +values+.
+        # 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.
+        #
+        # Related: ::new, Net::IMAP::SequenceSet(), ::try_convert
         def [](first, *rest)
           if rest.empty?
-            if first.is_a?(SequenceSet) && first.frozen? && first.valid?
-              first
-            else
-              new(first).validate.freeze
-            end
+            set = try_convert(first)&.validate
+            set&.frozen? ? set : (set&.dup || new(first).validate).freeze
           else
             new(first).merge(*rest).validate.freeze
           end
@@ -346,6 +429,8 @@ module Net
         #
         # If +obj.to_sequence_set+ doesn't return a SequenceSet, an exception is
         # raised.
+        #
+        # Related: Net::IMAP::SequenceSet(), ::new, ::[]
         def try_convert(obj)
           return obj if obj.is_a?(SequenceSet)
           return nil unless obj.respond_to?(:to_sequence_set)
@@ -364,20 +449,85 @@ module Net
       end
 
       # Create a new SequenceSet object from +input+, which may be another
-      # SequenceSet, an IMAP formatted +sequence-set+ string, a number, a
-      # range, <tt>:*</tt>, or an enumerable of these.
-      #
-      # Use ::[] to create a frozen (non-empty) SequenceSet.
+      # SequenceSet, an IMAP formatted +sequence-set+ string, a non-zero 32 bit
+      # unsigned integer, a range, <tt>:*</tt>, a Set of numbers or <tt>*</tt>,
+      # an object that responds to +to_sequence_set+ (such as SearchResult) or
+      # an Array 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"
+      #
+      # With no arguments (or +nil+) 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"
+      #
+      # When +input+ is a SequenceSet, ::new behaves the same as calling #dup on
+      # that 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
+      #
+      # === Alternative set creation methods
+      #
+      # * ::[] returns a frozen validated (non-empty) SequenceSet, without
+      #   allocating a new object when the input is already a valid frozen
+      #   SequenceSet.
+      # * Net::IMAP::SequenceSet() coerces an input to SequenceSet, without
+      #   allocating a new object when the input is already a SequenceSet.
+      # * ::try_convert calls +to_sequence_set+ on inputs that support it and
+      #   returns +nil+ for inputs that don't.
+      # * ::empty and ::full both return frozen singleton sets which can be
+      #   combined with set operations (#|, #&, #^, #-, etc) to make new sets.
+      #
+      # See SequenceSet@Creating+sequence+sets.
       def initialize(input = nil) input ? replace(input) : clear end
 
       # Removes all elements and returns self.
-      def clear; @tuples, @string = [], nil; self end
+      def clear
+        modifying! # redundant check, to normalize the error message for JRuby
+        @tuples, @string = [], nil
+        self
+      end
 
       # Replace the contents of the set with the contents of +other+ and returns
       # +self+.
       #
-      # +other+ may be another SequenceSet, or it may be an IMAP +sequence-set+
-      # string, a number, a range, <tt>*</tt>, or an enumerable of these.
+      # +other+ may be another SequenceSet or any other object that would be
+      # accepted by ::new.
       def replace(other)
         case other
         when SequenceSet then initialize_dup(other)
@@ -427,11 +577,13 @@ module Net
         if str.nil?
           clear
         else
+          modifying! # redundant check, to normalize the error message for JRuby
           str = String.try_convert(str) or raise ArgumentError, "not a string"
           tuples = str_to_tuples str
           @tuples, @string = [], -str
           tuples_add tuples
         end
+        str
       end
 
       # Returns the \IMAP +sequence-set+ string representation, or an empty
@@ -491,8 +643,9 @@ module Net
 
       # :call-seq: self === other -> true | false | nil
       #
-      # Returns whether +other+ is contained within the set.  Returns +nil+ if a
-      # StandardError is raised while converting +other+ to a comparable type.
+      # Returns whether +other+ is contained within the set.  +other+ may be any
+      # object that would be accepted by ::new.  Returns +nil+ if StandardError
+      # is raised while converting +other+ to a comparable type.
       #
       # Related: #cover?, #include?, #include_star?
       def ===(other)
@@ -506,12 +659,12 @@ module Net
       # Returns whether +other+ is contained within the set.  +other+ may be any
       # object that would be accepted by ::new.
       #
-      # Related: #===, #include?, #include_star?
+      # Related: #===, #include?, #include_star?, #intersect?
       def cover?(other) input_to_tuples(other).none? { !include_tuple?(_1) } end
 
       # Returns +true+ when a given number or range is in +self+, and +false+
-      # otherwise.  Returns +false+ unless +number+ is an Integer, Range, or
-      # <tt>*</tt>.
+      # otherwise.  Returns +nil+ when +number+ isn't a valid SequenceSet
+      # element (Integer, Range, <tt>*</tt>, +sequence-set+ string).
       #
       #     set = Net::IMAP::SequenceSet["5:10,100,111:115"]
       #     set.include? 1      #=> false
@@ -519,8 +672,8 @@ module Net
       #     set.include? 11..20 #=> false
       #     set.include? 100    #=> true
       #     set.include? 6      #=> true, covered by "5:10"
-      #     set.include? 4..9   #=> true, covered by "5:10"
-      #     set.include? "4:9"  #=> true, strings are parsed
+      #     set.include? 6..9   #=> true, covered by "5:10"
+      #     set.include? "6:9"  #=> true, strings are parsed
       #     set.include? 4..9   #=> false, intersection is not sufficient
       #     set.include? "*"    #=> false, use #limit to re-interpret "*"
       #     set.include? -1     #=> false, -1 is interpreted as "*"
@@ -529,11 +682,14 @@ module Net
       #     set.include? :*     #=> true
       #     set.include? "*"    #=> true
       #     set.include? -1     #=> true
-      #     set.include? 200..  #=> true
-      #     set.include? 100..  #=> false
+      #     set.include?(200..) #=> true
+      #     set.include?(100..) #=> false
       #
-      # Related: #include_star?, #cover?, #===
-      def include?(element) include_tuple? input_to_tuple element end
+      # Related: #include_star?, #cover?, #===, #intersect?
+      def include?(element)
+        tuple = input_to_tuple element rescue nil
+        !!include_tuple?(tuple) if tuple
+      end
 
       alias member? include?
 
@@ -546,7 +702,7 @@ module Net
       #     Net::IMAP::SequenceSet["5:10"].intersect? "7,9,11" #=> true
       #     Net::IMAP::SequenceSet["5:10"].intersect? "11:33"  #=> false
       #
-      # Related: #intersection, #disjoint?
+      # Related: #intersection, #disjoint?, #cover?, #include?
       def intersect?(other)
         valid? && input_to_tuples(other).any? { intersect_tuple? _1 }
       end
@@ -563,26 +719,53 @@ 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) => 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) => 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]
+      # :call-seq: minmax(star: :*) => [min, max] or nil
       #
       # Returns a 2-element array containing the minimum and maximum numbers in
-      # +self+, or +nil+ when the set is empty.
+      # +self+, or +nil+ when the set is empty.  +star+ is handled the same way
+      # as by #min and #max.
+      #
+      # Related: #min, #max
       def minmax(star: :*); [min(star: star), max(star: star)] unless empty? end
 
       # Returns false when the set is empty.
@@ -602,14 +785,19 @@ module Net
       # Returns a new sequence set that has every number in the +other+ object
       # added.
       #
-      # +other+ may be any object that would be accepted by ::new: a non-zero 32
-      # bit unsigned integer, range, <tt>sequence-set</tt> formatted string,
-      # another sequence set, or an enumerable containing any of these.
+      # +other+ may be any object that would be accepted by ::new.
       #
       #     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 :|
@@ -621,14 +809,22 @@ module Net
       # Returns a new sequence set built by duplicating this set and removing
       # every number that appears in +other+.
       #
-      # +other+ may be any object that would be accepted by ::new: a non-zero 32
-      # bit unsigned integer, range, <tt>sequence-set</tt> formatted string,
-      # another sequence set, or an enumerable containing any of these.
+      # +other+ may be any object that would be accepted by ::new.
       #
       #     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>~rhs - ~lhs</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 :-
 
@@ -639,14 +835,22 @@ module Net
       # Returns a new sequence set containing only the numbers common to this
       # set and +other+.
       #
-      # +other+ may be any object that would be accepted by ::new: a non-zero 32
-      # bit unsigned integer, range, <tt>sequence-set</tt> formatted string,
-      # another sequence set, or an enumerable containing any of these.
+      # +other+ may be any object that would be accepted by ::new.
       #
       #     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
@@ -659,16 +863,22 @@ module Net
       # Returns a new sequence set containing numbers that are exclusive between
       # this set and +other+.
       #
-      # +other+ may be any object that would be accepted by ::new: a non-zero 32
-      # bit unsigned integer, range, <tt>sequence-set</tt> formatted string,
-      # another sequence set, or an enumerable containing any of these.
+      # +other+ may be any object that would be accepted by ::new.
       #
       #     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:
@@ -685,21 +895,30 @@ 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
+      # SequenceSet@Ordered+and+Normalized+sets.
+      #
+      # Related: #add?, #merge, #union, #append
+      def add(element)
+        modifying! # short-circuit before input_to_tuple
+        tuple_add input_to_tuple element
         normalize!
       end
       alias << add
@@ -708,9 +927,13 @@ 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)
-        modifying!
-        tuple = input_to_tuple object
+      #
+      # 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
         entry = tuple_to_str tuple
         string unless empty? # write @string before tuple_add
         tuple_add tuple
@@ -718,19 +941,20 @@ module Net
         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)
+        modifying! # short-circuit before include?
+        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+.
       #
@@ -738,8 +962,9 @@ module Net
       # many elements at once.
       #
       # Related: #delete?, #delete_at, #subtract, #difference
-      def delete(object)
-        tuple_subtract input_to_tuple object
+      def delete(element)
+        modifying! # short-circuit before input_to_tuple
+        tuple_subtract input_to_tuple element
         normalize!
       end
 
@@ -775,8 +1000,9 @@ 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)
+        modifying! # short-circuit before input_to_tuple
+        tuple = input_to_tuple element
         if tuple.first == tuple.last
           return unless include_tuple? tuple
           tuple_subtract tuple
@@ -816,37 +1042,33 @@ module Net
       #
       # Related: #slice, #delete_at, #delete, #delete?, #subtract, #difference
       def slice!(index, length = nil)
+        modifying! # short-circuit before slice
         deleted = slice(index, length) and subtract deleted
         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.
       #
-      # #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)
+        modifying! # short-circuit before input_to_tuples
+        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.
       #
       # Related: #difference
-      def subtract(*objects)
-        tuples_subtract input_to_tuples objects
+      def subtract(*sets)
+        tuples_subtract input_to_tuples sets
         normalize!
       end
 
@@ -858,21 +1080,21 @@ module Net
       # This is useful when the given order is significant, for example in a
       # ESEARCH response to IMAP#sort.
       #
+      # See SequenceSet@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,
+      # SequenceSet@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.
       #
-      # The returned elements will be sorted 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"].elements
       #   #=> [2, 5..9, 11..12, :*]
       #
@@ -883,15 +1105,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,
+      # SequenceSet@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 sorted 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
@@ -903,7 +1123,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, SequenceSet@Ordered+and+Normalized+sets.
       #
       #   Net::IMAP::SequenceSet["2,5:9,6,12:11"].numbers
       #   #=> [2, 5, 6, 7, 8, 9, 11, 12]
@@ -935,6 +1155,8 @@ module Net
       # no sorting, deduplication, or coalescing.  When #string is in its
       # normalized form, this will yield the same values as #each_element.
       #
+      # See SequenceSet@Ordered+and+Normalized+sets.
+      #
       # Related: #entries, #each_element
       def each_entry(&block) # :yields: integer or range or :*
         return to_enum(__method__) unless block_given?
@@ -945,7 +1167,7 @@ module Net
       # 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, SequenceSet@Ordered+and+Normalized+sets.
       #
       # Related: #elements, #each_entry
       def each_element # :yields: integer or range or :*
@@ -1239,20 +1461,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+.
@@ -1270,6 +1548,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
@@ -1284,6 +1563,7 @@ module Net
       #
       # Related: #limit
       def limit!(max:)
+        modifying! # short-circuit, and normalize the error message for JRuby
         star = include_star?
         max  = to_tuple_int(max)
         tuple_subtract [max + 1, STAR_INT]
@@ -1298,6 +1578,7 @@ module Net
       #
       # Related: #complement
       def complement!
+        modifying! # short-circuit, and normalize the error message for JRuby
         return replace(self.class.full) if empty?
         return clear                    if full?
         flat = @tuples.flat_map { [_1 - 1, _2 + 1] }
@@ -1311,6 +1592,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 SequenceSet@Ordered+and+Normalized+sets.
       #
       #   Net::IMAP::SequenceSet["1:5,3:7,10:9,10:11"].normalize
       #   #=> Net::IMAP::SequenceSet["1:7,9:11"]
@@ -1323,21 +1605,24 @@ module Net
       end
 
       # Resets #string to be sorted, deduplicated, and coalesced.  Returns
-      # +self+.
+      # +self+.  See SequenceSet@Ordered+and+Normalized+sets.
       #
       # Related: #normalize, #normalized_string
       def normalize!
+        modifying! # redundant check, to normalize the error message for JRuby
         @string = nil
         self
       end
 
       # 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 SequenceSet@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(",")
@@ -1353,7 +1638,15 @@ module Net
         end
       end
 
-      # Returns self
+      ##
+      # :method: to_sequence_set
+      # :call-seq: to_sequence_set -> self
+      #
+      # Returns +self+
+      #
+      # Related: ::try_convert
+
+      # :nodoc: (work around rdoc bug)
       alias to_sequence_set itself
 
       # Unstable API: currently for internal use only (Net::IMAP#validate_data)
@@ -1367,6 +1660,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:
@@ -1374,6 +1679,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)
@@ -1381,35 +1687,35 @@ module Net
       end
 
       def initialize_dup(other)
+        modifying! # redundant check, to normalize the error message for JRuby
         @tuples = other.tuples.map(&:dup)
         @string = other.string&.-@
         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 Set         then obj.map      { [to_tuple_int(_1)] * 2 }
-        when Array       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]
+          raise DataFormatError, "expected nz-number, range, '*', Set, Array; " \
+                                 "got %p" % [set]
         end
       end