Xorcist 👻

Blazing-fast-cross-platform-monkey-patch-free string XOR. Yes, that means JRuby too.

Supported platforms: MRI (v2+), JRuby (v9.2+), Truffle (v21+), Truffle+GraalVM (v21+).

Usage

require 'xorcist'

a, b = 'a', 'b'
Xorcist.xor(a, b) # => "\u0003"
a # => 'a'
Xorcist.xor!(a, b) # => "\u0003"
a # => "\u0003"
Xorcist.xor!(a.freeze, b) # => RuntimeError!

You can include Xorcist to expose its methods:

require 'xorcist'
include Xorcist

a, b = 'a', 'b'
xor(a, b)
xor!(a, b)

Refinements on String are also available:

require 'xorcist'
require 'xorcist/refinements'
using Xorcist::Refinements

a, b = 'a', 'b'
a.xor(b)
a.xor!(b)

Note: Refinements will not work in JRuby 9.2.6 and below. This isn't an issue for earlier versions of JRuby 9.0-9.1 or JRuby 9.2.7+.

You can also monkey patch String if you're into that:

require 'xorcist'
require 'xorcist/string_methods'
String.include(Xorcist::StringMethods)

Encodings

Note the precise encoding xor's output is undefined in the v1.0-1.x releases. In MRI xor! will return a string using your default encoding. With JRuby, xor! will return an ASCII-8BIT string.

Benchmarks

Run from my Macbook. Run 'em yourself with bin/benchmark. You'll need to have benchmark-ips installed.

MRI

ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [arm64-darwin21]

Warming up --------------------------------------
                ruby    91.478k i/100ms
             xorcist     1.043M i/100ms
Calculating -------------------------------------
                ruby    928.443k (± 2.0%) i/s -      4.665M in   5.026920s
             xorcist     10.438M (± 1.4%) i/s -     53.187M in   5.096610s

JRuby

jruby 9.3.6.0 (2.6.8) 2022-06-27 7a2cbcd376 OpenJDK 64-Bit Server VM 18.0.2+0 on 18.0.2+0 +jit [arm64-darwin]

Warming up --------------------------------------
                ruby   236.487k i/100ms
             xorcist   813.234k i/100ms
Calculating -------------------------------------
                ruby      2.673M (±11.0%) i/s -     13.243M in   5.025536s
             xorcist     20.432M (±24.4%) i/s -     90.269M in   5.000974s

Installation

Add this line to your application's Gemfile:

gem 'xorcist'

And then execute:

$ bundle

Or install it yourself as:

$ gem install xorcist

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/fny/xorcist.

License

The gem is available as open source under the terms of the MIT License.

Special Thanks To...

• Steve Sloan for his fast_xor gem from which most of the tests are borrowed
• James Coglan for his guide on writing a JRuby Java extension
• Thomas Leitner for a faster pure Ruby XOR implementation that's used in the benchmark
• The JRuby Team for their assistance in debugging various issues over the years
• To all contributers! 🍻