scatter_swap 0.0.1 → 0.0.2

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format doc

data/README.md

@@ -1,5 +1,55 @@
 # ScatterSwap
 
+This is the hashing function behind ObfuscateId.
+https://github.com/namick/obfuscate_id
+
+Designing a hash function is a bit of a black art and
+being that I don't have math background, I must resort
+to this simplistic swaping and scattering of array elements.
+
+After writing this and reading/learning some elemental hashing techniques,
+I realize this library is what is known as a Minimal perfect hash function:
+http://en.wikipedia.org/wiki/Perfect_hash_function#Minimal_perfect_hash_function
+
+I welcome all improvements :-)
+
+If you have some comments or suggestions, please contact me on github
+https://github.com/namick
+
+- nathan amick
+
+
+This library is built for integers that can be expressed with 10 digits:
+It zero pads smaller numbers... so the number 1 is expressed with:
+0000000001
+
+The biggest number it can deal with is:
+9999999999
+
+Since we are working with a limited sequential set of input integers, 10 billion,
+this algorithm will suffice for simple id obfuscation for many web apps.
+The largest value that Ruby on Rails default id, Mysql INT type, is just over 2 billion (2147483647)
+which is the same as 2 to the power of 31 minus 1, but considerably less than 10 billion.
+
+ScatterSwap is an integer hash function designed to have:
+- zero collisions ( http://en.wikipedia.org/wiki/Perfect_hash_function )
+- achieve avalanche ( http://en.wikipedia.org/wiki/Avalanche_effect )
+- reversable
+
+We do that by combining two distinct strategies.
+
+1. Scattering - whereby we take the whole number, slice it up into 10 digits
+and rearange their places, yet retaining the same 10 digits.  This allows
+us to preserve the sum of all the digits, regardless of order.  This sum acts
+as a key to reverse this scattering effect.
+
+2. Swapping - when dealing with many sequential numbers that we don't want
+to look similar, scattering wont do us much good because so many of the
+digits are the same; it deoesn't help to scatter 9 zeros around, so we need
+to swap out each of those zeros for something else.. something different
+for each place in the 10 digit array; for this, we need a map so that we
+can reverse it.
+
 TODO: Write a gem description
 
 ## Installation

data/lib/scatter_swap/hasher.rb

@@ -0,0 +1,81 @@
+module ScatterSwap
+  class Hasher
+    attr_accessor :working_array
+
+    def initialize(original_integer, spin = 0)
+      @original_integer = original_integer
+      @spin = spin
+      zero_pad = original_integer.to_s.rjust(10, '0')
+      @working_array = zero_pad.split("").collect {|d| d.to_i}
+    end
+
+    # obfuscates an integer up to 10 digits in length
+    def hash
+      swap
+      scatter
+      completed_string
+    end
+
+    # de-obfuscates an integer
+    def reverse_hash
+      unscatter
+      unswap
+      completed_string
+    end
+
+    def completed_string
+      @working_array.join
+    end
+
+    # We want a unique map for each place in the original number
+    def swapper_map(index)
+      array = (0..9).to_a
+      10.times.collect.with_index do |i|
+        array.rotate!(index + i ^ spin).pop
+      end
+    end
+
+    # Using a unique map for each of the ten places,
+    # we swap out one number for another
+    def swap
+      @working_array = @working_array.collect.with_index do |digit, index|
+        swapper_map(index)[digit]
+      end
+    end
+
+    # Reverse swap
+    def unswap
+      @working_array = @working_array.collect.with_index do |digit, index|
+        swapper_map(index).rindex(digit)
+      end
+    end
+
+    # Rearrange the order of each digit in a reversable way by using the 
+    # sum of the digits (which doesn't change regardless of order)
+    # as a key to record how they were scattered
+    def scatter
+      sum_of_digits = @working_array.inject(:+).to_i
+      @working_array = 10.times.collect do 
+        @working_array.rotate!(spin ^ sum_of_digits).pop
+      end
+    end
+
+    # Reverse the scatter
+    def unscatter
+      scattered_array = @working_array
+      sum_of_digits = scattered_array.inject(:+).to_i
+      @working_array = []
+      @working_array.tap do |unscatter| 
+        10.times do
+          unscatter.push scattered_array.pop
+          unscatter.rotate! (sum_of_digits ^ spin) * -1
+        end
+      end
+    end
+
+    # Add some spice so that different apps can have differently mapped hashes
+    def spin
+      @spin || 0
+    end
+  end
+end

data/lib/scatter_swap/run.rb

@@ -0,0 +1,93 @@
+require 'scatter_swap'
+
+# This file is spike code and is not part of the library
+# 
+# While developing this, I used this file to visualize what was going on with the numbers
+#
+# You can uncomment various methods at the bottom and then run it like this:
+#
+# watch -n1 ruby run_scatter_swap.rb
+# 
+# tweak the code a bit and see instant visual changes in the generated numbers
+
+def visualize_scatter_and_unscatter
+  # change this number to experiment with different values
+  rotations = 99
+
+  original = ScatterSwap.arrayify(123456789)
+  scattered = []
+  unscattered = []
+  puts original.join
+  puts "rotate!(#{rotations})"
+  10.times do
+    puts original.rotate!(rotations).join + "->" + scattered.push(original.pop).join
+  end
+  puts "scattered"
+  puts scattered.join
+  10.times do
+    puts unscattered.push(scattered.pop).join + "->" + unscattered.rotate!(rotations * -1).join
+  end
+
+  puts unscattered.join
+end
+
+
+def visualize_swapper_map
+  puts "swapper map"
+  10.times do |index|
+    key = 1
+    puts ScatterSwap.swapper_map(index).join.to_s
+  end
+end
+
+def visualize_hash
+  puts "hash"
+  40.times do |integer|
+    output = "|"
+    3.times do |index|
+      output += " #{(integer + (123456789 * index)).to_s.rjust(5, ' ')}"
+      output += " => #{hashed = ScatterSwap.hash(integer + (123456789 * index) ) }"
+      output += " => #{ScatterSwap.reverse_hash(hashed) } |"
+    end
+    puts output
+  end
+end
+
+
+def visualize_scatter
+  puts "original      scattered     unscattered"
+  20.times do |integer|
+    output = ""
+    2.times do |index|
+      original = ScatterSwap.arrayify(integer + (123456789 * index))
+      scattered = ScatterSwap.scatter(original.clone)
+      unscattered = ScatterSwap.unscatter(scattered.clone)
+      output += "#{original.join}" 
+      output += " => #{scattered.join}"
+      output += " => #{unscattered.join}    |    "
+    end
+    puts output
+  end
+end
+
+
+# find hash for lots of spins
+def visualize_spin
+  2000.times do |original|
+    hashed_values = []
+    9000000000.times do |spin|
+      hashed =  ScatterSwap.hash(original, spin)
+      if hashed_values.include? hashed
+        puts "collision: #{original} - #{spin} - #{hashed}"
+        break
+      end
+      hashed_values.push hashed
+    end
+  end
+end
+
+#visualize_spin
+#visualize_hash
+#visualize_scatter_and_unscatter
+#visualize_scatter
+#visualize_swapper_map

data/lib/scatter_swap/version.rb

@@ -1,3 +1,3 @@
 module ScatterSwap
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/scatter_swap.rb

@@ -1,140 +1,12 @@
 require "scatter_swap/version"
+require "scatter_swap/hasher"
 
-class ScatterSwap
-  # This is the hashing function behind ObfuscateId.
-  # https://github.com/namick/obfuscate_id
-  #
-  # Designing a hash function is a bit of a black art and
-  # being that I don't have math background, I must resort
-  # to this simplistic swaping and scattering of array elements.
-  #
-  # After writing this and reading/learning some elemental hashing techniques,
-  # I realize this library is what is known as a Minimal perfect hash function:
-  # http://en.wikipedia.org/wiki/Perfect_hash_function#Minimal_perfect_hash_function
-  #
-  # I welcome all improvements :-)
-  #
-  # If you have some comments or suggestions, please contact me on github
-  # https://github.com/namick
-  #
-  # - nathan amick
-  # 
-  #
-  # This library is built for integers that can be expressed with 10 digits:
-  # It zero pads smaller numbers... so the number one is expressed with:
-  # 0000000001
-  # The biggest number it can deal with is:
-  # 9999999999
-  #
-  # Since we are working with a limited sequential set of input integers, 10 billion,
-  # this algorithm will suffice for simple id obfuscation for many web apps.
-  # The largest value that Ruby on Rails default id, Mysql INT type, is just over 2 billion (2147483647)
-  # which is the same as 2 to the power of 31 minus 1, but considerably less than 10 billion.
-  #
-  # ScatterSwap is an integer hash function designed to have:
-  # - zero collisions ( http://en.wikipedia.org/wiki/Perfect_hash_function )
-  # - achieve avalanche ( http://en.wikipedia.org/wiki/Avalanche_effect )
-  # - reversable
-  #
-  # We do that by combining two distinct strategies.
-  #
-  # 1. Scattering - whereby we take the whole number, slice it up into 10 digits
-  # and rearange their places, yet retaining the same 10 digits.  This allows
-  # us to preserve the sum of all the digits, regardless of order.  This sum acts
-  # as a key to reverse this scattering effect.
-  # 
-  # 2. Swapping - when dealing with many sequential numbers that we don't want
-  # to look similar, scattering wont do us much good because so many of the
-  # digits are the same; it deoesn't help to scatter 9 zeros around, so we need
-  # to swap out each of those zeros for something else.. something different
-  # for each place in the 10 digit array; for this, we need a map so that we
-  # can reverse it.
-
-  # Convience class method pointing to the instance method
+module ScatterSwap
   def self.hash(plain_integer, spin = 0)
-    new(plain_integer, spin).hash
+    Hasher.new(plain_integer, spin).hash
   end
 
-  # Convience class method pointing to the instance method
   def self.reverse_hash(hashed_integer, spin = 0)
-    new(hashed_integer, spin).reverse_hash
-  end
-
-  def initialize(original_integer, spin = 0)
-    @original_integer = original_integer
-    @spin = spin
-    zero_pad  = original_integer.to_s.rjust(10, '0')
-    @working_array = zero_pad.split("").collect {|d| d.to_i}
-  end
-
-  attr_accessor :working_array
-
-  # obfuscates an integer up to 10 digits in length
-  def hash
-    swap
-    scatter
-    completed_string
-  end
-
-  # de-obfuscates an integer
-  def reverse_hash
-    unscatter
-    unswap
-    completed_string
-  end
-
-  def completed_string
-    @working_array.join
-  end
-
-  # We want a unique map for each place in the original number
-  def swapper_map(index)
-    array = (0..9).to_a
-    10.times.collect.with_index do |i|
-      array.rotate!(index + i ^ spin).pop
-    end
-  end
-
-  # Using a unique map for each of the ten places,
-  # we swap out one number for another
-  def swap
-    @working_array = @working_array.collect.with_index do |digit, index|
-      swapper_map(index)[digit]
-    end
-  end
-
-  # Reverse swap
-  def unswap
-    @working_array = @working_array.collect.with_index do |digit, index|
-      swapper_map(index).rindex(digit)
-    end
-  end
-
-  # Rearrange the order of each digit in a reversable way by using the 
-  # sum of the digits (which doesn't change regardless of order)
-  # as a key to record how they were scattered
-  def scatter
-    sum_of_digits = @working_array.inject(:+).to_i
-    @working_array = 10.times.collect do 
-      @working_array.rotate!(spin ^ sum_of_digits).pop
-    end
-  end
-
-  # Reverse the scatter
-  def unscatter
-    scattered_array = @working_array
-    sum_of_digits = scattered_array.inject(:+).to_i
-    @working_array = []
-    @working_array.tap do |unscatter| 
-      10.times do
-        unscatter.push scattered_array.pop
-        unscatter.rotate! (sum_of_digits ^ spin) * -1
-      end
-    end
-  end
-
-  # Add some spice so that different apps can have differently mapped hashes
-  def spin
-    @spin || 0
+    Hasher.new(hashed_integer, spin).reverse_hash
   end
 end

data/spec/scatter_swap_spec.rb

@@ -0,0 +1,87 @@
+require 'spec_helper'
+require 'scatter_swap'
+
+describe "#hash" do
+  it "should be 10 digits" do
+    100.times do |integer|
+      ScatterSwap.hash(integer).to_s.length.should == 10
+    end
+  end
+
+  it "should not be sequential" do
+    first = ScatterSwap.hash(1)
+    second = ScatterSwap.hash(2)
+    second.should_not eql(first.to_i + 1)
+  end
+
+  it "should be reversable" do
+    100.times do |integer|
+      hashed = ScatterSwap.hash(integer)
+      ScatterSwap.reverse_hash(hashed).to_i.should == integer
+    end
+  end
+end
+
+describe "#swapper_map" do
+  before do
+    @map_set = []
+    s = ScatterSwap::Hasher.new(1)
+    10.times do |digit|
+      @map_set.push s.swapper_map(digit)
+    end
+  end
+
+  it "should create a unique map array for each digit" do
+    @map_set.length.should == 10
+    @map_set.uniq.length.should == 10
+  end
+
+  it "should include all 10 digits in each map" do
+    @map_set.each do |map|
+      map.length.should == 10
+      map.uniq.length.should == 10
+    end
+  end
+end
+
+describe "#scatter" do
+  it "should return a number different from original" do
+    100.times do |integer|
+      s = ScatterSwap::Hasher.new(integer)
+      original_array = s.working_array
+      s.scatter
+      s.working_array.should_not == original_array
+    end
+  end
+
+  it "should be reversable" do
+    100.times do |integer|
+      s = ScatterSwap::Hasher.new(integer)
+      original_array = s.working_array.clone
+      s.scatter
+      s.unscatter
+      s.working_array.should == original_array
+    end
+  end
+end
+
+describe "#swap" do
+  it "should be different from original" do
+    100.times do |integer|
+      s = ScatterSwap::Hasher.new(integer)
+      original_array = s.working_array.clone
+      s.swap
+      s.working_array.should_not == original_array
+    end
+  end
+
+  it "should be reversable" do
+    100.times do |integer|
+      s = ScatterSwap::Hasher.new(integer)
+      original_array = s.working_array.clone
+      s.swap
+      s.unswap
+      s.working_array.should == original_array
+    end
+  end
+end  

data/spec/spec_helper.rb

@@ -0,0 +1,17 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scatter_swap
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-27 00:00:00.000000000 Z
+date: 2013-03-28 00:00:00.000000000 Z
 dependencies: []
 description: ScatterSwap is an integer hash function designed to have zero collisions,
   achieve avalanche, and be reversible.
@@ -20,13 +20,18 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .rspec
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/scatter_swap.rb
+- lib/scatter_swap/hasher.rb
+- lib/scatter_swap/run.rb
 - lib/scatter_swap/version.rb
 - scatter_swap.gemspec
+- spec/scatter_swap_spec.rb
+- spec/spec_helper.rb
 homepage: ''
 licenses: []
 post_install_message: 
@@ -47,8 +52,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Minimal perfect hash function for 10 digit integers
-test_files: []
+test_files:
+- spec/scatter_swap_spec.rb
+- spec/spec_helper.rb