fixed_length_encoder 1.2.1 → 2.0.0

data/.gitignore

@@ -0,0 +1,2 @@
+*.gem
+Gemfile.lock

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+gemspec
+gem 'rspec', '~> 2.14.1'

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2013 Brett Pontarelli
+
+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.md

@@ -0,0 +1,80 @@
+# fixed_length_encoder
+
+A one-to-one mapping function between integers and fixed length strings, such that sequential
+integers are mapped to non-sequential strings.  In other words you can obfuscate user ids for use
+in urls.
+
+* https://rubygems.org/gems/fixed_length_encoder
+* http://github.com/brettwp/fixed_length_encoder
+
+## How it works
+
+### Encoding
+
+Converts an integer value to a string of fixed length (default is 8).  As of `1.2` the maximum encodable value is the same as the alphabet maximum.  For example the default 36 character alphabet and 8 character fixed length can encoded numbers between 0 and 2,821,109,907,455 = `36**8 - 1`.
+
+### Decoding
+
+Given a valid string returns the decoded number.  Note that the two operations are reversible and
+adjacent values are unlikely to return adjacent strings (See Stats section below).  For example, using the default configuration:
+
+    FixedLengthEncoder.decode(FixedLengthEncoder.encode(100)) == 100
+    FixedLengthEncoder.encode(100) == 'ycxk2ntw'
+    FixedLengthEncoder.encode(101) == 'd8gxk24x'
+
+## How to install
+
+    sudo gem install fixed_length_encoder
+
+## How to use
+
+    require 'fixed_length_encoder'
+
+    FixedLengthEncoder.encode(100)
+    FixedLengthEncoder.decode('ycxk2ntw')
+
+    FixedLengthEncoder.encode(42, 3)
+    FixedLengthEncoder.decode('5c4')
+
+## Changing the length
+
+    FixedLengthEncoder::MESSAGE_LENGTH = 10
+
+## Changing the alphabet and encoding
+
+The `ALPHABET`, `ENCODE_MAP` and `DECODE_MAP` must all work together.  The two maps must also be
+reversible.  For example, for an alphabet of 62 characters you will need to build two maps of
+length `62**2 - 1` such that `DECODE_MAP[ENCODE_MAP[x]] == x`.  One such way to do this would be:
+
+    max = 62*62 - 1
+    ENCODE_MAP = (0..max).to_a.shuffle
+    DECODE_MAP = []
+    (0..max).each { |i| DECODE_MAP[ENCODE_MAP[i]] = i }
+
+Then, hard code these results into your application.  You will have three lines much like the lines
+that define the default `ALPHABET`, `ENCODE_MAP` and `DECODE_MAP` in the `FixedLengthEncoded`:
+
+    FixedLengthEncoder::ALPHABET = 'abcdefg'
+    FixedLengthEncoder::ENCODE_MAP = [19, 22, 25, 44, 17, 21, 33, 48, 39, 0, 16, 20, 29, 40, 43, 23, 3, 41, 12, 35, 7, 14, 10, 32, 46, 38, 9, 11, 27, 31, 26, 18, 34, 24, 4, 42, 47, 5, 1, 36, 13, 37, 30, 15, 45, 2, 8, 28, 6]
+    FixedLengthEncoder::DECODE_MAP = [9, 38, 45, 16, 34, 37, 48, 20, 46, 26, 22, 27, 18, 40, 21, 43, 10, 4, 31, 0, 11, 5, 1, 15, 33, 2, 30, 28, 47, 12, 42, 29, 23, 6, 32, 19, 39, 41, 25, 8, 13, 17, 35, 14, 3, 44, 24, 36, 7]
+
+# Stats
+
+Consider a random `value` using the `FixedLengthEncoder` default `LENGTH` of 8 and `ALPHABET` of 36
+characters.  If we encode `value` and `value + 1` and compute the difference between them in base 36
+we get a `delta`.  The table below compares the distribution of 10M pairs of two adjacent encoded values with 10M pairs of two random numbers.
+Both sets are taken from the range `0` to `36**8 = 2,821,109,907,456`.  As expected the number of
+negative deltas is near `50%` with the encoded values `49.9860%` negative and random `49.9989%`.
+It's interesting to note that there are no random occurances of two adjecent values, but in the
+encoded values there are `674`.
+
+|                 |: Encoded         :|: Random          :|
+| ---------------:| -----------------:| -----------------:|
+|  Negative deltas|         4,998,610 |         4,999,894 |
+| Delta equals one|               674 |                 0 |
+|    Maximum Delta| 2,820,278,456,877 | 2,820,579,691,973 |
+|    Average Delta|   935,745,508,922 |   940,183,477,180 |
+|          Std Dev| 1,148,460,034,903 | 1,151,442,250,985 |
+
+* Author  :: Brett Pontarelli <brett@paperyfrog.com>
+* Website :: http://brett.pontarelli.com

data/Rakefile

@@ -0,0 +1,15 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rake'
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec
+
+desc 'Run statistical tests'
+task :stats do
+  load 'extra/stats.rb'
+end
+
+desc 'Build examples for README'
+task :readme do
+  load 'extra/readme.rb'
+end

data/extra/readme.rb

@@ -0,0 +1,12 @@
+require 'fixed_length_encoder'
+
+puts FixedLengthEncoder.encode(100)
+puts FixedLengthEncoder.encode(101)
+puts FixedLengthEncoder.encode(42, 3)
+
+max = 7*7 - 1
+ENCODE_MAP = (0..max).to_a.shuffle
+DECODE_MAP = []
+(0..max).each { |i| DECODE_MAP[ENCODE_MAP[i]] = i }
+puts "[#{ENCODE_MAP.join(', ')}]"
+puts "[#{DECODE_MAP.join(', ')}]"

data/extra/stats.rb

@@ -0,0 +1,85 @@
+require 'fixed_length_encoder'
+
+class Stats
+  def initialize
+    @delta_max = 0
+    @negative_count = 0
+    @one_count = 0
+    @iterations = 0
+    @average_cumm = 0
+    @stddev_cumm = 0
+  end
+
+  def add_delta(delta)
+    if (delta < 0)
+      delta = -delta
+      @negative_count += 1
+    end
+    @one_count += 1 if delta == 1
+    @iterations += 1
+    @average_cumm += delta
+    @stddev_cumm += delta*delta
+    @delta_max = delta if delta > @delta_max
+  end
+
+  def negative_count
+    @negative_count
+  end
+
+  def one_count
+    @one_count
+  end
+
+  def delta_max
+    @delta_max
+  end
+
+  def average
+    @average_cumm / @iterations
+  end
+
+  def stddev
+    Math.sqrt((@stddev_cumm - (average*average/@iterations))/@iterations)
+  end
+
+  def one_percent
+    100.0 * @one_count / @iterations
+  end
+
+  def negative_percent
+    100.0 * @negative_count / @iterations
+  end
+end
+
+def comma(number)
+  number.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+end
+
+max = 36**8
+iter = 10**7
+encoder = FixedLengthEncoder::Encoder.new(FixedLengthEncoder::ALPHABET, FixedLengthEncoder::ENCODE_MAP, FixedLengthEncoder::DECODE_MAP)
+random_stats = Stats.new()
+encoder_stats = Stats.new()
+puts "36**8 = #{comma(max)}"
+(0..iter).each do |i|
+  value = Random.rand(max - 2)
+  e1 = encoder.string_to_integer(encoder.encode(value, 8))
+  e2 = encoder.string_to_integer(encoder.encode(value+1, 8))
+  encoder_stats.add_delta(e1 - e2)
+
+  v1 = Random.rand(max - 1)
+  v2 = Random.rand(max - 1)
+  random_stats.add_delta(v1 - v2)
+end
+
+def report(title, encoder)
+  puts "===#{title}==="
+  puts 'Neg: ' + comma(encoder.negative_count) + " (#{encoder.negative_percent.to_s}%)"
+  puts 'One: ' + comma(encoder.one_count) + " (#{encoder.one_percent.to_s}%)"
+  puts 'Max: ' + comma(encoder.delta_max)
+  puts 'Avg: ' + comma(encoder.average)
+  puts 'Std: ' + comma(encoder.stddev)
+end
+
+report('Random', random_stats)
+report('Encoder', encoder_stats)

data/fixed_length_encoder.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'fixed_length_encoder'
+  spec.version       = FixedLengthEncoder::VERSION
+  spec.authors       = ['Brett Pontarelli']
+  spec.email         = ['brett@paperyfrog.com']
+  spec.description   = 'Integers are converted to strings using a complex mapping ' +
+                       'and a base 36 alphabet.  Strings with valid digits (0-9 a-z)' +
+                       'are converted back to integers.  The encoding is one-to-one but not sequential.' +
+                       'This is useful for obfuscating user ids in urls.'
+  spec.summary       = 'Two way conversion from integer to a fixed (default=8) digit string.'
+  spec.homepage      = 'http://rubygems.org/gems/fixed_length_encoder'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  # spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake'
+end

data/lib/fixed_length_encoder.rb

@@ -63,30 +63,26 @@ module FixedLengthEncoder
 
     def offset(value, direction)
       offset = (@max_value/2).floor
-      (value += offset) if direction > 0
-      (value -= offset) if direction < 0
-      (value += @max_value) if value < 0
-      (value -= @max_value) if value >= @max_value
-      value
+      (value + direction * offset) % @max_value
     end
 
     def scramble_value(value, direction)
-      message = integer_to_array(value)      
+      message = integer_to_array(value)
       message = map_array(message, @encode_map, direction) if direction > 0
       message = map_array(message, @decode_map, direction) if direction < 0
       array_to_integer(message)
     end
 
     def map_array(message, map, direction)
-      indexes = (1..(@message_length - 1)).to_a
+      indexes = (0..@message_length).to_a.map { |i| i % @message_length }
       indexes = indexes.reverse if direction < 0
-      indexes.each do |index|
-        low = message[index - 1]
-        high = message[index]
-        map_index = high * @base + low
+      (0...@message_length).each do |index|
+        low_index = indexes[index]
+        high_index = indexes[index + 1]
+        map_index = message[high_index] * @base + message[low_index]
         map_value = map[map_index]
-        message[index - 1] = map_value % @base
-        message[index] = map_value / @base
+        message[low_index] = map_value / @base
+        message[high_index] = map_value % @base
       end
       message
     end
@@ -123,4 +119,4 @@ module FixedLengthEncoder
       value
     end
   end
-end
+end

data/lib/version.rb

@@ -0,0 +1,3 @@
+module FixedLengthEncoder
+  VERSION = '2.0.0'
+end

data/spec/fixed_length_encoder_spec.rb

@@ -0,0 +1,125 @@
+require 'fixed_length_encoder'
+
+def suppress_warnings
+  original_verbosity = $VERBOSE
+  $VERBOSE = nil
+  result = yield
+  $VERBOSE = original_verbosity
+  return result
+end
+
+describe FixedLengthEncoder do
+  describe 'Invalid encodings' do
+    before (:each) do
+      suppress_warnings do
+        @origianl = FixedLengthEncoder::ALPHABET
+        FixedLengthEncoder::ALPHABET = '0123456789'
+      end
+    end
+
+    after (:each) do
+      suppress_warnings do
+        FixedLengthEncoder::ALPHABET = @origianl
+      end
+    end
+
+    it 'should error on non-integers' do
+      expect { FixedLengthEncoder.encode('ERROR') }.to raise_error(ArgumentError)
+    end
+
+    it 'shouldn\'t encode values too big for message length' do
+      expect { FixedLengthEncoder.encode(100, 2) }.to raise_error(ArgumentError)
+    end
+
+    it 'shouldn\'t encode negative values' do
+      expect { FixedLengthEncoder.encode(-1, 2) }.to raise_error(ArgumentError)
+    end
+
+    it 'should error for non-strings' do
+      expect { FixedLengthEncoder.decode(0) }.to raise_error(ArgumentError)
+    end
+
+    it 'should error for bad characters' do
+      expect { FixedLengthEncoder.decode('^') }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe 'Valid encodings' do
+    before (:each) do
+      suppress_warnings do
+        @origianl = FixedLengthEncoder::ALPHABET
+        @encode_map = FixedLengthEncoder::ENCODE_MAP
+        @decode_map = FixedLengthEncoder::DECODE_MAP
+        FixedLengthEncoder::ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
+        max = 62*62 - 1
+        encode_map = (0..max).to_a.shuffle
+        decode_map = []
+        (0..max).each { |i| decode_map[encode_map[i]] = i }
+        FixedLengthEncoder::ENCODE_MAP = encode_map
+        FixedLengthEncoder::DECODE_MAP = decode_map
+      end
+    end
+
+    after (:each) do
+      suppress_warnings do
+        FixedLengthEncoder::ALPHABET = @origianl
+        FixedLengthEncoder::ENCODE_MAP = @encode_map
+        FixedLengthEncoder::DECODE_MAP = @decode_map
+      end
+    end
+
+    it 'should be a valid alphabet' do
+      FixedLengthEncoder.isValidAlphabet().should be_true
+    end
+
+    it 'should be a valid map' do
+      FixedLengthEncoder.isValidMap().should be_true
+    end
+
+    it 'should be reversible for the min value' do
+      value = 0
+      message = FixedLengthEncoder.encode(value)
+      FixedLengthEncoder.decode(message).should eq(value)
+    end
+
+    it 'should be reversible for the max value' do
+      value = (62**8)-1
+      message = FixedLengthEncoder.encode(value)
+      FixedLengthEncoder.decode(message).should eq(value)
+    end
+
+    it 'should be reversible for the middle value' do
+      value = ((62**8)/2).floor
+      message = FixedLengthEncoder.encode(value)
+      FixedLengthEncoder.decode(message).should eq(value)
+    end
+  end
+
+  describe 'Default encodings' do
+    it 'should be a valid alphabet' do
+      FixedLengthEncoder.isValidAlphabet().should be_true
+    end
+
+    it 'should be a valid map' do
+      FixedLengthEncoder.isValidMap().should be_true
+    end
+
+    it 'should be reversible for the min value' do
+      value = 0
+      message = FixedLengthEncoder.encode(value)
+      FixedLengthEncoder.decode(message).should eq(value)
+    end
+
+    it 'should be reversible for the max value' do
+      value = (36**8)-1
+      message = FixedLengthEncoder.encode(value)
+      FixedLengthEncoder.decode(message).should eq(value)
+    end
+
+    it 'should be reversible for the middle value' do
+      value = ((36**8)/2).floor
+      message = FixedLengthEncoder.encode(value)
+      FixedLengthEncoder.decode(message).should eq(value)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fixed_length_encoder
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 2.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,20 +9,65 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-28 00:00:00.000000000 Z
-dependencies: []
+date: 2013-09-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Integers are converted to strings using a complex mapping and a base
   36 alphabet.  Strings with valid digits (0-9 a-z)are converted back to integers.  The
   encoding is one-to-one but not sequential.This is useful for obfuscating user ids
   in urls.
-email: brett@paperyfrog.com
+email:
+- brett@paperyfrog.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- extra/readme.rb
+- extra/stats.rb
+- fixed_length_encoder.gemspec
 - lib/fixed_length_encoder.rb
+- lib/version.rb
+- spec/fixed_length_encoder_spec.rb
 homepage: http://rubygems.org/gems/fixed_length_encoder
-licenses: []
+licenses:
+- MIT
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -33,16 +78,23 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 2142083918509383952
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 2142083918509383952
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: Two way conversion from integer to a fixed (default=8) digit string.
-test_files: []
+test_files:
+- spec/fixed_length_encoder_spec.rb