hand_record_utility 1.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: db3a370a62468dc2340f6d38b71b8abb2e306dc8
+  data.tar.gz: cf95f78402510dcd2408f4a3900799f029569485
+SHA512:
+  metadata.gz: 3ce5b36d978516bf2ab4a7d0a7f08821439e2acd41077cb2651ece428900ab7b4c5f23e7657829fd44ab5bc239ae8f7c2e75f8dabefcfd2ff37bc680327ff92b
+  data.tar.gz: 18a97da6cb633aa608b1635cb7a69b24021b83286fd9573acb37aaeee44a5064f0d8241b6f4e5d6f390c9924f745f8a0fa769dfc9b19ac3af701c4ef933a410c

data/AUTHORS

@@ -0,0 +1,13 @@
+Main developer and maintainer:
+==
+
+Nicolas Hammond
+
+
+Contributors:
+==
+
+Richard Pavlicek - author of the algorithm.
+Greg Humphries - wrote Andrews code.
+
+

data/Gemfile

@@ -0,0 +1,16 @@
+source "https://rubygems.org"
+
+# Declare your gem's dependencies in hand_record_utility.gemspec.
+# Bundler will treat runtime dependencies like base dependencies, and
+# development dependencies will be added by default to the :development group.
+gemspec
+
+gem 'combinatorics'
+
+# Declare any dependencies that are still in development here instead of in
+# your gemspec. These might include edge Rails or gems from your path or
+# Git. Remember to move these dependencies to your gemspec before releasing
+# your gem to rubygems.org.
+
+# To use debugger
+# gem 'debugger'

data/Gemfile.lock

@@ -0,0 +1,32 @@
+PATH
+  remote: .
+  specs:
+    hand_record_utility (1.0.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    combinatorics (0.4.3)
+    diff-lcs (1.2.5)
+    rake (10.3.2)
+    rspec (3.1.0)
+      rspec-core (~> 3.1.0)
+      rspec-expectations (~> 3.1.0)
+      rspec-mocks (~> 3.1.0)
+    rspec-core (3.1.4)
+      rspec-support (~> 3.1.0)
+    rspec-expectations (3.1.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.1.0)
+    rspec-mocks (3.1.2)
+      rspec-support (~> 3.1.0)
+    rspec-support (3.1.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  combinatorics
+  hand_record_utility!
+  rake
+  rspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014 Nicolas Hammond
+
+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,115 @@
+Hand Record Utility
+==
+
+Utility for hand records, primarily for use in Bridge. Can be applied to other games with 4x13 card hands.
+
+This code takes a hand record (4 hands from a Bridge table) and converts it to a unique number using Richard Pavlicek's alogrithm. See http://www.rpbridge.net/7z68.htm for details on Pavlicek's algorithm.
+
+Being extended to include other algorithms, e.g. Thomas Andrews. See http://bridge.thomasoandrews.com/impossible/
+
+Install
+==
+
+To install
+
+    git clone https://github.com/njhammond/hand_record_utility
+    cd hand_record_utility
+    bundle install
+
+Test
+==
+
+To test 
+
+    rake
+
+Expect to see 0 failures. There may be some diagnostics about invalid numbers, this is all part of the test. There are also standalone tests in the ```./standalone_tests``` directory.  These contain some of the debug code. Use these for code examples.
+
+Given a unique number, either use the debug tools in this code to display it,
+or use Thomas Andrews' web site, 
+[http://bridge.thomasoandrews.com/impossible]
+(http://bridge.thomasoandrews.com/impossible).
+
+Use, can also test
+
+    rspec
+
+Usage
+==
+
+The code is written in Ruby.
+
+The maximum number of deals is HandRecordUtility::D or
+53644737765488792839237440000. D is the name that Pavlicek assigns to the maximum number of deals.
+
+To create a random deal, and convert back
+
+```
+    i = rand(HandRecordUtility::D) + 1
+    board = HandRecordUtility.pavlicek_number_to_board(i)
+    HandRecordUtility.to_pavlicek_number(board)
+```
+
+Board is a hash with elements, :north, :east, :south, :west.
+
+There are some debug options to pretty print the data.
+
+```
+    # Print a short form of a board
+    HandRecordUtility.debug_board_short_form(board)
+    # Print a hand record of a board
+    HandRecordUtility.debug_board(board)
+```
+
+To do the same for Andrews numbers
+
+```
+    i = rand(HandRecordUtility::D) + 1
+    board = HandRecordUtility.andrews_number_to_board(i)
+    HandRecordUtility.to_andrews_number(board)
+    # Print a short form of a board
+    HandRecordUtility.debug_board_short_form(board)
+    # Print a hand record of a board
+    HandRecordUtility.debug_board(board)
+```
+
+
+Notes
+==
+
+Externally the range is 1..D, within the code the range is 0..D-1.
+
+Definitions
+==
+
+A hand has 13 cards. A hand record has 4 hands. 
+
+There are 53,644,737,765,488,792,839,237,440,000 possible bridge deals.
+
+Credits
+==
+
+Richard Pavlicek has given his approval for use of his algorithm subject to proper accreditiation. Thank you Richard.
+
+Thomas Andrews given his approval for use of his algorithm subject to proper accreditiation. Thank you Thomas.
+
+Purpose
+==
+
+The original purpose for putting this code out in the public domain is to try to spur some interest in creating Open Source code that can be used in Bridge projects.
+
+Developers
+==
+
+See AUTHORS for list of developers.
+
+
+License
+==
+
+This project uses the MIT-LICENSE.
+
+Please make sure to credit Richard Pavlicek as original author of the algorithm as well.
+
+Please make sure to credit Thomas Andrews as original author of his algorithm.
+

data/Rakefile

@@ -0,0 +1,37 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+require 'rspec/core/rake_task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'HandRecordUtility'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+#  t.pattern = 'test/**/*_test.rb'
+  t.pattern = 'test/*_test.rb'
+  t.verbose = false
+end
+
+RSpec::Core::RakeTask.new(:spec) do |config|
+  # Need to fix. Get errors about pattern.
+  config.pattern = "spec/*_spec.rb"
+end
+
+#task default: :test
+task :default => :spec

data/lib/hand_record_utility.rb

@@ -0,0 +1,695 @@
+# Provides a set of utilities for manipulating hand records.
+# Primarily for use for Bridge, the card game.
+#
+# A hand record/board contains four hands: ":north", ":south", ":west", ":east"
+# Each hand is a string[17] in the format
+# example hand="SKQH5432DAQJCT954"
+# where T=Ten (we rarely use 10 when working on internal strings).
+# Because of the implementation you can remove suits which are not used, e.g.
+# example hand="SAKQJT9H8765432" 
+# but this is discouraged.
+#
+# This gem assumes that the hand record and hand are well formed.
+# Little/no error checking on input values.
+#
+# See http://www.rpbridge.net/7z68.htm for Pavlicek algorithm.
+# Richard has given his permission to use the algorithm with proper attribution.
+#
+# This algorithm uses 0..D-1 internally, for a UI and externally we use 1..D
+#
+# See bridge.thomasandrews.com/impossible
+# for a web site that displays Pavlicek hands.
+#
+# We provide routines to go both ways, from a unique number to a hand record,
+# from a hand record to a unique number.
+#
+# Code now supports Andrews numbers as well.
+#
+# Code added to convert from a large number (up to 29 digits, see D below) 
+# to hex (up to 24 digits) and to base 64 (up to 16 characters). 
+# The latter has a translation algorithm to ensure that the 64 characters are 
+# regular ASCII characters.
+# Also can convert the other way.
+# This shortens the number for transmission, e.g. URLs
+#
+# Code best viewed with a tab stop of 2.
+# 345678901234567890123456789012345678901234567890123456789012345678901234567890
+
+# Used for some factorial math
+require 'combinatorics/choose'
+
+module HandRecordUtility
+
+  # Constants. D is a 29 digit number
+  #   22222222221111111111000000000
+  #   98765432109876543210987654321
+  D = 53644737765488792839237440000
+  # Different directions
+  DIR_N = 0
+  DIR_E = 1
+  DIR_S = 2
+  DIR_W = 3
+  DIRECTIONS = [
+    "North",
+    "East",
+    "South",
+    "West",
+  ]
+
+  # 64 characters so can map 
+  CHAR_TO_BITS = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ{}"
+  # Given the ascii characters, map to a number. Subtract 48 from the char
+  BITS_TO_CHAR = [
+     0,  1,  2,  3,  4,  5,  6,  7,  8,  9, # 0123456789
+    -1, -1, -1, -1, -1, -1, -1, 36, 37, 38, # :;<=>?@ABC
+    39, 40, 41, 42, 43, 44, 45, 46, 47, 48, # DEFGHIJKLM
+    49, 50, 51, 52, 53, 54, 55, 56, 57, 58, # NOPQRSTUVW
+    59, 60, 61, -1, -1, -1, -1, -1, -1, 10, # XYZ[/]^_'a
+    11, 12, 13, 14, 15, 16, 17, 18, 19, 20, # bcdefghijk
+    21, 22, 23, 24, 25, 26, 27, 28, 29, 30, # lmnopqrstu
+    31, 32, 33, 34, 35, 62, -1, 63          # vwxyz{|}
+  ]
+
+  # Using the Ranked order, the order of cards is AS, AH, AD, AC
+  # Using the Suited order, the order of cards is AS, KS, QS, ...
+  # Always used Ranked
+  PAVLICEK_RANKED = 1
+  PAVLICEK_SUITED = 2
+
+  # Used in Andrews numbers
+  S_MAX = Combinatorics::Choose.C(26,13)
+  E_MAX = Combinatorics::Choose.C(39,13)
+
+  # Default is suited
+  # Pavlicek web site uses the ranked order, Andrews reference is to the suited 
+  # order.
+  # Using Andrews web site to generate the numbers, the suited is preferred.
+  # The number is assumed to be 1..D, however the algorithm on Pavlicek's page
+  # is 0..D-1. Therefore in a later routine we subtract 1.
+  def self.pavlicek_number_to_board(number)
+    pavlicek_suited_number_to_board(number)
+  end
+
+  # Uses the ranked Pavlicek method
+  def self.pavlicek_ranked_number_to_board(number)
+    pavlicek_ranked_or_suited_number_to_board(number, PAVLICEK_RANKED)
+  end
+
+  # Uses the suited Pavlicek method (default)
+  def self.pavlicek_suited_number_to_board(number)
+    pavlicek_ranked_or_suited_number_to_board(number, PAVLICEK_SUITED)
+  end
+
+  # Algorithm:
+  # 1. N=E=S=W=13; C=52; K=D
+  # 2. X=K*N/C; If I < X then N=N-1, go to 6
+  # 3. I=I-X; X=K*E/C; If I < X then E=E-1, go to 6
+  # 4. I=I-X; X=K*S/C; If I < X then S=S-1, go to 6
+  # 5. I=I-X; X=K*W/C; W=W-1
+  # 6. K=X; C=C-1, loop if not zero to 2
+  # Returns a board
+  def self.pavlicek_ranked_or_suited_number_to_board(number, ranked_or_suited)
+    # Common theme to help with debugging. Define routine name for debug code. 
+    # Sometimes also define a short routine name. 
+    # Use a variable to turn debug on or off in the code
+    # Similar code through most of this gem
+    routine_name = "pavlicek_ranked_or_suited_number_to_board"
+    short_routine_name = "prsntb"
+    debug_routine = 0
+
+    # Error check
+    if (number <= 0) then
+      puts "Error in #{routine_name}. Invalid number #{number}. Must be 1 or higher."
+      return nil
+    end
+
+    if (number > HandRecordUtility::D) then
+      puts "Error in #{routine_name}. Invalid number #{number} is too big."
+      return nil
+    end
+
+    # Using variable names from http://www.rpbridge.net/7z68.htm
+    n = 13
+    e = 13
+    s = 13
+    w = 13
+    c = 52
+    k = D
+    # hands[NESW][HCDS][0..12 where 0=A, 1=K, 2=Q, ...12=2]
+    hands = Array.new(4) { Array.new(4) { Array.new } }
+
+    # The algorithm assumes that the space is 0..D-1
+    # But the UI assumes 1..D, so decrement by 1.
+    i = number - 1
+
+    (0..51).each do |card_count|
+#      if (ranked_or_suited == PAVLICEK_RANKED) then
+#        suit = card_count % 4
+#        # 0=A, 1=K, 2=Q, .... 12=2
+#        rank = (card_count / 4).to_i
+#      else
+        suit = (card_count / 13).to_i
+        # 0=A, 1=K, 2=Q, .... 12=2
+        rank = card_count - (suit * 13)
+#      end
+
+      # Make sure do it this way and not
+      # x = (k / c) * n
+      x = (k * n) / c
+      if (i < x) then
+        n = n - 1
+        dir = DIR_N
+        if (debug_routine == 1) then
+          puts "#{short_routine_name}: dir=#{dir} suit=#{suit} rank=#{rank} i=#{i} x=#{x} n=#{n} e=#{e} s=#{s} w=#{w}"
+        end
+        hands[dir][suit] << rank
+      else
+        i = i - x
+        x = (k * e) / c
+        if (i < x) then
+          e = e - 1
+          dir = DIR_E
+          if (debug_routine == 1) then
+            puts "#{short_routine_name}: dir=#{dir} suit=#{suit} rank=#{rank} i=#{i} x=#{x} n=#{n} e=#{e} s=#{s} w=#{w}"
+          end
+          hands[DIR_E][suit] << rank
+        else
+          i = i - x
+          x = (k * s) / c
+          if (i < x) then
+            s = s - 1
+            dir = DIR_S
+            if (debug_routine == 1) then
+              puts "#{short_routine_name}: dir=#{dir} suit=#{suit} rank=#{rank} i=#{i} x=#{x} n=#{n} e=#{e} s=#{s} w=#{w}"
+            end
+            hands[dir][suit] << rank
+          else
+            # This is West
+            i = i - x
+            x = (k * w) / c
+            if ((i < x) || ((i == 0) && (x == 0))) then
+              w = w - 1
+              dir = DIR_W
+              if (debug_routine == 1) then
+                puts "#{short_routine_name}: dir=#{dir} suit=#{suit} rank=#{rank} i=#{i} x=#{x} n=#{n} e=#{e} s=#{s} w=#{w}"
+              end
+              hands[dir][suit] << rank
+            else
+              puts "Error. card_count=#{card_count} i=#{i} x=#{x} k=#{k} c=#{c} n=#{n} e=#{e} s=#{s} w=#{w}"
+            end
+          end
+        end
+      end
+      k = x
+      c = c - 1
+    end
+
+    if (debug_routine == 1) then
+      puts "#{routine_name}: end. n=#{n} e=#{e} s=#{s} w=#{w}"
+    end
+
+    return pavlicek_arrays_to_board(hands)
+  end
+
+  # pavlicek_arrays_to_board takes four arrays and returns the entire board.
+  def self.pavlicek_arrays_to_board(hands)
+    board = Hash.new
+    board[:north] = pavlicek_array_to_hand(hands[DIR_N])
+    board[:east]  = pavlicek_array_to_hand(hands[DIR_E])
+    board[:south] = pavlicek_array_to_hand(hands[DIR_S])
+    board[:west]  = pavlicek_array_to_hand(hands[DIR_W])
+    return board
+  end
+
+
+  # pav_hand is an array of cards
+  # Returns a 17 char string with the hand record.
+  def self.pavlicek_array_to_hand(pav_hand_array)
+    s =     "S" + pavlicek_hand_array_to_suit(pav_hand_array[0])
+    s = s + "H" + pavlicek_hand_array_to_suit(pav_hand_array[1])
+    s = s + "D" + pavlicek_hand_array_to_suit(pav_hand_array[2])
+    s = s + "C" + pavlicek_hand_array_to_suit(pav_hand_array[3])
+    return s
+  end
+
+  # Given an array holding cards in a suit, return a string with that suit
+  def self.pavlicek_hand_array_to_suit(pav_hand_array)
+    routine_name = "pavlicek_hand_array_to_suit"
+    s = ""
+    return s if (pav_hand_array.nil?)
+
+    pav_hand_array.each do |card|
+      case card
+      when 0
+        s = s + "A"
+      when 1
+        s = s + "K"
+      when 2
+        s = s + "Q"
+      when 3
+        s = s + "J"
+      when 4
+        s = s + "T"
+      when 5..12
+        c = 14 - card
+        s = s + c.to_s
+      else
+        puts "Invalid value in #{routine_name}. card=#{card}"
+        # Error
+      end
+    end
+    return s
+  end
+
+  # Converts from a board to a Pavlicek number
+  # See http://www.rpbridge.net/7z68.htm
+  # Pavlicek ranks the cards in this order:
+  # AS, AH, AD, AC, KS.... 2C
+  # Algorithm from Richard's web site
+  # 1. N=E=S=W=13; C=52; K=D; I=0
+  # 2. X=K*N/C; If N card then N=N-1, go to 6
+  # 3. I=I+X; X=K*E/C; If E card then E=E-1, go to 6
+  # 4. I=I+X; X=K*S/C; If S card then S=S-1, go to 6
+  # 5. I=I+X; X=K*W/C; W=W-1
+  # 6. K=X; C=C-1, loop if not zero to 2
+  def self.to_pavlicek_number(board)
+    to_pavlicek_suited_number(board)
+  end
+
+  def self.to_pavlicek_suited_number(board)
+    routine_name = "to_pavlicek_suited_number"
+    debug_routine = 0
+
+    if (debug_routine == 1) then
+      puts "#{routine_name}: Board=#{board}"
+    end
+
+    pav_array = board_to_pavlicek_array(board, PAVLICEK_SUITED)
+#    debug_pavlicek_array(pav_array)
+    pav_number = pavlicek_array_to_number(pav_array)
+#    debug_pavlicek_array(pav_array)
+
+    return pav_number
+  end
+
+  # Given a hand, converts to a Pavlicek array
+  def self.to_pavlicek_ranked_number(board)
+    routine_name = "to_pavlicek_ranked_number"
+    debug_routine = 1
+
+    if (debug_routine == 1) then
+      puts "#{routine_name}: Board=#{board}"
+    end
+
+    pav_array = board_to_pavlicek_array(board, PAVLICEK_RANKED)
+    pav_number = pavlicek_array_to_number(pav_array)
+#    debug_pavlicek_array(pav_array)
+
+    return pav_number
+  end
+
+  # Given a hand, converts to a Pavlicek array
+  # This is a new term I have created.
+  # Returns an array [0..51] where 0 is AS, 1 is AH, 2 is AD.... 51 is 2C
+  # The values in the array are [0123] (n, e, s, w)
+  # In other words, for each card we know which hand it is in
+  def self.board_to_pavlicek_array(board, ranked_or_suited)
+    # Initialize an array of size 52. Set all values to -1 (as an error check)
+    pav_array = Array.new(52, -1)
+
+    put_hand_in_pavlicek_array(pav_array, board[:north], DIR_N, ranked_or_suited)
+    put_hand_in_pavlicek_array(pav_array, board[:east], DIR_E, ranked_or_suited)
+    put_hand_in_pavlicek_array(pav_array, board[:south], DIR_S, ranked_or_suited)
+    put_hand_in_pavlicek_array(pav_array, board[:west], DIR_W, ranked_or_suited)
+    # Return the array
+    pav_array
+  end
+
+  # Given a hand in format "SKQH5432DAQJCT954"
+  # Fill out the pavlicek array
+  def self.put_hand_in_pavlicek_array(pav_array, hand, direction, ranked_or_suited)
+    suit = 0
+    hand.each_char do |value|
+      if ((value == "S") || (value == "H") || (value == "D") || (value == "C")) then
+        case value
+        when "S"
+          suit = 0
+        when "H"
+          suit = 1
+        when "D"
+          suit = 2
+        when "C"
+          suit = 3
+        end
+      else
+        # We have a card in a suit
+        card = 14
+        case value
+        when "A"
+          card_value = 0
+        when "K"
+          card_value = 1
+        when "Q"
+          card_value = 2
+        when "J"
+          card_value = 3
+        when "T"
+          card_value = 4
+        else
+          # Map "9" -> 4, "8" -> 5, ... "2" -> 12
+          card_value = 62 - value.ord # 50=2, 57=9
+#          card_value = 14 - card_int
+          if (card_value <= 0) then
+            puts "Error in card. card_value=#{card_value} value=#{value}"
+          end
+        end
+
+        #Error check?
+        # AS=0, AH=1, AD=2, AC=3, ... 2C=51
+        if (ranked_or_suited == PAVLICEK_RANKED) then
+          card = (card_value * 4) + suit
+        else
+          card = (suit * 13) + card_value
+        end
+        # card should be 0..51
+#        puts "hand=#{hand} value=#{value} card=#{card} direction=#{direction}"
+        pav_array[card] = direction
+      end
+    end
+    # No return value
+  end
+
+  # Given a Pavlicek array, convert to a number
+  # Using variable names from http://www.rpbridge.net/7z68.htm
+  def self.pavlicek_array_to_number(pav_array)
+    routine_name = "pavlicek_array_to_number"
+    debug_routine = 0
+    n = 13
+    e = 13
+    s = 13
+    w = 13
+    c = 52
+    k = D
+    i = 0
+    card_count = 1
+
+    # Go through the 52 cards
+    (0..51).each do |card_count|
+      hand_has_card = pav_array[card_count]
+      if (debug_routine == 1) then
+        # Use a shortened routine name
+        puts "pa2n: count=#{card_count} hand_has_card=#{hand_has_card} c=#{c} k=#{k} i=#{i} n=#{n} e=#{e} s=#{s} w=#{w}"
+      end
+
+      x = (k * n) / c
+      if (hand_has_card == DIR_N) then
+        n = n - 1
+      else
+        i = i + x
+        x = (k * e) / c
+        if (hand_has_card == DIR_E) then
+          e = e - 1
+        else
+          i = i + x
+          x = (k * s) / c
+          if (hand_has_card == DIR_S) then
+            s = s - 1
+          else
+            i = i + x
+            x = (k * w) / c
+            if (hand_has_card == DIR_W) then
+              w = w - 1
+            else
+              # Invalid card
+              puts "Invalid direction in HandRecordUtility. direction=#{hand_has_card} count=#{count} value=#{hand_has_card}"
+            end
+          end
+        end
+      end
+
+      if (debug_routine == 1) then
+        puts "pa2n: end i=#{i} k=#{k} x=#{x} c=#{c} n=#{n} e=#{e} s=#{s} w=#{s}"
+      end
+      k = x
+      c = c - 1
+    end
+
+    # The algorithm uses 0..D-1, 
+    # The UI uses 1..D so need to increase by 1
+    return i + 1
+  end
+
+	##############
+	# Andrews code
+	##############
+  # Convert board to Andrews number.
+  # http://bridge.thomasoandrews.com/impossible/algorithm.html
+
+  def self.pavlicek_array_to_andrews_sequences(pav_array)
+    sequences = Array.new( 3 ) { Array.new( 13, -1 ) }
+    (0..2).each do |j|    
+      count = 0
+      loc = 0
+      (0..51).each do |i|
+        if (j == pav_array[i]) then
+          sequences[j][loc] = count
+          loc = loc + 1
+        end
+        if (j <= pav_array[i]) then
+          count = count + 1
+        end
+      end
+    end
+    sequences
+  end
+
+  def self.encode_increasing_sequence(sequence)
+    sum = 0
+    sequence.each_with_index do |val,index|
+      if val > index then
+        sum = sum + Combinatorics::Choose.C(val,index+1)
+      end
+    end
+    sum
+  end
+
+  def self.to_andrews_number(board)
+    pav_array = board_to_pavlicek_array(board, PAVLICEK_SUITED)
+    sequences = pavlicek_array_to_andrews_sequences(pav_array)
+
+    seqN = encode_increasing_sequence(sequences[0])
+    seqE = encode_increasing_sequence(sequences[1])
+    seqS = encode_increasing_sequence(sequences[2])
+
+		# Need to add 1. Internally we use 0..D-1, externally 1..D
+    i =  seqS + S_MAX * (seqE + (E_MAX * seqN)) + 1
+		return i
+  end
+
+  def self.decode_to_increasing_sequence(index)
+    length = 13
+    result = Array.new( length, -1 )
+
+    13.downto(1) do |i|
+      last_value = 0
+      num = i
+      next_value = Combinatorics::Choose.C(num,i)
+      while index >= next_value do
+        num += 1
+        last_value=next_value
+        next_value = Combinatorics::Choose.C(num,i)
+      end
+      result[i-1] = num-1
+      index = index - last_value
+    end
+    result
+  end
+
+  # Convert from an Andrews number to a board
+  def self.andrews_number_to_board(number)
+    routine_name = "andrews_number_to_board"
+
+    # Error check
+    if (number <= 0) then
+      puts "Error in #{routine_name}. Invalid number #{number}. Must be 1 or higher."
+      return nil
+    end
+
+    if (number > HandRecordUtility::D) then
+      puts "Error in #{routine_name}. Invalid number #{number} is too big."
+      return nil
+    end
+
+		# Need to subtract 1 because the UI is 1..D, code is 0..D-1
+		number = number - 1
+
+    # Using variable names from http://www.rpbridge.net/7z68.htm
+    s_index  = number % S_MAX
+    quotient = number / S_MAX
+
+    e_index = quotient % E_MAX
+    n_index = quotient / E_MAX
+
+    north_sequence = decode_to_increasing_sequence(n_index)
+    east_sequence  = decode_to_increasing_sequence(e_index)
+    south_sequence = decode_to_increasing_sequence(s_index)
+
+    # initialize all cards to west since anything missing must be there!
+
+    pav_array = Array.new(52,DIR_W)
+
+    [[north_sequence,DIR_N], 
+     [east_sequence,DIR_E],
+     [south_sequence,DIR_S]].each do |sequence,direction|
+      
+      hand_loc = 0
+      sequence_loc = 0
+      pav_array.each_with_index do |val,idx|
+        if (val == DIR_W) then
+          if (hand_loc == sequence[sequence_loc]) then
+            pav_array[idx] = direction
+            sequence_loc = sequence_loc + 1
+          end
+          hand_loc = hand_loc + 1
+        end
+      end
+    end
+
+    nsew = Array.new(4) { Array.new(4) { Array.new } }
+    pav_array.each_with_index do |dir,idx|
+			suit = idx / 13
+			rank = idx % 13
+      nsew[dir][suit].push(rank)
+    end
+
+    pavlicek_arrays_to_board(nsew)
+  end
+
+	##########
+	# Hex code
+	##########
+  # Given a number, convert to a 24 character hex string.
+  # A number should be a maximum of 96 bits.
+  # A hex character has 4 bits, so should be a maximum of 24 characters.
+  # This routine does no error checking on the input.
+  def self.number_to_hex(i)
+    i.to_s(16)
+  end
+
+  # From hex back to int
+  # This routine does no error checking on the input.
+  def self.hex_to_number(s)
+    s.to_i(16)
+  end
+
+	##########
+	# Base 64 code
+	##########
+  # From number to character string
+  # This routine does no error checking on the input.
+  def self.number_to_string_64(i)
+    return "0" if (i == 0)
+    s = ""
+    while (i > 0)
+      digit = i % 64
+      s = CHAR_TO_BITS[digit] + s
+      i = i / 64
+    end
+    s
+  end
+
+  # Converts the string to an int.
+  # This routine does no error checking on the input.
+  def self.string_64_to_number(s)
+    i = 0
+    return i if (s.nil? || s.empty?)
+    s.each_char do |c|
+      chr = c.ord - 48
+      # Validity check
+      return -1 if ((chr < 0) || (chr > 77))
+      n = BITS_TO_CHAR[chr]
+      # Validity check
+      return -1 if (n == -1)
+      i = (i * 64) + n
+    end
+    i
+  end
+
+	##########
+	# Debug code
+	##########
+  # Debug utility to print values of the pav_array
+  def self.debug_pavlicek_array(pav_array)
+    (0..4).each do |tens|
+      printf "%2d: ", tens
+      (0..9).each do |digit|
+        num = (tens * 10) + digit
+        printf "%d ", pav_array[num]
+      end
+      puts "\n"
+    end
+    printf "%2d: %d %d \n", 5, pav_array[50], pav_array[51]
+  end
+
+  # Print a board in short form
+  def self.debug_board_short_form(board)
+    debug_board_short_form_suit("N", board[:north])
+    debug_board_short_form_suit("S", board[:south])
+    debug_board_short_form_suit("E", board[:east])
+    debug_board_short_form_suit("W", board[:west])
+  end
+
+  # Helper routine to print a hand in short form
+  def self.debug_board_short_form_suit(hand_name, hand)
+    puts " #{hand_name}: #{hand}"
+  end
+
+  # Print out in format normally associated with bridge journalism
+  def self.debug_board(board)
+    debug_board_ns(board[:north])
+    sw = debug_board_hand_suit(board[:west], "S")
+    se = debug_board_hand_suit(board[:east], "S")
+    printf "S: %-14s S: %s\n", sw, se
+    sw = debug_board_hand_suit(board[:west], "H")
+    se = debug_board_hand_suit(board[:east], "H")
+    printf "H: %-14s H: %s\n", sw, se
+    sw = debug_board_hand_suit(board[:west], "D")
+    se = debug_board_hand_suit(board[:east], "D")
+    printf "D: %-14s D: %s\n", sw, se
+    sw = debug_board_hand_suit(board[:west], "C")
+    se = debug_board_hand_suit(board[:east], "C")
+    printf "C: %-14s C: %s\n", sw, se
+    debug_board_ns(board[:south])
+  end
+
+  # Prints the North or South hand
+  def self.debug_board_ns(hand)
+    printf "         S: %s\n", debug_board_hand_suit(hand, "S")
+    printf "         H: %s\n", debug_board_hand_suit(hand, "H")
+    printf "         D: %s\n", debug_board_hand_suit(hand, "D")
+    printf "         C: %s\n", debug_board_hand_suit(hand, "C")
+  end
+
+  # Returns the cards in a suit for a hand
+  # Assumes hand is well formed
+  def self.debug_board_hand_suit(hand, suit)
+    s = ""
+    case suit
+    when "S"
+      s = hand[/S.*H/]
+      s = s[1, s.length - 2]
+    when "H"
+      s = hand[/H.*D/]
+      s = s[1, s.length - 2]
+    when "D"
+      s = hand[/D.*C/]
+      s = s[1, s.length - 2]
+    when "C"
+      s = hand[/C.*/]
+      s = s[1, s.length - 1]
+    end
+    return s
+  end
+
+
+end

data/lib/hand_record_utility/version.rb

@@ -0,0 +1,3 @@
+module HandRecordUtility
+  VERSION = "1.0.2"
+end

data/lib/tasks/hand_record_utility_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :hand_record_utility do
+#   # Task goes here
+# end

data/spec/hand_record_utility_spec.rb

@@ -0,0 +1,219 @@
+require 'spec_helper'
+require 'hand_record_utility'
+
+describe HandRecordUtility do
+
+  # Set up board
+  # The format of a hand should be 17 characters, but we can shorten
+#    @board[:north] = "SAKQJT98765432"
+  # is the same as
+#    @board[:north] = "SAKQJT98765432HDC"
+  before do
+    @board = Hash.new
+#    @board[:north] = "SAKQJT98765432"
+#    @board[:east]  = "HAKQJT98765432"
+#    @board[:south] = "DAKQJT98765432"
+#    @board[:west]  = "CAKQJT98765432"
+  end
+
+  # Default first test
+#  it "should generate a board" do
+#    pending "do it"
+#  end
+
+  ###################
+  # Pavlicek tests
+  ###################
+  # Bounds test - success
+  it "should test Pavlicek 1" do
+    i = 1
+    @board[:north] = "SAKQJT98765432"
+    @board[:east]  = "HAKQJT98765432"
+    @board[:south] = "DAKQJT98765432"
+    @board[:west]  = "CAKQJT98765432"
+    expect(HandRecordUtility.to_pavlicek_number(@board)).to eq(i)
+  end
+
+  it "should test Pavlicek 12345678901234567890123456789" do
+    i = 12345678901234567890123456789
+    @board = HandRecordUtility.pavlicek_number_to_board(i)
+    expect(HandRecordUtility.to_pavlicek_number(@board)).to eq(i)
+  end
+
+  # Test for end
+  it "should test Pavlicek 53644737765488792839237440000" do
+    # D =53644737765488792839237440000 
+    i = HandRecordUtility::D
+    @board[:north] = "CAKQJT98765432"
+    @board[:east]  = "DAKQJT98765432"
+    @board[:south] = "HAKQJT98765432"
+    @board[:west]  = "SAKQJT98765432"
+    j = HandRecordUtility.to_pavlicek_number(@board)
+    expect(j).to eq(i)
+  end
+
+  ntimes = 10
+  it "should test 10 random Pavlicek numbers converting back and forth" do
+    (1..ntimes).each do |count|
+      i = rand(HandRecordUtility::D) + 1
+      @board = HandRecordUtility.pavlicek_number_to_board(i)
+      j = HandRecordUtility.to_pavlicek_number(@board)
+      expect(j).to eq(i)
+    end
+  end
+
+  # Bounds test - failure
+  it "should fail with number 0 and print an error message" do
+    i = 0
+    @board = HandRecordUtility.pavlicek_number_to_board(i)
+    expect(@board).to eq(nil)
+  end
+
+  it "should fail with number D+1 and print an error message" do
+    i = HandRecordUtility::D + 1
+    @board = HandRecordUtility.pavlicek_number_to_board(i)
+    expect(@board).to eq(nil)
+  end
+
+  ###################
+  # int<->hex tests
+  ###################
+  it "should convert 0 to hex 0x0" do
+    i = 0
+    s = HandRecordUtility.number_to_hex(i)
+    expect(s).to eq("0")
+    j = HandRecordUtility.hex_to_number(s)
+    expect(j).to eq(i)
+  end
+
+  it "should convert 1 to hex 0x1" do
+    i = 1
+    s = HandRecordUtility.number_to_hex(i)
+    expect(s).to eq("1")
+    j = HandRecordUtility.hex_to_number(s)
+    expect(j).to eq(i)
+  end
+
+  it "should convert 10 to hex a" do
+    i = 10
+    s = HandRecordUtility.number_to_hex(i)
+    j = HandRecordUtility.hex_to_number(s)
+    puts "i=#{i} s=#{s} j=#{j}"
+    expect(s).to eq "a"
+    expect(j).to eq(i)
+  end
+
+  it "should convert 53644737765488792839237440000 to hex 0xad55e315634dda658bf49200" do
+    i = 53644737765488792839237440000
+    s = HandRecordUtility.number_to_hex(i)
+    expect(s).to eq("ad55e315634dda658bf49200")
+    j = HandRecordUtility.hex_to_number(s)
+    expect(j).to eq(i)
+  end
+
+  ntimes = 10
+  it "should convert convert 10 random numbers to/from hex" do
+    (1..ntimes).each do |count|
+      i = rand(HandRecordUtility::D) + 1
+      s = HandRecordUtility.number_to_hex(i)
+      j = HandRecordUtility.hex_to_number(s)
+      expect(j).to eq(i)
+    end
+  end
+
+  ###################
+  # int<->string_64 tests
+  ###################
+  it "should test all characters to map string 64 format" do
+    (0..63).each do |number|
+      c = HandRecordUtility::CHAR_TO_BITS[number]
+      i = HandRecordUtility.string_64_to_number(c)
+      expect(number).to eq(i)
+    end
+  end
+
+  it "should convert 0 to string 64 0" do
+    i = 0
+    s = HandRecordUtility.number_to_string_64(i)
+    j = HandRecordUtility.string_64_to_number(s)
+    expect(s).to eq "0"
+    expect(j).to eq(i)
+  end
+
+  it "should convert 1 to string 64 1" do
+    i = 1
+    s = HandRecordUtility.number_to_string_64(i)
+    j = HandRecordUtility.string_64_to_number(s)
+    expect(s).to eq "1"
+    expect(j).to eq(i)
+  end
+
+  it "should convert 64 to string 64 40" do
+    i = 64
+    s = HandRecordUtility.number_to_string_64(i)
+    j = HandRecordUtility.string_64_to_number(s)
+    expect(s).to eq "10"
+    expect(j).to eq(i)
+  end
+
+  ntimes = 10
+  it "should convert convert 10 random numbers to/from 64 bit string" do
+    (1..ntimes).each do |count|
+      i = rand(HandRecordUtility::D) + 1
+      s = HandRecordUtility.number_to_string_64(i)
+      j = HandRecordUtility.string_64_to_number(s)
+      expect(j).to eq(i)
+    end
+  end
+
+  ###################
+  # Andrews tests
+  ###################
+  # 1 is the same hand record for Andrews as Pavlicek
+  # Test edge case
+  it "should test Andrews number of 1" do
+    i = 1
+    @board[:north] = "SAKQJT98765432"
+    @board[:east]  = "HAKQJT98765432"
+    @board[:south] = "DAKQJT98765432"
+    @board[:west]  = "CAKQJT98765432"
+    j = HandRecordUtility.to_andrews_number(@board)
+    expect(j).to eq(i)
+  end
+
+  # Test edge case
+  it "should test Andrews number of 53644737765488792839237440000" do
+    i = 53644737765488792839237440000
+    @board[:north] = "CAKQJT98765432"
+    @board[:east]  = "DAKQJT98765432"
+    @board[:south] = "HAKQJT98765432"
+    @board[:west]  = "SAKQJT98765432"
+    j = HandRecordUtility.to_andrews_number(@board)
+    expect(j).to eq(i)
+  end
+
+  # Test random cases
+  ntimes = 10
+  it "should test 10 random Andrew numbers converting back and forth" do
+    (1..ntimes).each do |count|
+      i = rand(HandRecordUtility::D) + 1
+      @board = HandRecordUtility.andrews_number_to_board(i)
+      j = HandRecordUtility.to_andrews_number(@board)
+      expect(j).to eq(i)
+    end
+  end
+  #
+  # Bounds test - failure
+  it "should fail with number 0 and print an error message" do
+    i = 0
+    @board = HandRecordUtility.andrews_number_to_board(i)
+    expect(@board).to eq(nil)
+  end
+
+  it "should fail with number D+1 and print an error message" do
+    i = HandRecordUtility::D + 1
+    @board = HandRecordUtility.andrews_number_to_board(i)
+    expect(@board).to eq(nil)
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+require 'hand_record_utility'
+
+RSpec.configure do |config|
+  # config.pattern = '**/*_spec'
+  # Optional config here.
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: hand_record_utility
+version: !ruby/object:Gem::Version
+  version: 1.0.2
+platform: ruby
+authors:
+- Nicolas Hammond
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  Takes a hand record (4 hands of 13 cards) and converts to a unique number using Richard Pavlicek's algorithm. The reverse also applies. Also works with the Andrews algorithm. The number will be in the range of [1..53644737765488792839237440000].
+
+  See Richard Pavlicek's web site at http://rpbridge.net/7z68.htm.
+
+  See Thomas Andrews' web site at http://bridge.thomasoandrews.com/impossible/bin/impossible.cgi.
+email:
+- gems@hammondsoftware.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AUTHORS
+- Gemfile
+- Gemfile.lock
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/hand_record_utility.rb
+- lib/hand_record_utility/version.rb
+- lib/tasks/hand_record_utility_tasks.rake
+- spec/hand_record_utility_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/njhammond/hand_record_utility
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.3.0
+signing_key: 
+specification_version: 4
+summary: Converts a hand record to/from a unique number using various algorithms.
+test_files: []