✨ Add SequenceSet#intersect! for in-place AND

This is simply the mutating version of `#&` or `#intersection`.

Although there is room for big performance improvement here, the
algorithm remains unchanged, so any performance improvement is small.

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

@@ -365,6 +365,8 @@ class IMAP
     # - #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: In-place set #difference.  Removes all members of the given
@@ -875,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:
@@ -1613,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|