✨ Add `SequenceSet#xor!" for in-place XOR

This is simply a mutating version of `#^` or `#xor`.

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

@@ -34,13 +34,12 @@ prelude: |
         subtract dup.subtract(SequenceSet.new(other))
       end
 
-      # TODO: add this as a public method
       def xor!(other) # :nodoc:
         modifying!
         copy  = dup
         other = SequenceSet.new(other)
         merge(other).subtract(other.subtract(copy.complement!))
-      end
+      end unless instance_methods.include?(:xor!)
 
       # L - (L ^ R)
       def and2!(other)

benchmarks/sequence_set-xor.yml

@@ -70,6 +70,7 @@ prelude: |
 
 benchmark:
   "      L ^ R":             l, r = sets; l ^ r
+  "      L.xor! R":          l, r = sets; l.xor! r
   "      (L | R) - (R & L)": l, r = sets; (l | r) - (r & l)
   "0.5.8 (L | R) - (R & L)": l, r = sets; l.xor0  r
   "dup1  (L | R) - (R & L)": l, r = sets; l.xor1  r

lib/net/imap/sequence_set.rb

@@ -345,6 +345,8 @@ class IMAP
     #   this set; returns +self+.
     # - #complement!: In-place set #complement.  Replaces the contents of this
     #   set with its own #complement; returns +self+.
+    # - #xor!: In-place +XOR+ operation.  Adds numbers that are unique to the
+    #   other set and removes numbers that are common to both; returns +self+.
     #
     # <i>Order preserving:</i>
     #
@@ -902,7 +904,7 @@ def &(other) remain_frozen dup.intersect! other end
       # * <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
+      def ^(other) remain_frozen dup.xor! other end
       alias xor :^
 
       # :call-seq:
@@ -1629,6 +1631,24 @@ def intersect!(other)
         subtract SequenceSet.new(other).complement!
       end
 
+      # In-place set #xor.  Adds any numbers in +other+ that are missing from
+      # this set, removes any numbers in +other+ that are already in this set,
+      # and returns +self+.
+      #
+      # +other+ can be any object that would be accepted by ::new.
+      #
+      #     set = Net::IMAP::SequenceSet.new(1..5)
+      #     set.xor! [2, 4, 6]
+      #     set #=> Net::IMAP::SequenceSet["1,3,5:6"]
+      #
+      # Related: #xor, #merge, #subtract
+      def xor!(other)
+        modifying!
+        other = IMAP::SequenceSet(other)
+        both = self & other
+        merge(other).subtract(both)
+      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

@@ -121,6 +121,9 @@ def compare_to_reference_set(nums, set, seqset)
       assert_equal xor, (lhs | rhs) - (lhs & rhs)
       assert_equal xor, (lhs ^ mid) ^ (mid ^ rhs)
       assert_equal xor, ~lhs ^ ~rhs
+      mutable = lhs.dup
+      assert_equal xor, mutable.xor!(rhs)
+      assert_equal xor, mutable
     end
   end
 
@@ -172,6 +175,7 @@ def compare_to_reference_set(nums, set, seqset)
   data "#subtract",    ->{ _1.subtract  1 }
   data "#limit!",      ->{ _1.limit! max: 10 }
   data "#intersect!",  ->{ _1.intersect! SequenceSet[1..100] }
+  data "#xor!",        ->{ _1.xor!       SequenceSet[9..98]  }
   data "#complement!", :complement!
   data "#normalize!",  :normalize!
   test "frozen error message" do |modification|