net-imap 0.5.7 → 0.5.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee48ac78f129043fd8ccb4f6e0b42535cc0ef3a6acd8ea1067cbd9b512815e49
-  data.tar.gz: 5bfae3bf0ee2e63c5b61c19d30187fe722adfe8018746e64d583124531de87a8
+  metadata.gz: 261794e07175481d35e146b718183fc057a3a54e2fd9958b25918c6bd4178ec4
+  data.tar.gz: 2568eb1d284b3f1662d1cf0c1bc79eb65722fa3ba8dc03072b52fbd3716c9294
 SHA512:
-  metadata.gz: f90a4500f3c218dd3a51cca84a76c620fa8f8488f2ca73486b538a43e67e21e0b897d23d957f490afe1590fd755c692f2e0dede562460ed2cfcd7f4d9bec3262
-  data.tar.gz: 22abb3cf5699bb715c33c69b596ead46ff400109925f58d633ecdc82797be9b80fbbd040c02aa7cd9286f3aa9c697e9fc426f1115b9019455b2ac4e6667cc236
+  metadata.gz: 357279f77c69c27b78924847216afad6c806abb7bfee5f0c95aab6c397cb10298440a59cb32b9f75a4174e6965d6bfe48a5e847e20d9098845033e8453f73302
+  data.tar.gz: e3c29888d787de23a843bfb9ff9194d1fa136763e9d9bcf36800953362f7611c489da1f9150ee2a23baa571125f4f2af2cebe4ee4666447783e355bd9995eb3a

data/Gemfile

@@ -14,7 +14,9 @@ gem "rdoc"
 gem "test-unit"
 gem "test-unit-ruby-core", git: "https://github.com/ruby/test-unit-ruby-core"
 
+gem "benchmark", require: false
 gem "benchmark-driver", require: false
+gem "vernier", require: false, platform: :mri
 
 group :test do
   gem "simplecov",        require: false

data/lib/net/imap/config/attr_type_coercion.rb

@@ -28,7 +28,11 @@ module Net
         end
         private_class_method :included
 
-        def self.safe(...) = Ractor.make_shareable nil.instance_eval(...).freeze
+        if defined?(Ractor.make_shareable)
+          def self.safe(...) Ractor.make_shareable nil.instance_eval(...).freeze end
+        else
+          def self.safe(...) nil.instance_eval(...).freeze end
+        end
         private_class_method :safe
 
         Types = Hash.new do |h, type| type => Proc | nil; safe{type} end

data/lib/net/imap/flags.rb

@@ -173,7 +173,7 @@ module Net
     SUBSCRIBED = :Subscribed
 
     # The mailbox is a remote mailbox.
-    REMOTE = :Remove
+    REMOTE = :Remote
 
     # Alias for NO_INFERIORS, to match the \IMAP spelling.
     NOINFERIORS   = NO_INFERIORS

data/lib/net/imap/response_data.rb

@@ -6,7 +6,6 @@ module Net
     autoload :FetchData,        "#{__dir__}/fetch_data"
     autoload :UIDFetchData,     "#{__dir__}/fetch_data"
     autoload :SearchResult,     "#{__dir__}/search_result"
-    autoload :SequenceSet,      "#{__dir__}/sequence_set"
     autoload :UIDPlusData,      "#{__dir__}/uidplus_data"
     autoload :AppendUIDData,    "#{__dir__}/uidplus_data"
     autoload :CopyUIDData,      "#{__dir__}/uidplus_data"

data/lib/net/imap/sequence_set.rb

@@ -18,21 +18,9 @@ module Net
     #
     # == Creating sequence sets
     #
-    # SequenceSet.new with no arguments creates an empty sequence set.  Note
-    # that an empty sequence set is invalid in the \IMAP grammar.
-    #
-    #     set = Net::IMAP::SequenceSet.new
-    #     set.empty?        #=> true
-    #     set.valid?        #=> false
-    #     set.valid_string  #!> raises DataFormatError
-    #     set << 1..10
-    #     set.empty?        #=> false
-    #     set.valid?        #=> true
-    #     set.valid_string  #=> "1:10"
-    #
     # SequenceSet.new may receive a single optional argument: a non-zero 32 bit
     # unsigned integer, a range, a <tt>sequence-set</tt> formatted string,
-    # another sequence set, a Set (containing only numbers or <tt>*</tt>), or an
+    # another SequenceSet, a Set (containing only numbers or <tt>*</tt>), or an
     # Array containing any of these (array inputs may be nested).
     #
     #     set = Net::IMAP::SequenceSet.new(1)
@@ -48,30 +36,114 @@ module Net
     #     set = Net::IMAP::SequenceSet.new(1, 2, 3..7, 5, 6..10, 2048, 1024)
     #     set.valid_string  #=> "1:10,55,1024:2048"
     #
-    # Use ::[] with one or more arguments to create a frozen SequenceSet.  An
-    # invalid (empty) set cannot be created with ::[].
+    # SequenceSet.new with no arguments creates an empty sequence set.  Note
+    # that an empty sequence set is invalid in the \IMAP grammar.
+    #
+    #     set = Net::IMAP::SequenceSet.new
+    #     set.empty?        #=> true
+    #     set.valid?        #=> false
+    #     set.valid_string  #!> raises DataFormatError
+    #     set << 1..10
+    #     set.empty?        #=> false
+    #     set.valid?        #=> true
+    #     set.valid_string  #=> "1:10"
     #
+    # Using SequenceSet.new with another SequenceSet input behaves the same as
+    # calling #dup on the other set.  The input's #string will be preserved.
+    #
+    #     input = Net::IMAP::SequenceSet.new("1,2,3:7,5,6:10,2048,1024")
+    #     copy  = Net::IMAP::SequenceSet.new(input)
+    #     input.valid_string  #=> "1,2,3:7,5,6:10,2048,1024"
+    #     copy.valid_string   #=> "1,2,3:7,5,6:10,2048,1024"
+    #     copy2 = input.dup   # same as calling new with a SequenceSet input
+    #     copy ==     input   #=> true,  same set membership
+    #     copy.eql?   input   #=> true,  same string value
+    #     copy.equal? input   #=> false, different objects
+    #
+    #     copy.normalize!
+    #     copy.valid_string   #=> "1:10,1024,2048"
+    #     copy ==   input     #=> true,  same set membership
+    #     copy.eql? input     #=> false, different string value
+    #
+    #     copy << 999
+    #     copy.valid_string   #=> "1:10,999,1024,2048"
+    #     copy ==   input     #=> false, different set membership
+    #     copy.eql? input     #=> false, different string value
+    #
+    # Use Net::IMAP::SequenceSet() to coerce a single (optional) input.
+    # A SequenceSet input is returned without duplication, even when frozen.
+    #
+    #     set = Net::IMAP::SequenceSet()
+    #     set.string   #=> nil
+    #     set.frozen?  #=> false
+    #
+    #     # String order is preserved
+    #     set = Net::IMAP::SequenceSet("1,2,3:7,5,6:10,2048,1024")
+    #     set.valid_string  #=> "1,2,3:7,5,6:10,2048,1024"
+    #     set.frozen?       #=> false
+    #
+    #     # Other inputs are normalized
+    #     set = Net::IMAP::SequenceSet([1, 2, [3..7, 5], 6..10, 2048, 1024])
+    #     set.valid_string  #=> "1:10,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 stores a normalized representation which sorts all
-    # entries, de-duplicates numbers, and coalesces adjacent or overlapping
-    # ranges.  Most methods use this normalized representation to achieve
-    # <tt>O(lg n)</tt> porformance.  Use #entries or #each_entry to enumerate
-    # the set in its original order.
+    # Internally, SequenceSet uses a normalized uint32 set representation which
+    # sorts and de-duplicates all numbers and coalesces adjacent or overlapping
+    # entries.  Many methods use this sorted set representation for <tt>O(lg
+    # n)</tt> searches.  Use #each_element, #elements, #each_range, #ranges,
+    # #each_number, or #numbers to enumerate the set in sorted order.  Basic
+    # object equality (using #==) is based on set membership, without regard to
+    # #entry order or #string normalization.
     #
-    # Most modification methods convert #string to its normalized form.  To
-    # preserve #string order while modifying a set, use #append, #string=, or
-    # #replace.
+    # Most modification methods reset #string to its #normalized form, so that
+    # #entries and #elements are identical.  Use #append to preserve #entries
+    # order while modifying a set.
     #
     # == Using <tt>*</tt>
     #
@@ -108,11 +180,15 @@ module Net
     # When a set includes <tt>*</tt>, some methods may have surprising behavior.
     #
     # For example, #complement treats <tt>*</tt> as its own number.  This way,
-    # the #intersection of a set and its #complement will always be empty.
-    # This is not how an \IMAP server interprets the set: it will convert
-    # <tt>*</tt> to either the number of messages in the mailbox or +UIDNEXT+,
-    # as appropriate.  And there _will_ be overlap between a set and its
-    # complement after #limit is applied to each:
+    # the #intersection of a set and its #complement will always be empty.  And
+    # <tt>*</tt> is sorted as greater than any other number in the set.  This is
+    # not how an \IMAP server interprets the set: it will convert <tt>*</tt> to
+    # the number of messages in the mailbox, the +UID+ of the last message in
+    # the mailbox, or +UIDNEXT+, as appropriate.  Several methods have an
+    # argument for how <tt>*</tt> should be interpreted.
+    #
+    # But, for example, this means that there may be overlap between a set and
+    # its complement after #limit is applied to each:
     #
     #   ~Net::IMAP::SequenceSet["*"]  == Net::IMAP::SequenceSet[1..(2**32-1)]
     #   ~Net::IMAP::SequenceSet[1..5] == Net::IMAP::SequenceSet["6:*"]
@@ -149,6 +225,7 @@ module Net
     # * ::new: Creates a new mutable sequence set, which may be empty (invalid).
     # * ::try_convert: Calls +to_sequence_set+ on an object and verifies that
     #   the result is a SequenceSet.
+    # * Net::IMAP::SequenceSet(): Coerce an input using ::try_convert or ::new.
     # * ::empty: Returns a frozen empty (invalid) SequenceSet.
     # * ::full: Returns a frozen SequenceSet containing every possible number.
     #
@@ -174,14 +251,13 @@ module Net
     #
     # <i>Set membership:</i>
     # - #include? (aliased as #member?):
-    #   Returns whether a given 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
@@ -248,6 +324,10 @@ 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.
     #
@@ -316,6 +396,23 @@ module Net
       STARS     = [:*, ?*, -1].freeze
       private_constant :STARS
 
+      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
 
         # :call-seq:
@@ -329,13 +426,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
@@ -350,6 +446,8 @@ module Net
         #
         # If +obj.to_sequence_set+ doesn't return a SequenceSet, an exception is
         # raised.
+        #
+        # Related: Net::IMAP::SequenceSet(), ::new, ::[]
         def try_convert(obj)
           return obj if obj.is_a?(SequenceSet)
           return nil unless obj.respond_to?(:to_sequence_set)
@@ -368,23 +466,91 @@ module Net
       end
 
       # Create a new SequenceSet object from +input+, which may be another
-      # SequenceSet, an IMAP formatted +sequence-set+ string, a number, a
-      # range, <tt>:*</tt>, or an enumerable of these.
-      #
-      # Use ::[] to create a frozen (non-empty) SequenceSet.
+      # SequenceSet, an IMAP formatted +sequence-set+ string, a non-zero 32 bit
+      # unsigned integer, a range, <tt>:*</tt>, a Set of numbers or <tt>*</tt>,
+      # an object that responds to +to_sequence_set+ (such as SearchResult) or
+      # an Array of these (array inputs may be nested).
+      #
+      #     set = Net::IMAP::SequenceSet.new(1)
+      #     set.valid_string  #=> "1"
+      #     set = Net::IMAP::SequenceSet.new(1..100)
+      #     set.valid_string  #=> "1:100"
+      #     set = Net::IMAP::SequenceSet.new(1...100)
+      #     set.valid_string  #=> "1:99"
+      #     set = Net::IMAP::SequenceSet.new([1, 2, 5..])
+      #     set.valid_string  #=> "1:2,5:*"
+      #     set = Net::IMAP::SequenceSet.new("1,2,3:7,5,6:10,2048,1024")
+      #     set.valid_string  #=> "1,2,3:7,5,6:10,2048,1024"
+      #     set = Net::IMAP::SequenceSet.new(1, 2, 3..7, 5, 6..10, 2048, 1024)
+      #     set.valid_string  #=> "1:10,1024,2048"
+      #
+      # With no arguments (or +nil+) creates an empty sequence set.  Note that
+      # an empty sequence set is invalid in the \IMAP grammar.
+      #
+      #     set = Net::IMAP::SequenceSet.new
+      #     set.empty?        #=> true
+      #     set.valid?        #=> false
+      #     set.valid_string  #!> raises DataFormatError
+      #     set << 1..10
+      #     set.empty?        #=> false
+      #     set.valid?        #=> true
+      #     set.valid_string  #=> "1:10"
+      #
+      # When +input+ is a SequenceSet, ::new behaves the same as calling #dup on
+      # that other set.  The input's #string will be preserved.
+      #
+      #     input = Net::IMAP::SequenceSet.new("1,2,3:7,5,6:10,2048,1024")
+      #     copy  = Net::IMAP::SequenceSet.new(input)
+      #     input.valid_string  #=> "1,2,3:7,5,6:10,2048,1024"
+      #     copy.valid_string   #=> "1,2,3:7,5,6:10,2048,1024"
+      #     copy2 = input.dup   # same as calling new with a SequenceSet input
+      #     copy ==     input   #=> true,  same set membership
+      #     copy.eql?   input   #=> true,  same string value
+      #     copy.equal? input   #=> false, different objects
+      #
+      #     copy.normalize!
+      #     copy.valid_string   #=> "1:10,1024,2048"
+      #     copy ==   input     #=> true,  same set membership
+      #     copy.eql? input     #=> false, different string value
+      #
+      #     copy << 999
+      #     copy.valid_string   #=> "1:10,999,1024,2048"
+      #     copy ==   input     #=> false, different set membership
+      #     copy.eql? input     #=> false, different string value
+      #
+      # === Alternative set creation methods
+      #
+      # * ::[] returns a frozen validated (non-empty) SequenceSet, without
+      #   allocating a new object when the input is already a valid frozen
+      #   SequenceSet.
+      # * Net::IMAP::SequenceSet() coerces an input to SequenceSet, without
+      #   allocating a new object when the input is already a SequenceSet.
+      # * ::try_convert calls +to_sequence_set+ on inputs that support it and
+      #   returns +nil+ for inputs that don't.
+      # * ::empty and ::full both return frozen singleton sets which can be
+      #   combined with set operations (#|, #&, #^, #-, etc) to make new sets.
+      #
+      # See SequenceSet@Creating+sequence+sets.
       def initialize(input = nil) input ? replace(input) : clear end
 
       # Removes all elements and returns self.
-      def clear; @tuples, @string = [], nil; self end
+      def clear
+        modifying! # redundant check, to normalize the error message for JRuby
+        @tuples, @string = [], nil
+        self
+      end
 
       # Replace the contents of the set with the contents of +other+ and returns
       # +self+.
       #
-      # +other+ may be another SequenceSet, or it may be an IMAP +sequence-set+
-      # string, a number, a range, <tt>*</tt>, or an enumerable of these.
+      # +other+ may be another SequenceSet or any other object that would be
+      # accepted by ::new.
       def replace(other)
         case other
-        when SequenceSet then initialize_dup(other)
+        when SequenceSet then
+          modifying! # short circuit before doing any work
+          @tuples = other.deep_copy_tuples
+          @string = other.instance_variable_get(:@string)
         when String      then self.string = other
         else                  clear; merge other
         end
@@ -413,36 +579,40 @@ 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
+      # 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.
       #
-      # Use #add or #merge to add a string to an existing set.
+      # Non-empty strings are validated but not normalized.
+      #
+      # 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
-        else
-          str = String.try_convert(str) or raise ArgumentError, "not a string"
+        elsif (str = String.try_convert(input))
+          modifying! # short-circuit before parsing the string
           tuples = str_to_tuples str
           @tuples, @string = [], -str
           tuples_add tuples
+        else
+          raise ArgumentError, "expected a string or nil, got #{input.class}"
         end
+        str
       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.
@@ -495,8 +665,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)
@@ -510,12 +681,12 @@ module Net
       # Returns whether +other+ is contained within the set.  +other+ may be any
       # object that would be accepted by ::new.
       #
-      # Related: #===, #include?, #include_star?
+      # Related: #===, #include?, #include_star?, #intersect?
       def cover?(other) input_to_tuples(other).none? { !include_tuple?(_1) } end
 
       # Returns +true+ when a given number or range is in +self+, and +false+
-      # otherwise.  Returns +false+ unless +number+ is an Integer, Range, or
-      # <tt>*</tt>.
+      # otherwise.  Returns +nil+ when +number+ isn't a valid SequenceSet
+      # element (Integer, Range, <tt>*</tt>, +sequence-set+ string).
       #
       #     set = Net::IMAP::SequenceSet["5:10,100,111:115"]
       #     set.include? 1      #=> false
@@ -523,8 +694,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 "*"
@@ -533,11 +704,14 @@ module Net
       #     set.include? :*     #=> true
       #     set.include? "*"    #=> true
       #     set.include? -1     #=> true
-      #     set.include? 200..  #=> true
-      #     set.include? 100..  #=> false
+      #     set.include?(200..) #=> true
+      #     set.include?(100..) #=> false
       #
-      # Related: #include_star?, #cover?, #===
-      def include?(element) include_tuple? input_to_tuple element end
+      # Related: #include_star?, #cover?, #===, #intersect?
+      def include?(element)
+        tuple = input_to_tuple element rescue nil
+        !!include_tuple?(tuple) if tuple
+      end
 
       alias member? include?
 
@@ -550,7 +724,7 @@ module Net
       #     Net::IMAP::SequenceSet["5:10"].intersect? "7,9,11" #=> true
       #     Net::IMAP::SequenceSet["5:10"].intersect? "11:33"  #=> false
       #
-      # Related: #intersection, #disjoint?
+      # Related: #intersection, #disjoint?, #cover?, #include?
       def intersect?(other)
         valid? && input_to_tuples(other).any? { intersect_tuple? _1 }
       end
@@ -567,26 +741,53 @@ module Net
         empty? || input_to_tuples(other).none? { intersect_tuple? _1 }
       end
 
-      # :call-seq: max(star: :*) => integer or star or nil
+      # :call-seq:
+      #   max(star: :*) => integer or star or nil
+      #   max(count) => SequenceSet
       #
       # Returns the maximum value in +self+, +star+ when the set includes
       # <tt>*</tt>, or +nil+ when the set is empty.
-      def max(star: :*)
-        (val = @tuples.last&.last) && val == STAR_INT ? star : val
+      #
+      # When +count+ is given, a new SequenceSet is returned, containing only
+      # the last +count+ numbers.  An empty SequenceSet is returned when +self+
+      # is empty.  (+star+ is ignored when +count+ is given.)
+      #
+      # Related: #min, #minmax, #slice
+      def max(count = nil, star: :*)
+        if count
+          slice(-[count, size].min..) || remain_frozen_empty
+        elsif (val = @tuples.last&.last)
+          val == STAR_INT ? star : val
+        end
       end
 
-      # :call-seq: min(star: :*) => integer or star or nil
+      # :call-seq:
+      #   min(star: :*) => integer or star or nil
+      #   min(count) => SequenceSet
       #
       # Returns the minimum value in +self+, +star+ when the only value in the
       # set is <tt>*</tt>, or +nil+ when the set is empty.
-      def min(star: :*)
-        (val = @tuples.first&.first) && val == STAR_INT ? star : val
+      #
+      # When +count+ is given, a new SequenceSet is returned, containing only
+      # the first +count+ numbers.  An empty SequenceSet is returned when +self+
+      # is empty.  (+star+ is ignored when +count+ is given.)
+      #
+      # Related: #max, #minmax, #slice
+      def min(count = nil, star: :*)
+        if count
+          slice(0...count) || remain_frozen_empty
+        elsif (val = @tuples.first&.first)
+          val != STAR_INT ? val : star
+        end
       end
 
-      # :call-seq: minmax(star: :*) => nil or [integer, integer or star]
+      # :call-seq: minmax(star: :*) => [min, max] or nil
       #
       # Returns a 2-element array containing the minimum and maximum numbers in
-      # +self+, or +nil+ when the set is empty.
+      # +self+, or +nil+ when the set is empty.  +star+ is handled the same way
+      # as by #min and #max.
+      #
+      # Related: #min, #max
       def minmax(star: :*); [min(star: star), max(star: star)] unless empty? end
 
       # Returns false when the set is empty.
@@ -606,14 +807,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 :|
@@ -625,14 +831,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 :-
 
@@ -643,14 +857,22 @@ module Net
       # Returns a new sequence set containing only the numbers common to this
       # set and +other+.
       #
-      # +other+ may be any object that would be accepted by ::new: a non-zero 32
-      # bit unsigned integer, range, <tt>sequence-set</tt> formatted string,
-      # another sequence set, or an enumerable containing any of these.
+      # +other+ may be any object that would be accepted by ::new.
       #
       #     Net::IMAP::SequenceSet[1..5] & [2, 4, 6]
       #     #=> Net::IMAP::SequenceSet["2,4"]
       #
-      # <tt>(seqset & other)</tt> is equivalent to <tt>(seqset - ~other)</tt>.
+      # Related: #intersect?, #|, #-, #^, #~
+      #
+      # ==== Set identities
+      #
+      # <tt>lhs & rhs</tt> is equivalent to:
+      # * <tt>rhs & lhs</tt> (commutative)
+      # * <tt>~(~lhs | ~rhs)</tt> (De Morgan's Law)
+      # * <tt>lhs - ~rhs</tt>
+      # * <tt>lhs - (lhs - rhs)</tt>
+      # * <tt>lhs - (lhs ^ rhs)</tt>
+      # * <tt>lhs ^ (lhs - rhs)</tt>
       def &(other)
         remain_frozen dup.subtract SequenceSet.new(other).complement!
       end
@@ -663,16 +885,22 @@ module Net
       # Returns a new sequence set containing numbers that are exclusive between
       # this set and +other+.
       #
-      # +other+ may be any object that would be accepted by ::new: a non-zero 32
-      # bit unsigned integer, range, <tt>sequence-set</tt> formatted string,
-      # another sequence set, or an enumerable containing any of these.
+      # +other+ may be any object that would be accepted by ::new.
       #
       #     Net::IMAP::SequenceSet[1..5] ^ [2, 4, 6]
       #     #=> Net::IMAP::SequenceSet["1,3,5:6"]
       #
-      # <tt>(seqset ^ other)</tt> is equivalent to <tt>((seqset | other) -
-      # (seqset & other))</tt>.
-      def ^(other) remain_frozen (self | other).subtract(self & other) end
+      # Related: #|, #&, #-, #~
+      #
+      # ==== Set identities
+      #
+      # <tt>lhs ^ rhs</tt> is equivalent to:
+      # * <tt>rhs ^ lhs</tt> (commutative)
+      # * <tt>~lhs ^ ~rhs</tt>
+      # * <tt>(lhs | rhs) - (lhs & rhs)</tt>
+      # * <tt>(lhs - rhs) | (rhs - lhs)</tt>
+      # * <tt>(lhs ^ other) ^ (other ^ rhs)</tt>
+      def ^(other) remain_frozen (dup | other).subtract(self & other) end
       alias xor :^
 
       # :call-seq:
@@ -689,7 +917,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 :~
 
@@ -701,8 +934,12 @@ 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)
+        modifying! # short-circuit before input_to_tuple
         tuple_add input_to_tuple element
         normalize!
       end
@@ -712,8 +949,12 @@ 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.
+      #
+      # See SequenceSet@Ordered+and+Normalized+sets.
+      #
+      # Related: #add, #merge, #union
       def append(entry)
-        modifying!
+        modifying! # short-circuit before input_to_tuple
         tuple = input_to_tuple entry
         entry = tuple_to_str tuple
         string unless empty? # write @string before tuple_add
@@ -731,6 +972,7 @@ module Net
       #
       # Related: #add, #merge, #union, #include?
       def add?(element)
+        modifying! # short-circuit before include?
         add element unless include? element
       end
 
@@ -743,6 +985,7 @@ module Net
       #
       # Related: #delete?, #delete_at, #subtract, #difference
       def delete(element)
+        modifying! # short-circuit before input_to_tuple
         tuple_subtract input_to_tuple element
         normalize!
       end
@@ -780,6 +1023,7 @@ module Net
       #
       # Related: #delete, #delete_at, #subtract, #difference, #disjoint?
       def delete?(element)
+        modifying! # short-circuit before input_to_tuple
         tuple = input_to_tuple element
         if tuple.first == tuple.last
           return unless include_tuple? tuple
@@ -820,6 +1064,7 @@ 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
@@ -827,14 +1072,13 @@ module Net
       # Merges all of the elements that appear in any of the +sets+ 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 +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)
+        modifying! # short-circuit before input_to_tuples
         tuples_add input_to_tuples sets
         normalize!
       end
@@ -842,9 +1086,7 @@ module Net
       # Removes all of the elements that appear in any of the given +sets+ 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 +sets+ may be any objects that would be accepted by ::new.
       #
       # Related: #difference
       def subtract(*sets)
@@ -860,21 +1102,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, :*]
       #
@@ -885,15 +1127,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
@@ -905,7 +1145,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]
@@ -937,6 +1177,8 @@ module Net
       # no sorting, deduplication, or coalescing.  When #string is in its
       # normalized form, this will yield the same values as #each_element.
       #
+      # See SequenceSet@Ordered+and+Normalized+sets.
+      #
       # Related: #entries, #each_element
       def each_entry(&block) # :yields: integer or range or :*
         return to_enum(__method__) unless block_given?
@@ -947,7 +1189,7 @@ module Net
       # and returns self.  Returns an enumerator when called without a block.
       #
       # The returned numbers are sorted and de-duplicated, even when the input
-      # #string is not.  See #normalize.
+      # #string is not.  See #normalize, SequenceSet@Ordered+and+Normalized+sets.
       #
       # Related: #elements, #each_entry
       def each_element # :yields: integer or range or :*
@@ -1241,20 +1483,76 @@ module Net
       def slice_range(range)
         first = range.begin ||  0
         last  = range.end   || -1
-        last -= 1 if range.exclude_end? && range.end && last != STAR_INT
+        if range.exclude_end?
+          return remain_frozen_empty if last.zero?
+          last -= 1 if range.end && last != STAR_INT
+        end
         if (first * last).positive? && last < first
-          SequenceSet.empty
+          remain_frozen_empty
         elsif (min = at(first))
           max = at(last)
+          max = :* if max.nil?
           if    max == :*  then self & (min..)
           elsif min <= max then self & (min..max)
-          else                  SequenceSet.empty
+          else                  remain_frozen_empty
           end
         end
       end
 
       public
 
+      # Returns a copy of +self+ which only contains the numbers above +num+.
+      #
+      #   Net::IMAP::SequenceSet["5,10:22,50"].above(10) # to_s => "11:22,50"
+      #   Net::IMAP::SequenceSet["5,10:22,50"].above(20) # to_s => "21:22,50
+      #   Net::IMAP::SequenceSet["5,10:22,50"].above(30) # to_s => "50"
+      #
+      # This returns the same result as #intersection with <tt>((num+1)..)</tt>
+      # or #difference with <tt>(..num)</tt>.
+      #
+      #   Net::IMAP::SequenceSet["5,10:22,50"] & (11..)   # to_s => "11:22,50"
+      #   Net::IMAP::SequenceSet["5,10:22,50"] - (..10)   # to_s => "11:22,50"
+      #   Net::IMAP::SequenceSet["5,10:22,50"] & (21..)   # to_s => "21:22,50"
+      #   Net::IMAP::SequenceSet["5,10:22,50"] - (..20)   # to_s => "21:22,50"
+      #
+      # Related: #above, #-, #&
+      def above(num)
+        NumValidator.valid_nz_number?(num) or
+          raise ArgumentError, "not a valid sequence set number"
+        difference(..num)
+      end
+
+      # Returns a copy of +self+ which only contains numbers below +num+.
+      #
+      #   Net::IMAP::SequenceSet["5,10:22,50"].below(10) # to_s => "5"
+      #   Net::IMAP::SequenceSet["5,10:22,50"].below(20) # to_s => "5,10:19"
+      #   Net::IMAP::SequenceSet["5,10:22,50"].below(30) # to_s => "5,10:22"
+      #
+      # This returns the same result as #intersection with <tt>(..(num-1))</tt>
+      # or #difference with <tt>(num..)</tt>.
+      #
+      #   Net::IMAP::SequenceSet["5,10:22,50"] & (..9)    # to_s => "5"
+      #   Net::IMAP::SequenceSet["5,10:22,50"] - (10..)   # to_s => "5"
+      #   Net::IMAP::SequenceSet["5,10:22,50"] & (..19)   # to_s => "5,10:19"
+      #   Net::IMAP::SequenceSet["5,10:22,50"] - (20..)   # to_s => "5,10:19"
+      #
+      # When the set does not contain <tt>*</tt>, #below is identical to #limit
+      # with <tt>max: num - 1</tt>.  When the set does contain <tt>*</tt>,
+      # #below always drops it from the result.  Use #limit when the IMAP
+      # semantics for <tt>*</tt> must be enforced.
+      #
+      #   Net::IMAP::SequenceSet["5,10:22,50"].below(30)      # to_s => "5,10:22"
+      #   Net::IMAP::SequenceSet["5,10:22,50"].limit(max: 29) # to_s => "5,10:22"
+      #   Net::IMAP::SequenceSet["5,10:22,*"].below(30)       # to_s => "5,10:22"
+      #   Net::IMAP::SequenceSet["5,10:22,*"].limit(max: 29)  # to_s => "5,10:22,29"
+      #
+      # Related: #above, #-, #&, #limit
+      def below(num)
+        NumValidator.valid_nz_number?(num) or
+          raise ArgumentError, "not a valid sequence set number"
+        difference(num..)
+      end
+
       # Returns a frozen SequenceSet with <tt>*</tt> converted to +max+, numbers
       # and ranges over +max+ removed, and ranges containing +max+ converted to
       # end at +max+.
@@ -1272,6 +1570,7 @@ module Net
       #   Net::IMAP::SequenceSet["500:*"].limit(max: 37)
       #   #=> Net::IMAP::SequenceSet["37"]
       #
+      # Related: #limit!
       def limit(max:)
         max = to_tuple_int(max)
         if    empty?                      then self.class.empty
@@ -1286,6 +1585,7 @@ module Net
       #
       # Related: #limit
       def limit!(max:)
+        modifying! # short-circuit, and normalize the error message for JRuby
         star = include_star?
         max  = to_tuple_int(max)
         tuple_subtract [max + 1, STAR_INT]
@@ -1300,6 +1600,7 @@ module Net
       #
       # Related: #complement
       def complement!
+        modifying! # short-circuit, and normalize the error message for JRuby
         return replace(self.class.full) if empty?
         return clear                    if full?
         flat = @tuples.flat_map { [_1 - 1, _2 + 1] }
@@ -1313,6 +1614,7 @@ module Net
       #
       # The returned set's #string is sorted and deduplicated.  Adjacent or
       # overlapping elements will be merged into a single larger range.
+      # See SequenceSet@Ordered+and+Normalized+sets.
       #
       #   Net::IMAP::SequenceSet["1:5,3:7,10:9,10:11"].normalize
       #   #=> Net::IMAP::SequenceSet["1:7,9:11"]
@@ -1325,37 +1627,87 @@ module Net
       end
 
       # Resets #string to be sorted, deduplicated, and coalesced.  Returns
-      # +self+.
+      # +self+.  See SequenceSet@Ordered+and+Normalized+sets.
       #
       # Related: #normalize, #normalized_string
       def normalize!
+        modifying! # redundant check, to normalize the error message for JRuby
         @string = nil
         self
       end
 
       # Returns a normalized +sequence-set+ string representation, sorted
       # and deduplicated.  Adjacent or overlapping elements will be merged into
-      # a single larger range.  Returns +nil+ when the set is empty.
+      # a single larger range.  See SequenceSet@Ordered+and+Normalized+sets.
       #
       #   Net::IMAP::SequenceSet["1:5,3:7,10:9,10:11"].normalized_string
       #   #=> "1:7,9:11"
       #
-      # Related: #normalize!, #normalize
+      # Returns +nil+ when the set is empty.
+      #
+      # Related: #normalize!, #normalize, #string, #to_s
       def normalized_string
         @tuples.empty? ? nil : -@tuples.map { tuple_to_str _1 }.join(",")
       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_string_entries(@tuples.first(INSPECT_TRUNCATE_LEN)) + ","
+            tail = "," + export_string_entries(@tuples.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
+      private def count_entries
+        @string ? @string.count(",") + 1 : @tuples.count
+      end
+
+      ##
+      # :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)
@@ -1385,18 +1737,21 @@ module Net
 
       attr_reader :tuples # :nodoc:
 
+      def deep_copy_tuples; @tuples.map { _1.dup } end # :nodoc:
+
       private
 
       def remain_frozen(set) frozen? ? set.freeze : set end
+      def remain_frozen_empty; frozen? ? SequenceSet.empty : SequenceSet.new end
 
       # frozen clones are shallow copied
       def initialize_clone(other)
-        other.frozen? ? super : initialize_dup(other)
+        @tuples = other.deep_copy_tuples unless other.frozen?
+        super
       end
 
       def initialize_dup(other)
-        @tuples = other.tuples.map(&:dup)
-        @string = other.string&.-@
+        @tuples = other.deep_copy_tuples
         super
       end
 
@@ -1421,9 +1776,8 @@ module Net
         when Array       then set.flat_map { input_to_tuples _1 }
         when nil         then []
         else
-          raise DataFormatError,
-                "expected nz-number, range, string, or enumerable; " \
-                "got %p" % [set]
+          raise DataFormatError, "expected nz-number, range, '*', Set, Array; " \
+                                 "got %p" % [set]
         end
       end
 
@@ -1449,6 +1803,10 @@ module Net
       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 export_string_entries(entries)
+        -entries.map { tuple_to_str _1 }.join(",")
+      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)

data/lib/net/imap.rb

@@ -788,7 +788,7 @@ module Net
   # * {IMAP URLAUTH Authorization Mechanism Registry}[https://www.iana.org/assignments/urlauth-authorization-mechanism-registry/urlauth-authorization-mechanism-registry.xhtml]
   #
   class IMAP < Protocol
-    VERSION = "0.5.7"
+    VERSION = "0.5.10"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -801,6 +801,7 @@ module Net
     autoload :ResponseReader,         "#{dir}/response_reader"
     autoload :SASL,                   "#{dir}/sasl"
     autoload :SASLAdapter,            "#{dir}/sasl_adapter"
+    autoload :SequenceSet,            "#{dir}/sequence_set"
     autoload :StringPrep,             "#{dir}/stringprep"
 
     include MonitorMixin
@@ -809,6 +810,22 @@ module Net
       include SSL
     end
 
+    # :call-seq:
+    #   Net::IMAP::SequenceSet(set = nil) -> SequenceSet
+    #
+    # Coerces +set+ into a SequenceSet, using either SequenceSet.try_convert or
+    # SequenceSet.new.
+    #
+    # * When +set+ is a SequenceSet, that same set is returned.
+    # * When +set+ responds to +to_sequence_set+, +set.to_sequence_set+ is
+    #   returned.
+    # * Otherwise, returns the result from calling SequenceSet.new with +set+.
+    #
+    # Related: SequenceSet.try_convert, SequenceSet.new, SequenceSet::[]
+    def self.SequenceSet(set = nil)
+      SequenceSet.try_convert(set) || SequenceSet.new(set)
+    end
+
     # Returns the global Config object
     def self.config; Config.global end
 
@@ -1114,28 +1131,27 @@ module Net
 
     # Disconnects from the server.
     #
+    # Waits for receiver thread to close before returning.  Slow or stuck
+    # response handlers can cause #disconnect to hang until they complete.
+    #
     # Related: #logout, #logout!
     def disconnect
+      in_logout_state = try_state_logout?
       return if disconnected?
-      state_logout!
       begin
-        begin
-          # try to call SSL::SSLSocket#io.
-          @sock.io.shutdown
-        rescue NoMethodError
-          # @sock is not an SSL::SSLSocket.
-          @sock.shutdown
-        end
+        @sock.to_io.shutdown
       rescue Errno::ENOTCONN
         # ignore `Errno::ENOTCONN: Socket is not connected' on some platforms.
       rescue Exception => e
         @receiver_thread.raise(e)
       end
+      @sock.close
       @receiver_thread.join
-      synchronize do
-        @sock.close
-      end
       raise e if e
+    ensure
+      # Try again after shutting down the receiver thread.  With no reciever
+      # left to wait for, any remaining locks should be _very_ brief.
+      state_logout! unless in_logout_state
     end
 
     # Returns true if disconnected from the server.
@@ -3062,8 +3078,8 @@ module Net
             raise @exception || Net::IMAP::Error.new("connection closed")
           end
         ensure
+          remove_response_handler(response_handler)
           unless @receiver_thread_terminating
-            remove_response_handler(response_handler)
             put_string("DONE#{CRLF}")
             response = get_tagged_response(tag, "IDLE", idle_response_timeout)
           end
@@ -3346,8 +3362,6 @@ module Net
       rescue Exception => ex
         @receiver_thread_exception = ex
         # don't exit the thread with an exception
-      ensure
-        state_logout!
       end
     end
 
@@ -3429,6 +3443,8 @@ module Net
           @idle_done_cond.signal
         end
       end
+    ensure
+      state_logout!
     end
 
     def get_tagged_response(tag, cmd, timeout = nil)
@@ -3791,15 +3807,29 @@ module Net
     end
 
     def state_unselected!
-      state_authenticated! if connection_state.to_sym == :selected
+      synchronize do
+        state_authenticated! if connection_state.to_sym == :selected
+      end
     end
 
     def state_logout!
+      return true if connection_state in [:logout, *]
       synchronize do
+        return true if connection_state in [:logout, *]
         @connection_state = ConnectionState::Logout.new
       end
     end
 
+    # don't wait to aqcuire the lock
+    def try_state_logout?
+      return true if connection_state in [:logout, *]
+      return false unless acquired_lock = mon_try_enter
+      state_logout!
+      true
+    ensure
+      mon_exit if acquired_lock
+    end
+
     def sasl_adapter
       SASLAdapter.new(self, &method(:send_command_with_continuations))
     end

data/rakelib/string_prep_tables_generator.rb

@@ -388,9 +388,11 @@ class StringPrepTablesGenerator
   end
 
   def asgn_mapping(name, replacement = to_map(tables[name]))
+    indent = "  " * 2
+    replacement = replacement.inspect.gsub(/" => "/, '"=>"')
     cname = name.tr(?., ?_).upcase
-    "# Replacements for %s\n%s%s = %p.freeze" % [
-      "IN_#{name}", "  " * 2, "MAP_#{cname}", replacement,
+    "# Replacements for %s\n%s%s = %s.freeze" % [
+      "IN_#{name}", indent, "MAP_#{cname}", replacement,
     ]
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.5.7
+  version: 0.5.10
 platform: ruby
 authors:
 - Shugo Maeda
@@ -129,7 +129,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby client api for Internet Message Access Protocol
 test_files: []