net-imap 0.4.22 → 0.6.3

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,30 +16,12 @@ 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
-    # 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, or an enumerable containing any of these.
+    # 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)
     #     set.valid_string  #=> "1"
@@ -52,30 +36,118 @@ 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,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.valid_string  #=> "1:10,1024,2048"
+    #     set.frozen?       #=> true
+    #
+    #     frozen   = set
+    #     unfrozen = set.dup
+    #     frozen.equal?   Net::IMAP::SequenceSet[frozen]    #=> true
+    #     unfrozen.equal? Net::IMAP::SequenceSet[unfrozen]  #=> false
+    #
+    # Objects which respond to +to_sequence_set+ (such as SearchResult and
+    # ThreadMember) can be coerced to a SequenceSet with ::new, ::try_convert,
+    # ::[], or Net::IMAP::SequenceSet.
+    #
+    #     search = imap.uid_search(["SUBJECT", "hello", "NOT", "SEEN"])
+    #     seqset = Net::IMAP::SequenceSet(search) - already_fetched
+    #     fetch  = imap.uid_fetch(seqset, "FAST")
     #
     # == Ordered and Normalized sets
     #
     # Sometimes the order of the set's members is significant, such as with the
     # +ESORT+, <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 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.
     #
-    # 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 reset #string to its #normalized form, so that
+    # #entries and #elements are identical.  Use #append to preserve #entries
+    # order while modifying a set.
     #
-    # Most modification methods convert #string to its normalized form.  To
-    # preserve #string order while modifying a set, use #append, #string=, or
-    # #replace.
+    # Non-normalized sets store both representations of the set, which can more
+    # than double memory usage.  Very large sequence sets should avoid
+    # denormalizing methods (such as #append) unless order is significant.
     #
     # == Using <tt>*</tt>
     #
@@ -111,12 +183,16 @@ 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:
+    # For example, #complement treats <tt>*</tt> as its own member.  This way,
+    # 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:*"]
@@ -127,7 +203,7 @@ module Net
     #   (set.limit(max: 4) & (~set).limit(max: 4)).to_a => [4]
     #
     # When counting the number of numbers in a set, <tt>*</tt> will be counted
-    # _except_ when UINT32_MAX is also in the set:
+    # as if it were equal to UINT32_MAX:
     #   UINT32_MAX = 2**32 - 1
     #   Net::IMAP::SequenceSet["*"].count                   => 1
     #   Net::IMAP::SequenceSet[1..UINT32_MAX - 1, :*].count => UINT32_MAX
@@ -136,6 +212,12 @@ module Net
     #   Net::IMAP::SequenceSet[UINT32_MAX, :*].count        => 1
     #   Net::IMAP::SequenceSet[UINT32_MAX..].count          => 1
     #
+    # Use #cardinality to count the set members wxth <tt>*</tt> counted as a
+    # distinct member:
+    #   Net::IMAP::SequenceSet[1..].cardinality            #=> UINT32_MAX + 1
+    #   Net::IMAP::SequenceSet[UINT32_MAX, :*].cardinality #=> 2
+    #   Net::IMAP::SequenceSet[UINT32_MAX..].cardinality   #=> 2
+    #
     # == What's here?
     #
     # SequenceSet provides methods for:
@@ -153,6 +235,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.
     #
@@ -178,14 +261,13 @@ module Net
     #
     # <i>Set membership:</i>
     # - #include? (aliased as #member?):
-    #   Returns whether a given element (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
@@ -199,8 +281,10 @@ module Net
     #   occurrence in entries.
     #
     # <i>Set cardinality:</i>
-    # - #count (aliased as #size): Returns the count of numbers in the set.
-    #   Duplicated numbers are not counted.
+    # - #cardinality: Returns the number of distinct members in the set.
+    #   <tt>*</tt> is counted as its own member, distinct from UINT32_MAX.
+    # - #count: Returns the count of distinct numbers in the set.
+    #   <tt>*</tt> is counted as equal to UINT32_MAX.
     # - #empty?: Returns whether the set has no members.  \IMAP syntax does not
     #   allow empty sequence sets.
     # - #valid?: Returns whether the set has any members.
@@ -208,12 +292,18 @@ module Net
     #   <tt>*</tt>.
     #
     # <i>Denormalized properties:</i>
+    # - #normalized?: Returns whether #entries are sorted, deduplicated, and
+    #   coalesced, and all #string entries are in normalized form.
     # - #has_duplicates?: Returns whether the ordered entries repeat any
     #   numbers.
-    # - #count_duplicates: Returns the count of repeated numbers in the ordered
-    #   entries.
+    # - #size: Returns the total size of all #entries, including repeated
+    #   numbers.  <tt>*</tt> is counted as its own member, distinct from
+    #   UINT32_MAX.
     # - #count_with_duplicates: Returns the count of numbers in the ordered
-    #   entries, including any repeated numbers.
+    #   #entries, including repeated numbers.  <tt>*</tt> is counted as
+    #   equal to UINT32_MAX.
+    # - #count_duplicates: Returns the count of repeated numbers in the ordered
+    #   #entries.  <tt>*</tt> is counted as equal to UINT32_MAX.
     #
     # === Methods for Iterating
     #
@@ -252,11 +342,15 @@ module Net
     #   +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+.
+    # These methods add or replace numbers in +self+.
     #
     # <i>Normalized (sorted and coalesced):</i>
     #
@@ -265,8 +359,12 @@ module Net
     # - #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: Adds all members of the given sets into this set; returns +self+.
-    # - #complement!: Replaces the contents of the set with its own #complement.
+    # - #merge: In-place set #union.  Adds all members of the given sets into
+    #   this set; returns +self+.
+    # - #complement!: In-place set #complement.  Replaces the contents of this
+    #   set with its own #complement; returns +self+.
+    # - #xor!: In-place +XOR+ operation.  Adds numbers that are unique to the
+    #   other set and removes numbers that are common to both; returns +self+.
     #
     # <i>Order preserving:</i>
     #
@@ -279,7 +377,7 @@ module Net
     #   of a given object.
     #
     # === Methods for Deleting
-    # These methods remove elements from +self+, and update #string to be fully
+    # These methods remove numbers from +self+, and update #string to be fully
     # sorted and coalesced.
     #
     # - #clear: Removes all elements in the set; returns +self+.
@@ -287,10 +385,12 @@ module Net
     # - #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.
+    # - #intersect!: In-place set #intersection.  Removes numbers that are not
+    #   in the given set; returns +self+.
     # - #slice!: Removes the number or consecutive numbers at a given offset or
     #   range of offsets.
-    # - #subtract: Removes all members of the given sets from this set; returns
-    #   +self+.
+    # - #subtract: In-place set #difference.  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,11 +418,24 @@ module Net
 
       # valid inputs for "*"
       STARS     = [:*, ?*, -1].freeze
-      private_constant :STAR_INT, :STARS
+      private_constant :STARS
 
-      COERCIBLE = ->{ _1.respond_to? :to_sequence_set }
-      ENUMABLE  = ->{ _1.respond_to?(:each) && _1.respond_to?(:empty?) }
-      private_constant :COERCIBLE, :ENUMABLE
+      INSPECT_MAX_LEN      = 512
+      INSPECT_TRUNCATE_LEN =  16
+      private_constant :INSPECT_MAX_LEN, :INSPECT_TRUNCATE_LEN
+
+      # /(,\d+){100}\z/ is shockingly slow on huge strings.
+      # /(,\d{0,10}){100}\z/ is ok, but ironically, Regexp.linear_time? is false.
+      #
+      # This unrolls all nested quantifiers.  It's much harder to read, but it's
+      # also the fastest out of all the versions I tested.
+      nz_uint32   = /[1-9](?:\d(?:\d(?:\d(?:\d(?:\d(?:\d(?:\d(?:\d(?:\d)?)?)?)?)?)?)?)?)?/
+      num_or_star = /#{nz_uint32}|\*/
+      entry       = /#{num_or_star}(?::#{num_or_star})?/
+      entries     = ([entry] * INSPECT_TRUNCATE_LEN).join(",")
+      INSPECT_ABRIDGED_HEAD_RE = /\A#{entries},/
+      INSPECT_ABRIDGED_TAIL_RE = /,#{entries}\z/
+      private_constant :INSPECT_ABRIDGED_HEAD_RE, :INSPECT_ABRIDGED_TAIL_RE
 
       class << self
 
@@ -337,13 +450,12 @@ module Net
         # 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
@@ -356,12 +468,14 @@ module Net
         # +to_sequence_set+, calls +obj.to_sequence_set+ and returns the result.
         # Otherwise returns +nil+.
         #
-        # If +obj.to_sequence_set+ doesn't return a SequenceSet, an exception is
-        # raised.
+        # If +obj.to_sequence_set+ doesn't return a SequenceSet or +nil+, 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)
-          obj = obj.to_sequence_set
+          return nil unless obj = obj.to_sequence_set
           return obj if obj.is_a?(SequenceSet)
           raise DataFormatError, "invalid object returned from to_sequence_set"
         end
@@ -376,23 +490,96 @@ 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.
-      def initialize(input = nil) input ? replace(input) : clear end
+      # 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,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)
+        @set_data = new_set_data
+        @string = nil
+        replace(input) unless input.nil?
+      end
 
       # Removes all elements and returns self.
-      def clear; @tuples, @string = [], nil; self end
+      def clear
+        modifying! # redundant check (normalizes the error message for JRuby)
+        set_data.clear
+        @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)
+        when SequenceSet then
+          modifying! # short circuit before doing any work
+          @set_data = other.dup_set_data
+          @string = other.instance_variable_get(:@string)
         when String      then self.string = other
         else                  clear; merge other
         end
@@ -421,39 +608,51 @@ module Net
       # If the set was created from a single string, it is not normalized.  If
       # the set is updated the string will be normalized.
       #
-      # Related: #valid_string, #normalized_string, #to_s
-      def string; @string ||= normalized_string if valid? end
+      # Related: #valid_string, #normalized_string, #to_s, #inspect
+      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.
+      # Assigns a new string to #string and resets #elements to match.
+      # Assigning +nil+ or an empty string are equivalent to calling #clear.
+      #
+      # Non-empty strings are validated but not normalized.
       #
-      # Use #add or #merge to add a string to an existing set.
+      # Use #add, #merge, or #append to add a string to an existing set.
       #
       # Related: #replace, #clear
-      def string=(str)
-        if str.nil?
+      def string=(input)
+        if input.nil?
           clear
+        elsif (str = String.try_convert(input))
+          modifying! # short-circuit before parsing the string
+          entries = each_parsed_entry(str).to_a
+          clear
+          if normalized_entries?(entries)
+            replace_minmaxes entries.map!(&:minmax)
+          else
+            add_minmaxes entries.map!(&:minmax)
+            @string = -str
+          end
         else
-          str = String.try_convert(str) or raise ArgumentError, "not a string"
-          tuples = str_to_tuples str
-          @tuples, @string = [], -str
-          tuples_add tuples
+          raise ArgumentError, "expected a string or nil, got #{input.class}"
         end
+        input
       end
 
       # Returns the \IMAP +sequence-set+ string representation, or an empty
       # string when the set is empty.  Note that an empty set is invalid in the
       # \IMAP syntax.
       #
-      # Related: #valid_string, #normalized_string, #to_s
+      # Related: #string, #valid_string, #normalized_string, #inspect
       def to_s; string || "" end
 
       # Freezes and returns the set.  A frozen SequenceSet is Ractor-safe.
       def freeze
         return self if frozen?
-        string
-        @tuples.each(&:freeze).freeze
+        freeze_set_data
         super
       end
 
@@ -475,7 +674,7 @@ module Net
       # Related: #eql?, #normalize
       def ==(other)
         self.class == other.class &&
-          (to_s == other.to_s || tuples == other.tuples)
+          (to_s == other.to_s || set_data == other.set_data)
       end
 
       # :call-seq: eql?(other) -> true or false
@@ -499,8 +698,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)
@@ -514,12 +714,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?
-      def cover?(other) input_to_tuples(other).none? { !include_tuple?(_1) } end
+      # Related: #===, #include?, #include_star?, #intersect?
+      def cover?(other) import_runs(other).none? { !include_run?(_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
@@ -527,8 +727,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 "*"
@@ -537,16 +737,19 @@ 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)
+        run = import_run element rescue nil
+        !!include_run?(run) if run
+      end
 
       alias member? include?
 
       # Returns +true+ when the set contains <tt>*</tt>.
-      def include_star?; @tuples.last&.last == STAR_INT end
+      def include_star?; max_num == STAR_INT end
 
       # Returns +true+ if the set and a given object have any common elements,
       # +false+ otherwise.
@@ -554,9 +757,9 @@ 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 }
+        valid? && import_runs(other).any? { intersect_run? _1 }
       end
       alias overlap? intersect?
 
@@ -568,39 +771,70 @@ module Net
       #
       # Related: #intersection, #intersect?
       def disjoint?(other)
-        empty? || input_to_tuples(other).none? { intersect_tuple? _1 }
+        empty? || import_runs(other).none? { intersect_run? _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
+          if cardinality <= count
+            frozen? ? self : dup
+          else
+            slice(-count..) || remain_frozen_empty
+          end
+        elsif (val = max_num)
+          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 = min_num)
+          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.
       def valid?; !empty? end
 
       # Returns true if the set contains no elements
-      def empty?; @tuples.empty? end
+      def empty?; runs.empty? end
 
       # Returns true if the set contains every possible element.
-      def full?; @tuples == [[1, STAR_INT]] end
+      def full?; set_data == FULL_SET_DATA end
 
       # :call-seq:
       #   self + other -> sequence set
@@ -610,14 +844,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 :|
@@ -629,14 +868,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 :-
 
@@ -647,17 +894,23 @@ 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>.
-      def &(other)
-        remain_frozen dup.subtract SequenceSet.new(other).complement!
-      end
+      # 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.intersect! other end
       alias intersection :&
 
       # :call-seq:
@@ -667,16 +920,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 (dup | 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.xor! other end
       alias xor :^
 
       # :call-seq:
@@ -693,7 +952,12 @@ 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 :~
 
@@ -705,9 +969,13 @@ module Net
       #
       # #string will be regenerated.  Use #merge to add many elements at once.
       #
-      # Related: #add?, #merge, #union
+      # Use #append to append new elements to #string.  See
+      # SequenceSet@Ordered+and+Normalized+sets.
+      #
+      # Related: #add?, #merge, #union, #append
       def add(element)
-        tuple_add input_to_tuple element
+        modifying! # short-circuit before import_run
+        add_run import_run element
         normalize!
       end
       alias << add
@@ -716,13 +984,56 @@ 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.
+      #
+      #    set = Net::IMAP::SequenceSet.new
+      #    set.append(1..2)  # => Net::IMAP::SequenceSet("1:2")
+      #    set.append(5)     # => Net::IMAP::SequenceSet("1:2,5")
+      #    set.append(4)     # => Net::IMAP::SequenceSet("1:2,5,4")
+      #    set.append(3)     # => Net::IMAP::SequenceSet("1:2,5,4,3")
+      #    set.append(2)     # => Net::IMAP::SequenceSet("1:2,5,4,3,2")
+      #
+      # If +entry+ is a string, it will be converted into normal form.
+      #
+      #    set = Net::IMAP::SequenceSet("4:5,1:2")
+      #    set.append("6:6") # => Net::IMAP::SequenceSet("4:5,1:2,6")
+      #    set.append("9:8") # => Net::IMAP::SequenceSet("4:5,1:2,6,8:9")
+      #
+      # If +entry+ adjacently follows the last entry, they will coalesced:
+      #    set = Net::IMAP::SequenceSet.new("2,1,9:10")
+      #    set.append(11..12) # => Net::IMAP::SequenceSet("2,1,9:12")
+      #
+      # Non-normalized sets store the string <em>in addition to</em> an internal
+      # normalized uint32 set representation.  This can more than double memory
+      # usage, so large sets should avoid using #append unless preserving order
+      # is required.  See SequenceSet@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)
+        modifying! # short-circuit before import_minmax
+        minmax = import_minmax entry
+        adj = minmax.first - 1
+        if @string.nil? && (runs.empty? || max_num <= adj)
+          # append to elements or coalesce with last element
+          add_minmax minmax
+          return self
+        elsif @string.nil?
+          # generate string for out-of-order append
+          head, comma = normalized_string, ","
+        else
+          # @string already exists... maybe coalesce with last entry
+          head, comma, last_entry = @string.rpartition(",")
+          last_min, last_max = import_minmax last_entry
+          if last_max == adj
+            # coalesce with last entry
+            minmax[0] = last_min
+          else
+            # append to existing string
+            head, comma = @string, ","
+          end
+        end
+        entry = export_minmax minmax
+        add_minmax minmax
+        @string = -"#{head}#{comma}#{entry}"
         self
       end
 
@@ -735,6 +1046,7 @@ module Net
       #
       # Related: #add, #merge, #union, #include?
       def add?(element)
+        modifying! # short-circuit before include?
         add element unless include? element
       end
 
@@ -747,7 +1059,8 @@ module Net
       #
       # Related: #delete?, #delete_at, #subtract, #difference
       def delete(element)
-        tuple_subtract input_to_tuple element
+        modifying! # short-circuit before import_run
+        subtract_run import_run element
         normalize!
       end
 
@@ -784,15 +1097,17 @@ module Net
       #
       # Related: #delete, #delete_at, #subtract, #difference, #disjoint?
       def delete?(element)
-        tuple = input_to_tuple element
-        if tuple.first == tuple.last
-          return unless include_tuple? tuple
-          tuple_subtract tuple
+        modifying! # short-circuit before import_minmax
+        element = input_try_convert(element)
+        minmax = import_minmax element
+        if number_input?(element)
+          return unless include_minmax? minmax
+          subtract_minmax minmax
           normalize!
-          from_tuple_int tuple.first
+          export_num minmax.first
         else
           copy = dup
-          tuple_subtract tuple
+          subtract_minmax minmax
           normalize!
           copy if copy.subtract(self).valid?
         end
@@ -824,35 +1139,34 @@ 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 +sets+ into the
-      # set, and returns +self+.
+      # In-place set #union.  Merges all of the elements that appear in any of
+      # the +sets+ into this set, and returns +self+.
       #
-      # 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.
+      # The +sets+ may be any objects that would be accepted by ::new.
       #
       # #string will be regenerated after all sets have been merged.
       #
       # Related: #add, #add?, #union
       def merge(*sets)
-        tuples_add input_to_tuples sets
+        modifying! # short-circuit before import_runs
+        add_runs import_runs sets
         normalize!
       end
 
-      # Removes all of the elements that appear in any of the given +sets+ from
-      # the set, and returns +self+.
+      # In-place set #difference.  Removes all of the elements that appear in
+      # any of the given +sets+ from this set, and returns +self+.
       #
-      # 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.
+      # The +sets+ may be any objects that would be accepted by ::new.
       #
       # Related: #difference
       def subtract(*sets)
-        tuples_subtract input_to_tuples sets
+        modifying! # short-circuit before import_runs
+        subtract_runs import_runs sets
         normalize!
       end
 
@@ -864,21 +1178,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, :*]
       #
@@ -889,15 +1203,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
@@ -909,7 +1221,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]
@@ -941,54 +1253,34 @@ 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?
-        each_entry_tuple do yield tuple_to_entry _1 end
+        each_entry_run do yield export_run_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, SequenceSet@Ordered+and+Normalized+sets.
       #
       # Related: #elements, #each_entry
       def each_element # :yields: integer or range or :*
         return to_enum(__method__) unless block_given?
-        @tuples.each do yield tuple_to_entry _1 end
-        self
-      end
-
-      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
+        runs.each do yield export_run_entry _1 end
         self
       end
 
-      def tuple_to_entry((min, max))
-        if    min == STAR_INT then :*
-        elsif max == STAR_INT then min..
-        elsif min == max      then min
-        else                       min..max
-        end
-      end
-
-      public
-
       # Yields each range in #ranges to the block and returns self.
       # Returns an enumerator when called without a block.
       #
       # Related: #ranges
       def each_range # :yields: range
         return to_enum(__method__) unless block_given?
-        @tuples.each do |min, max|
+        minmaxes.each do |min, max|
           if    min == STAR_INT then yield :*..
           elsif max == STAR_INT then yield min..
           else                       yield min..max
@@ -1007,7 +1299,7 @@ module Net
       def each_number(&block) # :yields: integer
         return to_enum(__method__) unless block_given?
         raise RangeError, '%s contains "*"' % [self.class] if include_star?
-        @tuples.each do each_number_in_tuple _1, _2, &block end
+        minmaxes.each do each_number_in_minmax _1, _2, &block end
         self
       end
 
@@ -1021,16 +1313,7 @@ module Net
       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
+        each_entry_minmax do each_number_in_minmax _1, _2, &block end
       end
 
       # Returns a Set with all of the #numbers in the sequence set.
@@ -1042,35 +1325,103 @@ module Net
       # Related: #elements, #ranges, #numbers
       def to_set; Set.new(numbers) end
 
-      # Returns the count of #numbers in the set.
+      # Returns the number of members in the set.
+      #
+      # Unlike #count, <tt>"*"</tt> is considered to be distinct from
+      # <tt>2³² - 1</tt> (the maximum 32-bit unsigned integer value).
+      #
+      #     set = Net::IMAP::SequenceSet[1..10]
+      #     set.count        #=> 10
+      #     set.cardinality  #=> 10
       #
-      # <tt>*</tt> will be counted as <tt>2**32 - 1</tt> (the maximum 32-bit
-      # unsigned integer value).
+      #     set = Net::IMAP::SequenceSet["4294967295,*"]
+      #     set.count        #=> 1
+      #     set.cardinality  #=> 2
       #
-      # Related: #count_with_duplicates
+      #     set = Net::IMAP::SequenceSet[1..]
+      #     set.count        #=> 4294967295
+      #     set.cardinality  #=> 4294967296
+      #
+      # Related: #count, #count_with_duplicates
+      def cardinality = minmaxes.sum(runs.count) { _2 - _1 }
+
+      # Returns the count of distinct #numbers in the set.
+      #
+      # Unlike #cardinality, <tt>"*"</tt> is considered to be equal to
+      # <tt>2³² - 1</tt> (the maximum 32-bit unsigned integer value).
+      #
+      #     set = Net::IMAP::SequenceSet[1..10]
+      #     set.count        #=> 10
+      #     set.cardinality  #=> 10
+      #
+      #     set = Net::IMAP::SequenceSet["4294967295,*"]
+      #     set.count        #=> 1
+      #     set.cardinality  #=> 2
+      #
+      #     set = Net::IMAP::SequenceSet[1..]
+      #     set.count        #=> 4294967295
+      #     set.cardinality  #=> 4294967296
+      #
+      # Related: #cardinality, #count_with_duplicates
       def count
-        @tuples.sum(@tuples.count) { _2 - _1 } +
-          (include_star? && include?(UINT32_MAX) ? -1 : 0)
+        cardinality + (include_star? && include?(UINT32_MAX) ? -1 : 0)
       end
 
-      alias size count
-
       # 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?
+      # When #string is normalized, this returns the same as #count.  Like
+      # #count, <tt>"*"</tt> is considered to be equal to <tt>2³² - 1</tt> (the
+      # maximum 32-bit unsigned integer value).
+      #
+      # In a range, <tt>"*"</tt> is _not_ considered a duplicate:
+      #     set = Net::IMAP::SequenceSet["4294967295:*"]
+      #     set.count_with_duplicates  #=> 1
+      #     set.size                   #=> 2
+      #     set.count                  #=> 1
+      #     set.cardinality            #=> 2
+      #
+      # In a separate entry, <tt>"*"</tt> _is_ considered a duplicate:
+      #     set = Net::IMAP::SequenceSet["4294967295,*"]
+      #     set.count_with_duplicates  #=> 2
+      #     set.size                   #=> 2
+      #     set.count                  #=> 1
+      #     set.cardinality            #=> 2
+      #
+      # Related: #count, #cardinality, #size, #count_duplicates,
+      # #has_duplicates?, #entries
       def count_with_duplicates
         return count unless @string
-        each_entry_tuple.sum {|min, max|
+        each_entry_minmax.sum {|min, max|
           max - min + ((max == STAR_INT && min != STAR_INT) ? 0 : 1)
         }
       end
 
+      # Returns the combined size of the ordered #entries, including any
+      # repeated numbers.
+      #
+      # When #string is normalized, this returns the same as #cardinality.
+      # Like #cardinality, <tt>"*"</tt> is considered to be be distinct from
+      # <tt>2³² - 1</tt> (the maximum 32-bit unsigned integer value).
+      #
+      #     set = Net::IMAP::SequenceSet["4294967295:*"]
+      #     set.size                   #=> 2
+      #     set.count_with_duplicates  #=> 1
+      #     set.count                  #=> 1
+      #     set.cardinality            #=> 2
+      #
+      #     set = Net::IMAP::SequenceSet["4294967295,*"]
+      #     set.size                   #=> 2
+      #     set.count_with_duplicates  #=> 2
+      #     set.count                  #=> 1
+      #     set.cardinality            #=> 2
+      #
+      # Related: #cardinality, #count_with_duplicates, #count, #entries
+      def size
+        return cardinality unless @string
+        each_entry_minmax.sum {|min, max| max - min + 1 }
+      end
+
       # Returns the count of repeated numbers in the ordered #entries, the
       # difference between #count_with_duplicates and #count.
       #
@@ -1088,7 +1439,7 @@ module Net
       #
       # Always returns +false+ when #string is normalized.
       #
-      # Related: #entries, #count_with_duplicates, #count_duplicates?
+      # Related: #entries, #count_with_duplicates, #count_duplicates
       def has_duplicates?
         return false unless @string
         count_with_duplicates != count
@@ -1099,10 +1450,10 @@ module Net
       #
       # Related: #[], #at, #find_ordered_index
       def find_index(number)
-        number = to_tuple_int number
-        each_tuple_with_index(@tuples) do |min, max, idx_min|
+        number = import_num number
+        each_minmax_with_index(minmaxes) do |min, max, idx_min|
           number <  min and return nil
-          number <= max and return from_tuple_int(idx_min + (number - min))
+          number <= max and return export_num(idx_min + (number - min))
         end
         nil
       end
@@ -1112,38 +1463,15 @@ module Net
       #
       # 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|
+        number = import_num number
+        each_minmax_with_index(each_entry_minmax) do |min, max, idx_min|
           if min <= number && number <= max
-            return from_tuple_int(idx_min + (number - min))
+            return export_num(idx_min + (number - min))
           end
         end
         nil
       end
 
-      private
-
-      def each_tuple_with_index(tuples)
-        idx_min = 0
-        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(tuples)
-        idx_max = -1
-        tuples.reverse_each do |min, max|
-          yield min, max, (idx_min = idx_max - (max - min)), idx_max
-          idx_max = idx_min - 1
-        end
-        idx_max
-      end
-
-      public
-
       # :call-seq: at(index) -> integer or nil
       #
       # Returns the number at the given +index+ in the sorted set, without
@@ -1154,7 +1482,7 @@ module Net
       #
       # Related: #[], #slice, #ordered_at
       def at(index)
-        lookup_number_by_tuple_index(tuples, index)
+        seek_number_in_minmaxes(minmaxes, index)
       end
 
       # :call-seq: ordered_at(index) -> integer or nil
@@ -1167,21 +1495,7 @@ module Net
       #
       # 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(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(tuples) do |min, _, idx_min, idx_max|
-            index <= idx_max and return from_tuple_int(min + (index - idx_min))
-          end
-        end
-        nil
+        seek_number_in_minmaxes(each_entry_minmax, index)
       end
 
       # :call-seq:
@@ -1232,37 +1546,58 @@ module Net
 
       alias slice :[]
 
-      private
-
-      def slice_length(start, length)
-        start  = Integer(start.to_int)
-        length = Integer(length.to_int)
-        raise ArgumentError, "length must be positive" unless length.positive?
-        last = start + length - 1 unless start.negative? && start.abs <= length
-        slice_range(start..last)
+      # 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
 
-      def slice_range(range)
-        first = range.begin ||  0
-        last  = range.end   || -1
-        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
-          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                  remain_frozen_empty
-          end
-        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
 
-      public
-
       # 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+.
@@ -1280,8 +1615,9 @@ module Net
       #   Net::IMAP::SequenceSet["500:*"].limit(max: 37)
       #   #=> Net::IMAP::SequenceSet["37"]
       #
+      # Related: #limit!
       def limit(max:)
-        max = to_tuple_int(max)
+        max = import_num(max)
         if    empty?                      then self.class.empty
         elsif !include_star? && max < min then self.class.empty
         elsif max(star: STAR_INT) <= max  then frozen? ? self : dup.freeze
@@ -1294,76 +1630,206 @@ module Net
       #
       # Related: #limit
       def limit!(max:)
+        modifying! # short-circuit before querying
         star = include_star?
-        max  = to_tuple_int(max)
-        tuple_subtract [max + 1, STAR_INT]
-        tuple_add      [max,     max     ] if star
+        max  = import_num(max)
+        subtract_minmax [max + 1, STAR_INT]
+        add_minmax      [max,     max     ] if star
         normalize!
       end
 
       # :call-seq: complement! -> self
       #
-      # Converts the SequenceSet to its own #complement.  It will contain all
-      # possible values _except_ for those currently in the set.
+      # In-place set #complement.  Replaces the contents of this set with its
+      # own #complement.  It will contain all possible values _except_ for those
+      # currently in the set.
       #
       # Related: #complement
       def complement!
+        modifying! # short-circuit before querying
         return replace(self.class.full) if empty?
         return clear                    if full?
-        flat = @tuples.flat_map { [_1 - 1, _2 + 1] }
+        flat = minmaxes.flat_map { [_1 - 1, _2 + 1] }
         if flat.first < 1         then flat.shift else flat.unshift 1        end
         if STAR_INT   < flat.last then flat.pop   else flat.push    STAR_INT end
-        @tuples = flat.each_slice(2).to_a
+        replace_minmaxes flat.each_slice(2).to_a
         normalize!
       end
 
-      # Returns a new SequenceSet with a normalized string representation.
+      # In-place set #intersection.  Removes any elements that are missing from
+      # +other+ from this set, keeping only the #intersection, and returns
+      # +self+.
+      #
+      # +other+ can be any object that would be accepted by ::new.
       #
-      # The returned set's #string is sorted and deduplicated.  Adjacent or
-      # overlapping elements will be merged into a single larger range.
+      #     set = Net::IMAP::SequenceSet.new(1..5)
+      #     set.intersect! [2, 4, 6]
+      #     set #=> Net::IMAP::SequenceSet("2,4")
+      #
+      # Related: #intersection, #intersect?
+      def intersect!(other)
+        modifying! # short-circuit before processing input
+        subtract SequenceSet.new(other).complement!
+      end
+
+      # In-place set #xor.  Adds any numbers in +other+ that are missing from
+      # this set, removes any numbers in +other+ that are already in this set,
+      # and returns +self+.
+      #
+      # +other+ can be any object that would be accepted by ::new.
+      #
+      #     set = Net::IMAP::SequenceSet.new(1..5)
+      #     set.xor! [2, 4, 6]
+      #     set #=> Net::IMAP::SequenceSet["1,3,5:6"]
+      #
+      # Related: #xor, #merge, #subtract
+      def xor!(other)
+        modifying! # short-circuit before processing input
+        other = SequenceSet.new(other)
+        copy  = dup
+        merge(other).subtract(other.subtract(copy.complement!))
+      end
+
+      # Returns whether #string is fully normalized: entries have been sorted,
+      # deduplicated, and coalesced, and all entries are in normal form.  See
+      # SequenceSet@Ordered+and+Normalized+sets.
+      #
+      #   Net::IMAP::SequenceSet["1,3,5"].normalized?  #=> true
+      #   Net::IMAP::SequenceSet["20:30"].normalized?  #=> true
+      #
+      #   Net::IMAP::SequenceSet["3,5,1"].normalized?  #=> false, not sorted
+      #   Net::IMAP::SequenceSet["1,2,3"].normalized?  #=> false, not coalesced
+      #   Net::IMAP::SequenceSet["1:5,2"].normalized?  #=> false, repeated number
+      #
+      #   Net::IMAP::SequenceSet["1:1"].normalized?    #=> false, number as range
+      #   Net::IMAP::SequenceSet["5:1"].normalized?    #=> false, backwards range
+      #
+      # Returns +true+ if (and only if) #string is equal to #normalized_string:
+      #   seqset = Net::IMAP::SequenceSet["1:3,5"]
+      #   seqset.string             #=> "1:3,5"
+      #   seqset.normalized_string  #=> "1:3,5"
+      #   seqset.entries            #=> [1..3, 5]
+      #   seqset.elements           #=> [1..3, 5]
+      #   seqset.normalized?        #=> true
+      #
+      #   seqset = Net::IMAP::SequenceSet["3,1,2"]
+      #   seqset.string             #=> "3,1,2"
+      #   seqset.normalized_string  #=> "1:3"
+      #   seqset.entries            #=> [3, 1, 2]
+      #   seqset.elements           #=> [1..3]
+      #   seqset.normalized?        #=> false
+      #
+      # Can return +false+ even when #entries and #elements are the same:
+      #   seqset = Net::IMAP::SequenceSet["5:1"]
+      #   seqset.string             #=> "5:1"
+      #   seqset.normalized_string  #=> "1:5"
+      #   seqset.entries            #=> [1..5]
+      #   seqset.elements           #=> [1..5]
+      #   seqset.normalized?        #=> false
+      #
+      # Note that empty sets are normalized, even though they are not #valid?:
+      #   seqset = Net::IMAP::SequenceSet.empty
+      #   seqset.normalized?        #=> true
+      #   seqset.valid?             #=> false
+      #
+      # Related: #normalize, #normalize!, #normalized_string
+      def normalized?
+        @string.nil? || normal_string?(@string)
+      end
+
+      # Returns a SequenceSet with a normalized string representation: entries
+      # have been sorted, deduplicated, and coalesced, and all entries
+      # are in normal form.  Returns +self+ for frozen normalized sets, and a
+      # normalized duplicate otherwise.
+      #
+      # 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"]
       #
-      # Related: #normalize!, #normalized_string
+      # Related: #normalize!, #normalized_string, #normalized?
       def normalize
-        str = normalized_string
-        return self if frozen? && str == string
-        remain_frozen dup.instance_exec { @string = str&.-@; self }
+        frozen? && normalized? ? self : remain_frozen(dup.normalize!)
       end
 
       # Resets #string to be sorted, deduplicated, and coalesced.  Returns
-      # +self+.
+      # +self+.  See SequenceSet@Ordered+and+Normalized+sets.
       #
-      # Related: #normalize, #normalized_string
+      # Related: #normalize, #normalized_string, #normalized?
       def normalize!
+        modifying! # redundant check (normalizes 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"
       #
-      # Related: #normalize!, #normalize
+      # Returns +nil+ when the set is empty.
+      #
+      # Related: #normalize!, #normalize, #string, #to_s, #normalized?
       def normalized_string
-        @tuples.empty? ? nil : -@tuples.map { tuple_to_str _1 }.join(",")
+        export_runs(runs) unless runs.empty?
       end
 
+      # Returns an inspection string for the SequenceSet.
+      #
+      #   Net::IMAP::SequenceSet.new.inspect
+      #   #=> "Net::IMAP::SequenceSet()"
+      #
+      #   Net::IMAP::SequenceSet(1..5, 1024, 15, 2000).inspect
+      #   #=> 'Net::IMAP::SequenceSet("1:5,15,1024,2000")'
+      #
+      # Frozen sets have slightly different output:
+      #
+      #   Net::IMAP::SequenceSet.empty.inspect
+      #   #=> "Net::IMAP::SequenceSet.empty"
+      #
+      #   Net::IMAP::SequenceSet[1..5, 1024, 15, 2000].inspect
+      #   #=> 'Net::IMAP::SequenceSet["1:5,15,1024,2000"]'
+      #
+      # Large sets (by number of #entries) have abridged output, with only the
+      # first and last entries:
+      #
+      #   Net::IMAP::SequenceSet(((1..5000) % 2).to_a).inspect
+      #   #=> #<Net::IMAP::SequenceSet 2500 entries "1,3,5,7,9,11,13,15,17,19,21,23,25,27,29,31,...(2468 entries omitted)...,4969,4971,4973,4975,4977,4979,4981,4983,4985,4987,4989,4991,4993,4995,4997,4999">
+      #
+      # Related: #to_s, #string
       def inspect
-        if empty?
-          (frozen? ?  "%s.empty" : "#<%s empty>") % [self.class]
-        elsif frozen?
-          "%s[%p]"   % [self.class, to_s]
+        case (count = count_entries)
+        when 0
+          (frozen? ? "%s.empty" : "%s()") % [self.class]
+        when ..INSPECT_MAX_LEN
+          (frozen? ? "%s[%p]" : "%s(%p)") % [self.class, to_s]
         else
-          "#<%s %p>" % [self.class, to_s]
+          if @string
+            head = @string[INSPECT_ABRIDGED_HEAD_RE]
+            tail = @string[INSPECT_ABRIDGED_TAIL_RE]
+          else
+            head = export_runs(runs.first(INSPECT_TRUNCATE_LEN)) + ","
+            tail = "," + export_runs(runs.last(INSPECT_TRUNCATE_LEN))
+          end
+          '#<%s %d entries "%s...(%d entries omitted)...%s"%s>' % [
+            self.class, count,
+            head, count - INSPECT_TRUNCATE_LEN * 2, tail,
+            frozen? ? " (frozen)" : "",
+          ]
         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)
@@ -1377,9 +1843,25 @@ 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:
+        @set_data = new_set_data
+        self.string = coder['string']
+      end
+
+      # :stopdoc:
       protected
 
-      attr_reader :tuples # :nodoc:
+      attr_reader :set_data
+
+      alias runs set_data
+      alias minmaxes runs
 
       private
 
@@ -1388,38 +1870,42 @@ module Net
 
       # frozen clones are shallow copied
       def initialize_clone(other)
-        other.frozen? ? super : initialize_dup(other)
+        @set_data = other.dup_set_data unless other.frozen?
+        super
       end
 
       def initialize_dup(other)
-        @tuples = other.tuples.map(&:dup)
-        @string = other.string&.-@
+        @set_data = other.dup_set_data
         super
       end
 
-      def input_to_tuple(entry)
-        entry = input_try_convert entry
+      ######################################################################{{{2
+      # Import methods
+
+      def import_minmax(input)
+        entry = input_try_convert input
         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)
+        when *STARS, Integer then [int = import_num(entry), int]
+        when Range           then import_range_minmax(entry)
+        when String          then parse_minmax(entry)
         else
-          raise DataFormatError, "expected number or range, got %p" % [entry]
+          raise DataFormatError, "expected number or range, got %p" % [input]
         end
       end
+      alias import_run import_minmax
 
-      def input_to_tuples(set)
-        set = input_try_convert set
+      def import_runs(input)
+        set = input_try_convert input
         case set
-        when *STARS, Integer, Range then [input_to_tuple(set)]
-        when String      then str_to_tuples set
-        when SequenceSet then set.tuples
-        when ENUMABLE    then set.flat_map { input_to_tuples _1 }
+        when *STARS, Integer, Range then [import_run(set)]
+        when String      then parse_runs set
+        when SequenceSet then set.runs
+        when Set         then set.map      { [import_num(_1)] * 2 }
+        when Array       then set.flat_map { import_runs _1 }
         when nil         then []
         else
-          raise DataFormatError,
-                "expected nz-number, range, string, or enumerable; " \
-                "got %p" % [set]
+          raise DataFormatError, "expected nz-number, range, '*', Set, Array; " \
+                                 "got %p" % [input]
         end
       end
 
@@ -1427,15 +1913,22 @@ 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
 
-      def range_to_tuple(range)
-        first = to_tuple_int(range.begin || 1)
-        last  = to_tuple_int(range.end   || :*)
+      # NOTE: input_try_convert must be called on input first
+      def number_input?(input)
+        case input
+        when *STARS, Integer then true
+        when String          then !input.include?(/[:,]/)
+        end
+      end
+
+      def import_range_minmax(range)
+        first = import_num(range.begin || 1)
+        last  = import_num(range.end   || :*)
         last -= 1 if range.exclude_end? && range.end && last != STAR_INT
         unless first <= last
           raise DataFormatError, "invalid range for sequence-set: %p" % [range]
@@ -1443,67 +1936,260 @@ module Net
         [first, last]
       end
 
-      def to_tuple_int(obj) STARS.include?(obj) ? STAR_INT : nz_number(obj) end
-      def from_tuple_int(num) num == STAR_INT ? :* : num end
+      def import_num(obj) STARS.include?(obj) ? STAR_INT : nz_number(obj) end
+      def nz_number(num) = NumValidator.coerce_nz_number(num)
+
+      ######################################################################{{{2
+      # Export methods
+
+      def export_num(num) num == STAR_INT ? :* : num end
 
-      def tuple_to_str(tuple) tuple.uniq.map{ from_tuple_int _1 }.join(":") end
-      def str_to_tuples(str) str.split(",", -1).map! { str_to_tuple _1 } end
-      def str_to_tuple(str)
+      def export_minmaxes(minmaxes)
+        -minmaxes.map { export_minmax _1 }.join(",")
+      end
+
+      def export_minmax(minmax) minmax.uniq.map { export_num _1 }.join(":") end
+
+      alias export_runs export_minmaxes
+      alias export_run  export_minmax
+
+      def export_minmax_entry((min, max))
+        if    min == STAR_INT then :*
+        elsif max == STAR_INT then min..
+        elsif min == max      then min
+        else                       min..max
+        end
+      end
+      alias export_run_entry export_minmax_entry
+
+      def each_number_in_minmax(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
+
+      ######################################################################{{{2
+      # Parse methods
+
+      def parse_runs(str) str.split(",", -1).map! { parse_run _1 } end
+      def parse_minmax(str) parse_entry(str).minmax end
+      alias parse_run parse_minmax
+
+      def parse_entry(str)
         raise DataFormatError, "invalid sequence set string" if str.empty?
-        str.split(":", 2).map! { to_tuple_int _1 }.minmax
+        str.split(":", 2).map! { import_num _1 }
+      end
+
+      # yields validated but unsorted [num] or [num, num]
+      def each_parsed_entry(str)
+        return to_enum(__method__, str) unless block_given?
+        str&.split(",", -1) do |entry| yield parse_entry(entry) end
       end
 
-      def include_tuple?((min, max)) range_gte_to(min)&.cover?(min..max) end
+      def normal_string?(str) normalized_entries? each_parsed_entry str end
 
-      def intersect_tuple?((min, max))
-        range = range_gte_to(min) and
+      def normalized_entries?(entries)
+        max = nil
+        entries.each do |first, last|
+          return false if last && last  <= first    # 1:1 or 2:1
+          return false if max  && first <= max + 1  # 2,1 or 1,1 or 1,2
+          max = last || first
+        end
+        true
+      end
+
+      ######################################################################{{{2
+      # Ordered entry methods
+
+      def count_entries
+        @string ? @string.count(",") + 1 : runs.count
+      end
+
+      def each_entry_minmax(&block)
+        return to_enum(__method__) unless block_given?
+        if @string
+          @string.split(",") do block.call parse_minmax _1 end
+        else
+          minmaxes.each(&block)
+        end
+        self
+      end
+      alias each_entry_run each_entry_minmax
+
+      ######################################################################{{{2
+      # Search methods
+
+      def include_minmax?((min, max)) bsearch_range(min)&.cover?(min..max) end
+
+      def intersect_minmax?((min, max))
+        range = bsearch_range(min) and
           range.include?(min) || range.include?(max) || (min..max).cover?(range)
       end
 
+      alias include_run?   include_minmax?
+      alias intersect_run? intersect_minmax?
+
+      def bsearch_index(num)  = minmaxes.bsearch_index { _2 >= num }
+      def bsearch_minmax(num) = minmaxes.bsearch       { _2 >= num }
+      def bsearch_range(num)  = (min, max = bsearch_minmax(num)) && (min..max)
+
+      ######################################################################{{{2
+      # Number indexing methods
+
+      def seek_number_in_minmaxes(minmaxes, index)
+        index = Integer(index.to_int)
+        if index.negative?
+          reverse_each_minmax_with_index(minmaxes) do |min, max, idx_min, idx_max|
+            idx_min <= index and return export_num(min + (index - idx_min))
+          end
+        else
+          each_minmax_with_index(minmaxes) do |min, _, idx_min, idx_max|
+            index <= idx_max and return export_num(min + (index - idx_min))
+          end
+        end
+        nil
+      end
+
+      def each_minmax_with_index(minmaxes)
+        idx_min = 0
+        minmaxes.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_minmax_with_index(minmaxes)
+        idx_max = -1
+        minmaxes.reverse_each do |min, max|
+          yield min, max, (idx_min = idx_max - (max - min)), idx_max
+          idx_max = idx_min - 1
+        end
+        idx_max
+      end
+
+      def slice_length(start, length)
+        start  = Integer(start.to_int)
+        length = Integer(length.to_int)
+        raise ArgumentError, "length must be positive" unless length.positive?
+        last = start + length - 1 unless start.negative? && start.abs <= length
+        slice_range(start..last)
+      end
+
+      def slice_range(range)
+        first = range.begin ||  0
+        last  = range.end   || -1
+        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
+          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                  remain_frozen_empty
+          end
+        end
+      end
+
+      ######################################################################{{{2
+      # Core set data create/freeze/dup primitives
+
+      def new_set_data    = []
+      def freeze_set_data = set_data.each(&:freeze).freeze
+      def dup_set_data    = set_data.map { _1.dup }
+      protected :dup_set_data
+
+      ######################################################################{{{2
+      # Core set data query/enumeration primitives
+
+      def min_num                 = minmaxes.first&.first
+      def max_num                 = minmaxes.last&.last
+
+      def min_at(idx)             = minmaxes[idx][0]
+      def max_at(idx)             = minmaxes[idx][1]
+
+      ######################################################################{{{2
+      # Core set data modification primitives
+
+      def set_min_at(idx, min)         = minmaxes[idx][0] = min
+      def set_max_at(idx, max)         = minmaxes[idx][1] = max
+      def replace_minmaxes(other)      = minmaxes.replace(other)
+      def append_minmax(min, max)      = minmaxes << [min, max]
+      def insert_minmax(idx, min, max) = minmaxes.insert idx, [min, max]
+      def delete_run_at(idx)           = runs.delete_at(idx)
+      def slice_runs!(...)             = runs.slice!(...)
+      def truncate_runs!(idx)          = runs.slice!(idx..)
+
+      ######################################################################{{{2
+      # Update methods
+
       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
+      def add_minmaxes(minmaxes)
+        minmaxes.each do |minmax|
+          add_minmax minmax
+        end
+        self
+      end
+
+      def subtract_minmaxes(minmaxes)
+        minmaxes.each do |minmax|
+          subtract_minmax minmax
+        end
+        self
+      end
 
       #
-      #   --|=====| |=====new tuple=====|                 append
-      #   ?????????-|=====new tuple=====|-|===lower===|-- insert
+      #   --|=====| |=====new run=======|                 append
+      #   ?????????-|=====new run=======|-|===lower===|-- insert
       #
-      #             |=====new tuple=====|
+      #             |=====new run=======|
       #   ---------??=======lower=======??--------------- noop
       #
       #   ---------??===lower==|--|==|                    join remaining
       #   ---------??===lower==|--|==|----|===upper===|-- join until upper
       #   ---------??===lower==|--|==|--|=====upper===|-- join to upper
-      def tuple_add(tuple)
+      def add_minmax(minmax)
         modifying!
-        min, max = tuple
-        lower, lower_idx = tuple_gte_with_index(min - 1)
-        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)
+        min, max   = minmax
+        lower_idx  = bsearch_index(min - 1)
+        lmin, lmax = min_at(lower_idx), max_at(lower_idx) if lower_idx
+        if    lmin.nil?        then append_minmax min, max
+        elsif (max + 1) < lmin then insert_minmax lower_idx, min, max
+        else  add_coalesced_minmax(lower_idx, lmin, lmax, min, max)
         end
       end
 
-      def tuple_coalesce(lower, lower_idx, min, max)
-        return if lower.first <= min && max <= lower.last
-        lower[0] = [min, lower.first].min
-        lower[1] = [max, lower.last].max
-        lower_idx += 1
-        return if lower_idx == tuples.count
-        tmax_adj = lower.last + 1
-        upper, upper_idx = tuple_gte_with_index(tmax_adj)
-        if upper
-          tmax_adj < upper.first ? (upper_idx -= 1) : (lower[1] = upper.last)
+      def add_coalesced_minmax(lower_idx, lmin, lmax, min, max)
+        return if lmin <= min && max <= lmax
+        set_min_at lower_idx, (lmin = min) if min < lmin
+        set_max_at lower_idx, (lmax = max) if lmax < max
+        next_idx = lower_idx + 1
+        return if next_idx == runs.count
+        tmax_adj = lmax + 1
+        if (upper_idx = bsearch_index(tmax_adj))
+          if tmax_adj < min_at(upper_idx)
+            upper_idx -= 1
+          else
+            set_max_at lower_idx, max_at(upper_idx)
+          end
         end
-        tuples.slice!(lower_idx..upper_idx)
+        slice_runs! next_idx..upper_idx
       end
 
-      #         |====tuple================|
+      #         |====subtracted run=======|
       # --|====|                               no more       1. noop
       # --|====|---------------------------|====lower====|-- 2. noop
       # -------|======lower================|---------------- 3. split
@@ -1516,62 +2202,59 @@ module Net
       # -------??=====lower====|--|====|       no more       6. delete rest
       # -------??=====lower====|--|====|---|====upper====|-- 7. delete until
       # -------??=====lower====|--|====|--|=====upper====|-- 8. delete and trim
-      def tuple_subtract(tuple)
+      def subtract_minmax(minmax)
         modifying!
-        min, max = tuple
-        lower, idx = tuple_gte_with_index(min)
-        if    lower.nil?        then nil # case 1.
-        elsif max < lower.first then nil # case 2.
-        elsif max < lower.last  then tuple_trim_or_split   lower, idx, min, max
-        else                         tuples_trim_or_delete lower, idx, min, max
+        min, max   = minmax
+        idx        = bsearch_index(min)
+        lmin, lmax = min_at(idx), max_at(idx) if idx
+        if    lmin.nil?  then nil # case 1.
+        elsif max < lmin then nil # case 2.
+        elsif max < lmax then trim_or_split_minmax  idx, lmin,       min, max
+        else                  trim_or_delete_minmax idx, lmin, lmax, min, max
         end
       end
 
-      def tuple_trim_or_split(lower, idx, tmin, tmax)
-        if lower.first < tmin # split
-          tuples.insert(idx, [lower.first, tmin - 1])
+      def trim_or_split_minmax(idx, lmin, tmin, tmax)
+        set_min_at idx, tmax + 1
+        if lmin < tmin # split
+          insert_minmax idx, lmin, tmin - 1
         end
-        lower[0] = tmax + 1
       end
 
-      def tuples_trim_or_delete(lower, lower_idx, tmin, tmax)
-        if lower.first < tmin # trim lower
-          lower[1] = tmin - 1
+      def trim_or_delete_minmax(lower_idx, lmin, lmax, tmin, tmax)
+        if lmin < tmin # trim lower
+          lmax = set_max_at lower_idx, tmin - 1
           lower_idx += 1
         end
-        if tmax == lower.last                           # case 5
-          upper_idx = lower_idx
-        elsif (upper, upper_idx = tuple_gte_with_index(tmax + 1))
-          upper_idx -= 1                                # cases 7 and 8
-          upper[0] = tmax + 1 if upper.first <= tmax    # case 8 (else case 7)
+        if tmax == lmax                                 # case 5
+          delete_run_at lower_idx
+        elsif (upper_idx = bsearch_index(tmax + 1))
+          if min_at(upper_idx) <= tmax                  # case 8
+            set_min_at upper_idx, tmax + 1
+          end
+          slice_runs! lower_idx..upper_idx - 1          # cases 7 and 8
+        else                                            # case 6
+          truncate_runs! lower_idx
         end
-        tuples.slice!(lower_idx..upper_idx)
       end
 
-      def tuple_gte_with_index(num)
-        idx = tuples.bsearch_index { _2 >= num } and [tuples[idx], idx]
-      end
-
-      def range_gte_to(num)
-        first, last = tuples.bsearch { _2 >= num }
-        first..last if first
-      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
-      end
+      alias add_runs      add_minmaxes
+      alias add_run       add_minmax
+      alias subtract_runs subtract_minmaxes
+      alias subtract_run  subtract_minmax
 
+      ######################################################################{{{2
       # intentionally defined after the class implementation
 
+      FULL_SET_DATA = [[1, STAR_INT].freeze].freeze
+      private_constant :FULL_SET_DATA
+
       EMPTY = new.freeze
       FULL  = self["1:*"]
       private_constant :EMPTY, :FULL
 
+      # }}}
+      # vim:foldmethod=marker
     end
   end
 end