🔀 Merge pull request #549 from ruby/sequence_set/intersect-bang

✨ Add `SequenceSet#intersect!` for in-place set `AND`

Author: nevans

benchmarks/sequence_set-and.yml

@@ -65,6 +65,7 @@ prelude: |
 
 benchmark:
   "      L & R":       l, r = sets; l & r
+  "mut!  L & R":       l, r = sets; l.intersect! r
   "      L - ~R":      l, r = sets; l - ~r
   "and0  L - ~R":      l, r = sets; l.and0  r
   "and0! L - ~R":      l, r = sets; l.and0! r

benchmarks/sequence_set-xor.yml

@@ -31,11 +31,10 @@ prelude: |
         merge(other).subtract(other.subtract(copy.complement!))
       end
 
-      # TODO: add this as a public method
       def intersect!(other) # :nodoc:
         modifying!
         subtract SequenceSet.new(other).complement!
-      end
+      end unless instance_methods.include?(:intersect!)
 
       # (L | R) - (L & R)
       def xor2!(other)

lib/net/imap/sequence_set.rb

@@ -332,7 +332,7 @@ class IMAP
     #   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>
     #
@@ -341,8 +341,10 @@ class IMAP
     # - #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+.
     #
     # <i>Order preserving:</i>
     #
@@ -355,18 +357,20 @@ class IMAP
     #   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+.
     # - #delete: Removes a given element from the set; returns +self+.
     # - #delete?: If the given element is included in the set, removes it and
     #   returns it; otherwise, returns +nil+.
     # - #delete_at: Removes the number at a given offset.
+    # - #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+.
     #
@@ -873,9 +877,7 @@ def -(other) remain_frozen dup.subtract other end
       # * <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
+      def &(other) remain_frozen dup.intersect! other end
       alias intersection :&
 
       # :call-seq:
@@ -1069,8 +1071,8 @@ def slice!(index, length = nil)
         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.
       #
@@ -1083,8 +1085,8 @@ def merge(*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.
       #
@@ -1595,8 +1597,9 @@ def limit!(max:)
 
       # :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!
@@ -1610,6 +1613,22 @@ def complement!
         normalize!
       end
 
+      # 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.
+      #
+      #     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!
+        subtract SequenceSet.new(other).complement!
+      end
+
       # Returns a new SequenceSet with a normalized string representation.
       #
       # The returned set's #string is sorted and deduplicated.  Adjacent or

test/net/imap/test_sequence_set.rb

@@ -89,6 +89,9 @@ def compare_to_reference_set(nums, set, seqset)
       assert_equal intersection, lhs - (lhs - rhs)
       assert_equal intersection, lhs - (lhs ^ rhs)
       assert_equal intersection, lhs ^ (lhs - rhs)
+      mutable = lhs.dup
+      assert_equal intersection, mutable.intersect!(rhs)
+      assert_equal intersection, mutable
     end
   end
 
@@ -168,6 +171,7 @@ def compare_to_reference_set(nums, set, seqset)
   data "#merge",       ->{ _1.merge     1 }
   data "#subtract",    ->{ _1.subtract  1 }
   data "#limit!",      ->{ _1.limit! max: 10 }
+  data "#intersect!",  ->{ _1.intersect! SequenceSet[1..100] }
   data "#complement!", :complement!
   data "#normalize!",  :normalize!
   test "frozen error message" do |modification|