🚧✨ Add `SequenceSet#xor!"

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

TODO:
* rdoc on method
* rdoc in class "What's Here"

Author: nevans

benchmarks/sequence_set-and.yml

@@ -33,14 +33,6 @@ 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
-
       # L - (L ^ R)
       def and2!(other)
         modifying!

benchmarks/sequence_set-xor.yml

@@ -66,6 +66,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

@@ -743,7 +743,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:
@@ -1472,6 +1472,13 @@ def intersect!(other) # :nodoc:
         subtract SequenceSet.new(other).complement!
       end
 
+      # TODO: document and directly test this
+      def xor!(other) # :nodoc:
+        modifying!
+        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

@@ -104,6 +104,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
 
@@ -155,6 +158,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|