fny / xorcist

Blazing-fast-cross-platform-monkey-patch-free string XOR

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! 🍻

xorcist's Issues

Travis CI Issue with JRuby 9.2.7

9.2.7 test isn't working on Travis for some reason.

https://travis-ci.community/t/unable-to-test-against-jruby-9-2-7-0/3138

Recommend JRuby 9.2.7 if you keep refinements

Hey, @enebo pointed me to your README where you mention JRuby failing the build because of refinements. I've been working in getting refinements working better, so I figured I'd see if xorcist works better on JRuby master (which will be 9.2.7):

[] ~/projects/xorcist $ bundle exec rake
Run options: --seed 8423

# Running:

........

Fabulous run in 0.021027s, 380.4612 runs/s, 903.5954 assertions/s.

8 runs, 19 assertions, 0 failures, 0 errors, 0 skips

[] ~/projects/xorcist $ jruby -v
jruby 9.2.7.0-SNAPSHOT (2.5.3) 2019-03-05 2c4518f OpenJDK 64-Bit Server VM 25.202-b08 on 1.8.0_202-b08 +jit [darwin-x86_64]

So you should be good to go using refinements on JRuby 9.2.7 or higher. If you decide to keep the refinements, do update the README to mention that requirement.

Thank you!

Pull in error handling from fast_xor

see: https://github.com/CodeMonkeySteve/fast_xor/blob/master/ext/xor/xor.c

irb(main):004:0> class A; end
=> nil
irb(main):005:0> Xorcist.xor(A,A)
=> #<Class:0x00007f1d3fed92f8>

This is a security issue cause you could causing segfaults here.

Enable Github Packages

JRuby 9.3 Compatibility

For some reason, Xorcist.xor! is not being required properly when importing the JAR.

https://github.com/fny/xorcist/runs/7636403550?check_suite_focus=true

I've reached out to the JRuby team: jruby/jruby#7287