net-imap 0.4.20 → 0.5.0

data/lib/net/imap/sequence_set.rb

@@ -14,13 +14,6 @@ module Net
     # receive a SequenceSet as an argument, for example IMAP#search, IMAP#fetch,
     # and IMAP#store.
     #
-    # == EXPERIMENTAL API
-    #
-    # SequenceSet is currently experimental.  Only two methods, ::[] and
-    # #valid_string, are considered stable.  Although the API isn't expected to
-    # change much, any other methods may be removed or changed without
-    # deprecation.
-    #
     # == Creating sequence sets
     #
     # SequenceSet.new with no arguments creates an empty sequence set.  Note
@@ -37,7 +30,8 @@ module Net
     #
     # SequenceSet.new may receive a single optional argument: a non-zero 32 bit
     # unsigned integer, a range, a <tt>sequence-set</tt> formatted string,
-    # another sequence set, or an enumerable containing any of these.
+    # another sequence set, a Set (containing only numbers or <tt>*</tt>), or an
+    # Array containing any of these (array inputs may be nested).
     #
     #     set = Net::IMAP::SequenceSet.new(1)
     #     set.valid_string  #=> "1"
@@ -60,20 +54,18 @@ module Net
     #     set = Net::IMAP::SequenceSet[1, 2, [3..7, 5], 6..10, 2048, 1024]
     #     set.valid_string  #=> "1:10,55,1024:2048"
     #
-    # == 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.
+    # == Normalized form
     #
-    # 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.
+    # When a sequence set is created with a single String value, that #string
+    # representation is preserved.  SequenceSet's internal representation
+    # implicitly sorts all entries, de-duplicates numbers, and coalesces
+    # adjacent or overlapping ranges.  Most enumeration methods and offset-based
+    # methods use this normalized representation.  Most modification methods
+    # will convert #string to its normalized form.
     #
-    # Most modification methods convert #string to its normalized form.  To
+    # In some cases the order of the string representation is significant, such
+    # as the +ESORT+, <tt>CONTEXT=SORT</tt>, and +UIDPLUS+ extensions.  Use
+    # #entries or #each_entry to enumerate the set in its original order.  To
     # preserve #string order while modifying a set, use #append, #string=, or
     # #replace.
     #
@@ -166,7 +158,7 @@ module Net
     # - #===:
     #   Returns whether a given object is fully contained within +self+, or
     #   +nil+ if the object cannot be converted to a compatible type.
-    # - #cover?:
+    # - #cover? (aliased as #===):
     #   Returns whether a given object is fully contained within +self+.
     # - #intersect? (aliased as #overlap?):
     #   Returns whether +self+ and a given object have any common elements.
@@ -178,7 +170,7 @@ module Net
     #
     # <i>Set membership:</i>
     # - #include? (aliased as #member?):
-    #   Returns whether a given element (nz-number, range, or <tt>*</tt>) is
+    #   Returns whether a given object (nz-number, range, or <tt>*</tt>) is
     #   contained by the set.
     # - #include_star?: Returns whether the set contains <tt>*</tt>.
     #
@@ -187,41 +179,30 @@ module Net
     # - #max: Returns the maximum number in the set.
     # - #minmax: Returns the minimum and maximum numbers in the set.
     #
-    # <i>Accessing value by offset in sorted set:</i>
+    # <i>Accessing value by offset:</i>
     # - #[] (aliased as #slice): Returns the number or consecutive subset at a
-    #   given offset or range of offsets in the sorted set.
-    # - #at: Returns the number at a given offset in the sorted set.
-    # - #find_index: Returns the given number's offset in the sorted set.
-    #
-    # <i>Accessing value by offset in ordered entries</i>
-    # - #ordered_at: Returns the number at a given offset in the ordered entries.
-    # - #find_ordered_index: Returns the index of the given number's first
-    #   occurrence in entries.
+    #   given offset or range of offsets.
+    # - #at: Returns the number at a given offset.
+    # - #find_index: Returns the given number's offset in the set
     #
     # <i>Set cardinality:</i>
     # - #count (aliased as #size): Returns the count of numbers in the set.
-    #   Duplicated numbers are not counted.
     # - #empty?: Returns whether the set has no members.  \IMAP syntax does not
     #   allow empty sequence sets.
     # - #valid?: Returns whether the set has any members.
     # - #full?: Returns whether the set contains every possible value, including
     #   <tt>*</tt>.
     #
-    # <i>Denormalized properties:</i>
-    # - #has_duplicates?: Returns whether the ordered entries repeat any
-    #   numbers.
-    # - #count_duplicates: Returns the count of repeated numbers in the ordered
-    #   entries.
-    # - #count_with_duplicates: Returns the count of numbers in the ordered
-    #   entries, including any repeated numbers.
-    #
     # === Methods for Iterating
     #
-    # <i>Normalized (sorted and coalesced):</i>
     # - #each_element: Yields each number and range in the set, sorted and
     #   coalesced, and returns +self+.
     # - #elements (aliased as #to_a): Returns an Array of every number and range
     #   in the set, sorted and coalesced.
+    # - #each_entry: Yields each number and range in the set, unsorted and
+    #   without deduplicating numbers or coalescing ranges, and returns +self+.
+    # - #entries: Returns an Array of every number and range in the set,
+    #   unsorted and without deduplicating numbers or coalescing ranges.
     # - #each_range:
     #   Yields each element in the set as a Range and returns +self+.
     # - #ranges: Returns an Array of every element in the set, converting
@@ -231,25 +212,17 @@ module Net
     #   ranges into all of their contained numbers.
     # - #to_set: Returns a Set containing all of the #numbers in the set.
     #
-    # <i>Order preserving:</i>
-    # - #each_entry: Yields each number and range in the set, unsorted and
-    #   without deduplicating numbers or coalescing ranges, and returns +self+.
-    # - #entries: Returns an Array of every number and range in the set,
-    #   unsorted and without deduplicating numbers or coalescing ranges.
-    # - #each_ordered_number: Yields each number in the ordered entries and
-    #   returns +self+.
-    #
     # === Methods for \Set Operations
     # These methods do not modify +self+.
     #
     # - #| (aliased as #union and #+): Returns a new set combining all members
-    #   from +self+ with all members from the other set.
+    #   from +self+ with all members from the other object.
     # - #& (aliased as #intersection): Returns a new set containing all members
-    #   common to +self+ and the other set.
+    #   common to +self+ and the other object.
     # - #- (aliased as #difference): Returns a copy of +self+ with all members
-    #   in the other set removed.
+    #   in the other object removed.
     # - #^ (aliased as #xor): Returns a new set containing all members from
-    #   +self+ and the other set except those common to both.
+    #   +self+ and the other object except those common to both.
     # - #~ (aliased as #complement): Returns a new set containing all members
     #   that are not in +self+
     # - #limit: Returns a copy of +self+ which has replaced <tt>*</tt> with a
@@ -258,39 +231,28 @@ module Net
     # === Methods for Assigning
     # These methods add or replace elements in +self+.
     #
-    # <i>Normalized (sorted and coalesced):</i>
-    #
-    # These methods always update #string to be fully sorted and coalesced.
-    #
-    # - #add (aliased as #<<): Adds a given element to the set; returns +self+.
-    # - #add?: If the given element is not fully included the set, adds it and
+    # - #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
     #   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.
-    #
-    # <i>Order preserving:</i>
-    #
-    # These methods _may_ cause #string to not be sorted or coalesced.
-    #
-    # - #append: Adds the given entry to the set, appending it to the existing
+    # - #merge: Merges multiple elements into the set; returns +self+.
+    # - #append: Adds a given object to the set, appending it to the existing
     #   string, and returns +self+.
     # - #string=: Assigns a new #string value and replaces #elements to match.
     # - #replace: Replaces the contents of the set with the contents
     #   of a given object.
+    # - #complement!: Replaces the contents of the set with its own #complement.
     #
     # === Methods for Deleting
-    # These methods remove elements from +self+, and update #string to be fully
-    # sorted and coalesced.
+    # These methods remove elements from +self+.
     #
     # - #clear: Removes all elements in the set; returns +self+.
-    # - #delete: Removes a given element from the set; returns +self+.
-    # - #delete?: If the given element is included in the set, removes it and
+    # - #delete: Removes a given object from the set; returns +self+.
+    # - #delete?: If the given object is an element 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 all members of the given sets from this set; returns
-    #   +self+.
+    # - #subtract: Removes each given object from the set; returns +self+.
     # - #limit!: Replaces <tt>*</tt> with a given maximum value and removes all
     #   members over that maximum; returns +self+.
     #
@@ -321,18 +283,14 @@ module Net
       private_constant :STAR_INT, :STARS
 
       COERCIBLE = ->{ _1.respond_to? :to_sequence_set }
-      ENUMABLE  = ->{ _1.respond_to?(:each) && _1.respond_to?(:empty?) }
-      private_constant :COERCIBLE, :ENUMABLE
+      private_constant :COERCIBLE
 
       class << self
 
         # :call-seq:
-        #   SequenceSet[*inputs] -> valid frozen sequence set
-        #
-        # Returns a frozen SequenceSet, constructed from +inputs+.
+        #   SequenceSet[*values] -> valid frozen sequence set
         #
-        # When only a single valid frozen SequenceSet is given, that same set is
-        # returned.
+        # Returns a frozen SequenceSet, constructed from +values+.
         #
         # An empty SequenceSet is invalid and will raise a DataFormatError.
         #
@@ -360,7 +318,7 @@ module Net
         # raised.
         def try_convert(obj)
           return obj if obj.is_a?(SequenceSet)
-          return nil unless obj.respond_to?(:to_sequence_set)
+          return nil unless respond_to?(:to_sequence_set)
           obj = obj.to_sequence_set
           return obj if obj.is_a?(SequenceSet)
           raise DataFormatError, "invalid object returned from to_sequence_set"
@@ -698,7 +656,7 @@ module Net
       alias complement :~
 
       # :call-seq:
-      #   add(element)   -> self
+      #   add(object)   -> self
       #   self << other -> self
       #
       # Adds a range or number to the set and returns +self+.
@@ -706,8 +664,8 @@ module Net
       # #string will be regenerated.  Use #merge to add many elements at once.
       #
       # Related: #add?, #merge, #union
-      def add(element)
-        tuple_add input_to_tuple element
+      def add(object)
+        tuple_add input_to_tuple object
         normalize!
       end
       alias << add
@@ -716,29 +674,28 @@ 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(entry)
+      def append(object)
         modifying!
-        tuple = input_to_tuple entry
+        tuple = input_to_tuple object
         entry = tuple_to_str tuple
-        string unless empty? # write @string before tuple_add
         tuple_add tuple
-        @string = -(@string ? "#{@string},#{entry}" : entry)
+        @string = -(string ? "#{@string},#{entry}" : entry)
         self
       end
 
-      # :call-seq: add?(element) -> self or nil
+      # :call-seq: add?(object) -> self or nil
       #
       # Adds a range or number to the set and returns +self+.  Returns +nil+
-      # when the element is already included in the set.
+      # when the object 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?(element)
-        add element unless include? element
+      def add?(object)
+        add object unless include? object
       end
 
-      # :call-seq: delete(element) -> self
+      # :call-seq: delete(object) -> self
       #
       # Deletes the given range or number from the set and returns +self+.
       #
@@ -746,8 +703,8 @@ module Net
       # many elements at once.
       #
       # Related: #delete?, #delete_at, #subtract, #difference
-      def delete(element)
-        tuple_subtract input_to_tuple element
+      def delete(object)
+        tuple_subtract input_to_tuple object
         normalize!
       end
 
@@ -783,8 +740,8 @@ module Net
       # #string will be regenerated after deletion.
       #
       # Related: #delete, #delete_at, #subtract, #difference, #disjoint?
-      def delete?(element)
-        tuple = input_to_tuple element
+      def delete?(object)
+        tuple = input_to_tuple object
         if tuple.first == tuple.last
           return unless include_tuple? tuple
           tuple_subtract tuple
@@ -828,31 +785,33 @@ module Net
         deleted
       end
 
-      # Merges all of the elements that appear in any of the +sets+ into the
+      # Merges all of the elements that appear in any of the +inputs+ into the
       # 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 +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.
       #
-      # #string will be regenerated after all sets have been merged.
+      # #string will be regenerated after all inputs have been merged.
       #
       # Related: #add, #add?, #union
-      def merge(*sets)
-        tuples_add input_to_tuples sets
+      def merge(*inputs)
+        tuples_add input_to_tuples inputs
         normalize!
       end
 
-      # Removes all of the elements that appear in any of the given +sets+ from
-      # the set, and returns +self+.
+      # Removes all of the elements that appear in any of the given +objects+
+      # from the 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 +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.
       #
       # Related: #difference
-      def subtract(*sets)
-        tuples_subtract input_to_tuples sets
+      def subtract(*objects)
+        tuples_subtract input_to_tuples objects
         normalize!
       end
 
@@ -876,8 +835,8 @@ module Net
       # <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.
+      # If the original input was unordered or contains overlapping ranges, the
+      # returned ranges will be ordered and coalesced.
       #
       #   Net::IMAP::SequenceSet["2,5:9,6,*,12:11"].elements
       #   #=> [2, 5..9, 11..12, :*]
@@ -895,7 +854,7 @@ module Net
       # 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
+      # The returned ranges will be ordered and coalesced, even when the input
       # #string is not.  <tt>*</tt> will sort last.  See #normalize.
       #
       #   Net::IMAP::SequenceSet["2,5:9,6,*,12:11"].ranges
@@ -944,7 +903,9 @@ module Net
       # 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
+        return each_element(&block) unless @string
+        @string.split(",").each do yield tuple_to_entry str_to_tuple _1 end
+        self
       end
 
       # Yields each number or range (or <tt>:*</tt>) in #elements to the block
@@ -962,16 +923,6 @@ module Net
 
       private
 
-      def each_entry_tuple(&block)
-        return to_enum(__method__) unless block_given?
-        if @string
-          @string.split(",") do block.call str_to_tuple _1 end
-        else
-          @tuples.each(&block)
-        end
-        self
-      end
-
       def tuple_to_entry((min, max))
         if    min == STAR_INT then :*
         elsif max == STAR_INT then min..
@@ -1003,34 +954,17 @@ module Net
       # Returns an enumerator when called without a block (even if the set
       # contains <tt>*</tt>).
       #
-      # Related: #numbers, #each_ordered_number
+      # Related: #numbers
       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
-        self
-      end
-
-      # Yields each number in #entries to the block and returns self.
-      # If the set contains a <tt>*</tt>, RangeError will be raised.
-      #
-      # Returns an enumerator when called without a block (even if the set
-      # contains <tt>*</tt>).
-      #
-      # Related: #entries, #each_number
-      def each_ordered_number(&block)
-        return to_enum(__method__) unless block_given?
-        raise RangeError, '%s contains "*"' % [self.class] if include_star?
-        each_entry_tuple do each_number_in_tuple _1, _2, &block end
-      end
-
-      private def each_number_in_tuple(min, max, &block)
-        if    min == STAR_INT then yield :*
-        elsif min == max      then yield min
-        elsif max != STAR_INT then (min..max).each(&block)
-        else
-          raise RangeError, "#{SequenceSet} cannot enumerate range with '*'"
+        each_element do |elem|
+          case elem
+          when Range   then elem.each(&block)
+          when Integer then block.(elem)
+          end
         end
+        self
       end
 
       # Returns a Set with all of the #numbers in the sequence set.
@@ -1044,10 +978,8 @@ module Net
 
       # Returns the count of #numbers in the set.
       #
-      # <tt>*</tt> will be counted as <tt>2**32 - 1</tt> (the maximum 32-bit
-      # unsigned integer value).
-      #
-      # Related: #count_with_duplicates
+      # If <tt>*</tt> and <tt>2**32 - 1</tt> (the maximum 32-bit unsigned
+      # integer value) are both in the set, they will only be counted once.
       def count
         @tuples.sum(@tuples.count) { _2 - _1 } +
           (include_star? && include?(UINT32_MAX) ? -1 : 0)
@@ -1055,87 +987,33 @@ module Net
 
       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?
-      def count_with_duplicates
-        return count unless @string
-        each_entry_tuple.sum {|min, max|
-          max - min + ((max == STAR_INT && min != STAR_INT) ? 0 : 1)
-        }
-      end
-
-      # Returns the count of repeated numbers in the ordered #entries, the
-      # difference between #count_with_duplicates and #count.
-      #
-      # When #string is normalized, this is zero.
-      #
-      # Related: #entries, #count_with_duplicates, #has_duplicates?
-      def count_duplicates
-        return 0 unless @string
-        count_with_duplicates - count
-      end
-
-      # :call-seq: has_duplicates? -> true | false
-      #
-      # Returns whether or not the ordered #entries repeat any numbers.
-      #
-      # Always returns +false+ when #string is normalized.
-      #
-      # Related: #entries, #count_with_duplicates, #count_duplicates?
-      def has_duplicates?
-        return false unless @string
-        count_with_duplicates != count
-      end
-
-      # Returns the (sorted and deduplicated) index of +number+ in the set, or
-      # +nil+ if +number+ isn't in the set.
+      # Returns the index of +number+ in the set, or +nil+ if +number+ isn't in
+      # the set.
       #
-      # Related: #[], #at, #find_ordered_index
+      # Related: #[]
       def find_index(number)
         number = to_tuple_int number
-        each_tuple_with_index(@tuples) do |min, max, idx_min|
+        each_tuple_with_index do |min, max, idx_min|
           number <  min and return nil
           number <= max and return from_tuple_int(idx_min + (number - min))
         end
         nil
       end
 
-      # Returns the first index of +number+ in the ordered #entries, or
-      # +nil+ if +number+ isn't in the set.
-      #
-      # Related: #find_index
-      def find_ordered_index(number)
-        number = to_tuple_int number
-        each_tuple_with_index(each_entry_tuple) do |min, max, idx_min|
-          if min <= number && number <= max
-            return from_tuple_int(idx_min + (number - min))
-          end
-        end
-        nil
-      end
-
       private
 
-      def each_tuple_with_index(tuples)
+      def each_tuple_with_index
         idx_min = 0
-        tuples.each do |min, max|
-          idx_max = idx_min + (max - min)
-          yield min, max, idx_min, idx_max
+        @tuples.each do |min, max|
+          yield min, max, idx_min, (idx_max = idx_min + (max - min))
           idx_min = idx_max + 1
         end
         idx_min
       end
 
-      def reverse_each_tuple_with_index(tuples)
+      def reverse_each_tuple_with_index
         idx_max = -1
-        tuples.reverse_each do |min, max|
+        @tuples.reverse_each do |min, max|
           yield min, max, (idx_min = idx_max - (max - min)), idx_max
           idx_max = idx_min - 1
         end
@@ -1146,38 +1024,18 @@ module Net
 
       # :call-seq: at(index) -> integer or nil
       #
-      # Returns the number at the given +index+ in the sorted set, without
-      # modifying the set.
-      #
-      # +index+ is interpreted the same as in #[], except that #at only allows a
-      # single integer argument.
+      # Returns a number from +self+, without modifying the set.  Behaves the
+      # same as #[], except that #at only allows a single integer argument.
       #
-      # Related: #[], #slice, #ordered_at
+      # Related: #[], #slice
       def at(index)
-        lookup_number_by_tuple_index(tuples, index)
-      end
-
-      # :call-seq: ordered_at(index) -> integer or nil
-      #
-      # Returns the number at the given +index+ in the ordered #entries, without
-      # modifying the set.
-      #
-      # +index+ is interpreted the same as in #at (and #[]), except that
-      # #ordered_at applies to the ordered #entries, not the sorted set.
-      #
-      # Related: #[], #slice, #ordered_at
-      def ordered_at(index)
-        lookup_number_by_tuple_index(each_entry_tuple, index)
-      end
-
-      private def lookup_number_by_tuple_index(tuples, index)
         index = Integer(index.to_int)
         if index.negative?
-          reverse_each_tuple_with_index(tuples) do |min, max, idx_min, idx_max|
+          reverse_each_tuple_with_index 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|
+          each_tuple_with_index do |min, _, idx_min, idx_max|
             index <= idx_max and return from_tuple_int(min + (index - idx_min))
           end
         end
@@ -1192,18 +1050,17 @@ module Net
       #    seqset[range]         -> sequence set or nil
       #    slice(range)          -> sequence set or nil
       #
-      # Returns a number or a subset from the _sorted_ set, without modifying
-      # the set.
+      # Returns a number or a subset from +self+, without modifying the set.
       #
       # When an Integer argument +index+ is given, the number at offset +index+
-      # in the sorted set is returned:
+      # is returned:
       #
       #     set = Net::IMAP::SequenceSet["10:15,20:23,26"]
       #     set[0]   #=> 10
       #     set[5]   #=> 15
       #     set[10]  #=> 26
       #
-      # If +index+ is negative, it counts relative to the end of the sorted set:
+      # If +index+ is negative, it counts relative to the end of +self+:
       #     set = Net::IMAP::SequenceSet["10:15,20:23,26"]
       #     set[-1]  #=> 26
       #     set[-3]  #=> 22
@@ -1215,14 +1072,13 @@ module Net
       #     set[11]  #=> nil
       #     set[-12] #=> nil
       #
-      # The result is based on the sorted and de-duplicated set, not on the
-      # ordered #entries in #string.
+      # The result is based on the normalized set—sorted and de-duplicated—not
+      # on the assigned value of #string.
       #
       #     set = Net::IMAP::SequenceSet["12,20:23,11:16,21"]
       #     set[0]   #=> 11
       #     set[-1]  #=> 23
       #
-      # Related: #at
       def [](index, length = nil)
         if    length              then slice_length(index, length)
         elsif index.is_a?(Range)  then slice_range(index)
@@ -1392,29 +1248,30 @@ module Net
         super
       end
 
-      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)
+      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)
         else
-          raise DataFormatError, "expected number or range, got %p" % [entry]
+          raise DataFormatError, "expected number or range, got %p" % [obj]
         end
       end
 
-      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 ENUMABLE    then set.flat_map { input_to_tuples _1 }
+      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 }
         when nil         then []
         else
           raise DataFormatError,
                 "expected nz-number, range, string, or enumerable; " \
-                "got %p" % [set]
+                "got %p" % [obj]
         end
       end
 
@@ -1422,8 +1279,7 @@ module Net
       # String, Set, Array, or... any type of object.
       def input_try_convert(input)
         SequenceSet.try_convert(input) ||
-          # Integer.try_convert(input) || # ruby 3.1+
-          input.respond_to?(:to_int) && Integer(input.to_int) ||
+          Integer.try_convert(input) ||
           String.try_convert(input) ||
           input
       end
@@ -1478,8 +1334,8 @@ module Net
         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])
+        if    lower.nil?              then tuples << tuple
+        elsif (max + 1) < lower.first then tuples.insert(lower_idx, tuple)
         else  tuple_coalesce(lower, lower_idx, min, max)
         end
       end
@@ -1553,12 +1409,11 @@ module Net
       end
 
       def nz_number(num)
-        case num
-        when Integer, /\A[1-9]\d*\z/ then num = Integer(num)
-        else raise DataFormatError, "%p is not a valid nz-number" % [num]
-        end
-        NumValidator.ensure_nz_number(num)
-        num
+        String === num && !/\A[1-9]\d*\z/.match?(num) and
+          raise DataFormatError, "%p is not a valid nz-number" % [num]
+        NumValidator.ensure_nz_number Integer num
+      rescue TypeError # To catch errors from Integer()
+        raise DataFormatError, $!.message
       end
 
       # intentionally defined after the class implementation