fast_xor 1.0.1

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2006-2009 Steve Sloan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/README.rdoc

@@ -0,0 +1,33 @@
+= String XOR Ruby Extension
+
++fast_xor+ is a simple extension which provides fast in-place String XOR functions (suitable for cryptography).
+
+== How do you use it?
+
+  require 'xor'
+
+  # two-argument version
+  a, b = 'a string', 'another string'
+  a.xor!(b)
+  a == "\000N\034\000\032\f\034G"
+
+  # three-argument version
+  a, b, c = 'a string', 'another string', 'yet another string'
+  a.xor!(b, c)
+  a == "y+h {bs3"
+
+== How fast is "Fast"?
+
+On my computer, about 1,000x faster than pure Ruby (your mileage my vary):
+
+  $ ruby test/benchmark.rb
+        user     system      total        real
+  Ruby:  2.070000   0.930000   3.000000 (  3.004088)
+  C   :  0.010000   0.000000   0.010000 (  0.003045)
+
+
+Author::    Steve Sloan (mailto:steve@finagle.org)
+Website::   http://github.com/CodeMonkeySteve/fast_xor
+Copyright:: Copyright (c) 2009 Steve Sloan
+License::   MIT
+

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rake'
+require 'rake/clean'
+require 'rake/extensiontask'
+require 'rake/testtask'
+require 'jeweler'
+
+namespace 'xor' do
+  desc "Build the XOR extension"
+  Rake::ExtensionTask.new :xor do |t|
+    t.dir = 'ext'
+  end
+end
+
+task :test => 'xor:xor'
+Rake::TestTask.new do |t|
+  t.libs << 'ext'
+  t.test_files = FileList['test/test_*.rb']
+  t.verbose = true
+end
+
+task :all => ['xor:xor', :test]
+task :default => :all
+
+Jeweler::Tasks.new do |g|
+  g.name = 'fast_xor'
+  g.summary = 'Fast String XOR operator'
+  g.description = 'Provides a C-optimized method for in-place XORing of two (or three) strings'
+  g.email = 'steve@finagle.org'
+  g.homepage = 'http://github.com/CodeMonkeySteve/fast_xor'
+  g.authors = ['Steve Sloan']
+
+  g.files = %w(
+    README.rdoc MIT-LICENSE
+    rake/extensiontask.rb
+    ext/xor.c
+    test/test_xor.rb
+    test/benchmark.rb
+  )
+  g.extensions = ['Rakefile']
+  g.require_paths = %w(ext)
+
+#  g.has_rdoc = true
+#  g.rdoc_options = %w| --line-numbers --inline-source --main README.rdoc |
+#  g.extra_rdoc_files = %w| README.rdoc |
+end
+Jeweler::GemcutterTasks.new

data/ext/xor.c

@@ -0,0 +1,55 @@
+#include <stdio.h>
+#include <ruby.h>
+
+VALUE string_xor( int argc, VALUE *argv, VALUE self ) {
+  const char *src = 0;
+  char *dest = 0 ;
+  size_t length = 0;
+
+  if ( (argc < 1) || (argc > 2) ) {
+    rb_raise( rb_eArgError, "wrong # of arguments(%d for 1 or 2)", argc );
+    return Qnil;
+  }
+
+  dest = STR2CSTR(self);
+  length = RSTRING(self)->len;
+
+  if ( TYPE(argv[0]) == T_STRING ) {
+    src = STR2CSTR(argv[0]);
+    size_t l = RSTRING(argv[0])->len;
+    if ( l < length )
+      length = l;
+  } else {
+    rb_raise( rb_eTypeError, "in method '" "xor" "', argument " "1"" of type '" "String""'" );
+    return Qnil;
+  }
+
+  if ( argc == 1 ) {
+    for ( ; length--; ++dest, ++src )
+      *dest ^= *src;
+
+  } else {
+    const char *src2 = 0;
+
+    if ( TYPE(argv[1]) == T_STRING ) {
+      src2 = STR2CSTR(argv[1]);
+      size_t l = RSTRING(argv[1])->len;
+      if ( l < length )
+        length = l;
+    } else {
+      rb_raise( rb_eTypeError, "in method '" "xor" "', argument " "2"" of type '" "String""'" );
+      return Qnil;
+    }
+
+    for ( ; length--; ++dest, ++src, ++src2 )
+      *dest ^= *src ^ *src2;
+  }
+
+  return self;
+}
+
+
+void Init_xor( void )
+{
+  rb_define_method( rb_cString, "xor!", ((VALUE (*)(ANYARGS)) string_xor), -1 );
+}

data/rake/extensiontask.rb

@@ -0,0 +1,191 @@
+require 'rake'
+require 'rake/clean'
+require 'rake/tasklib'
+
+# Rake tasks to build Ruby extensions
+
+module Rake
+
+  # Create a build task that will generate a Ruby extension (e.g. .so) from one or more
+  # C (.c) or C++ (.cc, .cpp, .cxx) files, and is intended as a replcaement for mkmf.
+  # It determines platform-specific settings (e.g. file extensions, compiler flags, etc.)
+  # from rbconfig (note: examples assume *nix file extensions).
+  #
+  # *Note*: Strings vs Symbols
+  # In places where filenames are expected (e.g. lib_name and objs), Strings are used
+  # as verbatim filenames, while, Symbols have the platform-dependant extension
+  # appended (e.g. '.so' for libraries and '.o' for objects).  Also, only Symbols
+  # have #dir prepended to them.
+  #
+  # Example:
+  #   desc "build sample extension"
+  #   # build sample.so (from foo.{c,cc,cxx,cpp}, through foo.o)
+  #   Rake::ExtensionTask.new :sample => :foo do |t|
+  #     # all extension files under this directory
+  #     t.dir = 'ext'
+  #     # link libraries (libbar.so)
+  #     t.link_libs << 'bar'
+  #   end
+  #
+  # Author::    Steve Sloan (mailto:steve@finagle.org)
+  # Copyright:: Copyright (c) 2006 Steve Sloan
+  # License::   GPL
+
+  class ExtensionTask < Rake::TaskLib
+    # The name of the extension
+    attr_accessor :name
+
+    # The filename of the extension library file (e.g. 'extension.so')
+    attr_accessor :lib_name
+
+    # Object files to build and link into the extension.
+    attr_accessor :objs
+
+    # The directory where the extension files (source, output, and
+    # intermediate) are stored.
+    attr_accessor :dir
+
+    # Environment configuration -- i.e. CONFIG from rbconfig, with a few other
+    # settings, and converted to lowercase-symbols.
+    attr_accessor :env
+
+    # Additional link libraries
+    attr_accessor :link_libs
+
+    # Same arguments as Rake::define_task
+    def initialize( args, &blk )
+      @env = @@DefaultEnv.dup
+      @name, @objs = resolve_args(args)
+      set_defaults
+      yield self  if block_given?
+      define_tasks
+    end
+
+    # Generate default values.  This is called from initialize _before_ the
+    # yield block.
+    #
+    # Defaults:
+    # - lib_name: name.so
+    # - objs: name.o (<- name.{c,cxx,cpp,cc})
+    # - dir: .
+    # - link_libs: <none>
+    def set_defaults
+      @lib_name ||= name.to_sym
+      @objs = [name.to_sym]  unless @objs and @objs.any?
+      @dir ||= '.'
+      @link_libs ||= []
+    end
+
+    # Defines the library task.
+    def define_tasks
+      output_objs = @objs.collect { |obj| filepath obj, :objext }
+      output_lib = filepath lib_name, :dlext
+
+      task name => output_lib
+
+      file output_lib => output_objs do |t|
+        sh_cmd :ldshared, :dldflags, :ldflags,
+               {'-L' => :libdirs}, '-o', output_lib,
+               output_objs.join(' '),
+               link_libs.join(' '),
+               :libs, :dldlibs, :librubyarg_shared
+      end
+
+      CLEAN.include output_objs
+      CLOBBER.include output_lib
+      define_rules
+    end
+
+    # Defines C and C++ source-to-object rules, using the source extensions from env.
+    def define_rules
+      for ext in env[:c_exts]
+        Rake::Task.create_rule '.'+env[:objext] => '.'+ext do |r|
+          sh_cmd :cc, :cflags, :cppflags, {'-D' => :defines}, {'-I' => :includedirs}, {'-I' => :topdir},
+                '-c', '-o', r.name, r.sources
+        end
+      end
+
+      for ext in env[:cpp_exts]
+        Rake::Task.create_rule '.'+env[:objext] => '.'+ext do |r|
+          sh_cmd :cxx, :cxxflags, :cppflags, {'-D' => :defines}, {'-I' => :includedirs}, {'-I' => :topdir},
+                '-o', r.name, '-c', r.sources
+        end
+      end
+    end
+
+    class << self
+      # The default environment for all extensions.
+      @@DefaultEnv = {}
+      def env
+        @@DefaultEnv
+      end
+      def env=(e)
+        @@DefaultEnv = e
+      end
+
+      Config::CONFIG.merge(ENV).each { |k, v| @@DefaultEnv[k.downcase.to_sym] = v }
+      @@DefaultEnv = {
+        :cxx => 'c++',
+        :cxxflags => '',
+        :c_exts => ['c'],
+        :cpp_exts => ['cc', 'cxx', 'cpp'],
+        :includedirs => [],
+        :libdirs => [],
+      }.update(@@DefaultEnv)
+    end
+
+  protected
+
+    # Handles convenience filenames:
+    # * f (String) => f
+    # * f (Symbol) => dir/f.ext
+    def filepath( f, ext )
+      ext = env[ext]  if Symbol === ext
+      Symbol === f ? File.join( dir, "#{f}.#{ext}" ) : f
+    end
+
+    # Convenience function for cnstructing command lines for build tools.
+    def optify( *opts )
+      return optify(*opts.first)  if opts.size == 1 and opts.first.kind_of? Array
+      opts.collect do |opt|
+        case opt
+          when String then  opt
+          when Symbol then  optify env[opt]
+          when Hash
+            opt.collect do |k, v|
+              v = env[v]  if v.kind_of? Symbol
+              if v.kind_of? Array
+                optify v.collect { |w| k.to_s + w.to_s }
+              elsif v
+                k.to_s + v.to_s
+              end
+            end
+          else
+            opt.to_s
+        end
+      end.join(' ').squeeze(' ')
+    end
+
+    def sh_cmd( cmd, *opts )
+      sh optify( cmd, *opts )
+    end
+
+    # For some reason, Rake::TaskManager.resolve_args can't be found, so snarf it.
+    def resolve_args(args)
+      case args
+      when Hash
+        fail "Too Many Task Names: #{args.keys.join(' ')}" if args.size > 1
+        fail "No Task Name Given" if args.size < 1
+        task_name = args.keys[0]
+        deps = args[task_name]
+        deps = [deps] if (String===deps) || (Regexp===deps) || (Proc===deps)
+      else
+        task_name = args
+        deps = []
+      end
+      [task_name, deps]
+    end
+
+  end
+
+end

data/test/benchmark.rb

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+$: << File.dirname($0) + '/../ext'
+require 'benchmark'
+
+class String
+  def slow_xor!(other)
+    i = 0
+    other.each_byte { |b|  self[i] ^= b ; i += 1 }
+  end
+
+ require 'xor'
+ alias_method :fast_xor!, :xor!
+end
+
+a = ([255].pack('C')) * (2**17)   # 128k
+b = a.dup
+
+n = 10
+Benchmark.bm do |x|
+  x.report('Ruby:') do  n.times { a.slow_xor! b }  end
+  x.report('C   :') do  n.times { a.fast_xor! b }  end
+end
+

data/test/test_xor.rb

@@ -0,0 +1,45 @@
+require 'test/unit'
+require 'xor'
+
+class XORTest < Test::Unit::TestCase
+  def setup
+    @len = 16
+    @zero = [0x00].pack('C') * @len
+    @one  = [0xFF].pack('C') * @len
+    @x = (0...@len).collect { rand 256 }.pack('C*')
+    @invx = (0...@len).collect { |i| @x[i] ^ 0xFF }.pack('C*')
+  end
+
+  def assert_equal( a, b )
+    super a.unpack('H*'), b.unpack('H*')
+  end
+
+  def test_xor_same
+    assert_equal @zero, @x.dup.xor!(@x)
+    assert_equal @one,  @x.dup.xor!(@invx)
+    assert_equal @x,    @x.dup.xor!(@zero)
+    assert_equal @invx, @x.dup.xor!(@one)
+  end
+
+  def test_xor2_same
+    assert_equal @x,    @x.dup.xor!(@x, @x)
+    assert_equal @invx, @x.dup.xor!(@x, @invx)
+    assert_equal @zero, @x.dup.xor!(@x, @zero)
+    assert_equal @one,  @x.dup.xor!(@x, @one)
+
+    assert_equal @invx, @x.dup.xor!(@invx, @x)
+    assert_equal @x,    @x.dup.xor!(@invx, @invx)
+    assert_equal @one,  @x.dup.xor!(@invx, @zero)
+    assert_equal @zero, @x.dup.xor!(@invx, @one)
+
+    assert_equal @zero, @x.dup.xor!(@zero, @x)
+    assert_equal @one,  @x.dup.xor!(@zero, @invx)
+    assert_equal @invx, @x.dup.xor!(@zero, @one)
+    assert_equal @x,    @x.dup.xor!(@zero, @zero)
+
+    assert_equal @one,  @x.dup.xor!(@one, @x)
+    assert_equal @zero, @x.dup.xor!(@one, @invx)
+    assert_equal @invx, @x.dup.xor!(@one, @zero)
+    assert_equal @x,    @x.dup.xor!(@one, @one)
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification 
+name: fast_xor
+version: !ruby/object:Gem::Version 
+  version: 1.0.1
+platform: ruby
+authors: 
+- Steve Sloan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-26 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Provides a C-optimized method for in-place XORing of two (or three) strings
+email: steve@finagle.org
+executables: []
+
+extensions: 
+- Rakefile
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- MIT-LICENSE
+- README.rdoc
+- ext/xor.c
+- rake/extensiontask.rb
+- test/benchmark.rb
+- test/test_xor.rb
+has_rdoc: true
+homepage: http://github.com/CodeMonkeySteve/fast_xor
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- ext
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Fast String XOR operator
+test_files: 
+- test/benchmark.rb
+- test/test_xor.rb