scatter_swap 0.0.2 → 0.0.3

data/README.md

@@ -1,37 +1,68 @@
 # ScatterSwap
 
-This is the hashing function behind ObfuscateId.
-https://github.com/namick/obfuscate_id
+This is the integer hashing function behind [obfuscate_id](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.
+> 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
+> After writing this and reading/learning some elemental hashing techniques,
+> I realized that this library is an example of 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 :-)
+> I welcome all improvements via pull-requests :-)
 
-If you have some comments or suggestions, please contact me on github
-https://github.com/namick
+> If you have some comments or suggestions, please contact me at `github@nathanamick.com` - nathan amick
 
-- nathan amick
+## Goals
 
+We want to transform an integer into another random looking integer and then reliably tranform it back.
 
-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
+It will turn the number `3` into `2356513904`, and it can then reliably reverse that scrambled `2356513904` number back into `3`
 
-The biggest number it can deal with is:
-9999999999
+We also want sequential integers to become non-sequential.
+
+So for example it will turn `7001, 7002, 7003` into `5270192353, 7107163820, 3296163828`, and back again.
+
+Please note, this is not encryption or related to security in any way.  It lightly obfuscates an integer in a reversable way.
+
+## Usage
+
+Pass a number (as an integer or string) to the 'hash' method and it will return an obfuscated version of it.
+
+    ScatterSwap.hash(1).to_i
+    #=> 4517239960
+
+Pass that obfuscated version in and it will return the original (as a zero padded string).
+
+    ScatterSwap.reverse_hash(4517239960).to_i
+    #=> 1
+
+
+*Because this was originally built for urls like this `example.com/users/00000000001` it outputs strings.  This is why the examples above have `to_i` tacked on to them.  Since extracting it to its own library, that may not make sense anymore.  I'm considering output the same type as it is input.  Thoughts?*
+
+## How it works 
+
+This library is built for integers that can be expressed with 10 digits.
+It zero pads smaller numbers. 
+
+The number 1 is expressed with:
+
+    0000000001
+
+The biggest number it can deal with is 10 billion - 1:
+
+    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.
 
+## Strategies
+
 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
@@ -50,7 +81,6 @@ 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
 
@@ -66,10 +96,6 @@ Or install it yourself as:
 
     $ gem install scatter_swap
 
-## Usage
-
-TODO: Write usage instructions here
-
 ## Contributing
 
 1. Fork it

data/lib/scatter_swap/version.rb

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

data/scatter_swap.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |gem|
   gem.email         = ["github@nathanamick.com"]
   gem.description   = %q{ScatterSwap is an integer hash function designed to have zero collisions, achieve avalanche, and be reversible.}
   gem.summary       = %q{Minimal perfect hash function for 10 digit integers}
-  gem.homepage      = ""
+  gem.homepage      = "https://github.com/namick/scatter_swap"
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scatter_swap
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -32,7 +32,7 @@ files:
 - scatter_swap.gemspec
 - spec/scatter_swap_spec.rb
 - spec/spec_helper.rb
-homepage: ''
+homepage: https://github.com/namick/scatter_swap
 licenses: []
 post_install_message: 
 rdoc_options: []