sudokusolver 1.3 → 1.4

data/lib/sudokusolver.rb

@@ -4,19 +4,20 @@
 #  Algorithm, overall structure and original python source code by Peter Norvig
 #  See http://norvig.com/sudoku.html
 
-## Throughout this program:
-##   r is a row,    e.g. 'A'
-##   c is a column, e.g. '3'
-##   s is a square, e.g. 'A3'
-##   d is a digit,  e.g. '9'
-##   u is a unit,   e.g. ['A1','B1','C1','D1','E1','F1','G1','H1','I1']
-##   g is a grid,   e.g. 81 non-blank chars, e.g. starting with '.18...7...
-##   values is a hash of possible values, e.g. {'A1'=>'123489', 'A2'=>'8', ...}
+# Throughout this program:
+#   r is a row,    e.g. 'A'
+#   c is a column, e.g. '3'
+#   s is a square, e.g. 'A3'
+#   d is a digit,  e.g. '9'
+#   u is a unit,   e.g. ['A1','B1','C1','D1','E1','F1','G1','H1','I1']
+#   g is a grid,   e.g. 81 non-blank chars, e.g. starting with '.18...7...
+#   values is a hash of possible values, e.g. {'A1'=>'123489', 'A2'=>'8', ...}
 
 class SudokuSolver
-	VERSION = "1.3"
+	VERSION = "1.4"
   attr_reader :rows, :cols, :squares, :unitlist, :peers, :units
   
+	# Cross-product
   def cross(a, b)
     cp = Array.new # cross product
     a.each do |x|
@@ -60,6 +61,8 @@ class SudokuSolver
     
   end
   
+	# A grid is an 81 character string composed of the digits 0-9
+	# A blank is represented as a period.
   def parse_grid(g)
     g = g.chomp
     g = g.split('')
@@ -72,6 +75,9 @@ class SudokuSolver
     return values
   end
   
+	# Assign a value to a square in the Sudoku grid:
+	# Eliminate all other possible digits from the square
+	# by calling the eliminate function (mutually recursive)
   def assign(values, s, d)
     values[s].split('').each do |d2|
       unless d2 == d
@@ -81,19 +87,23 @@ class SudokuSolver
     return values
   end
   
+	# Remove a possibility from a square.
+	# Recursively propagate the constraints: look at the source code for how this is done.
   def eliminate(values, s, d)
     return values unless values[s].include?(d) ## Already eliminated.
 
-    values[s] = values[s].sub(d,'') ## Remove the digit from the string of possibilities
-    ##  values[s].sub!(d,'') => why doesn't sub!() work?
+    values[s] = values[s].sub(d,'') # Remove the digit from the string of possibilities
+    #  values[s].sub!(d,'') => why doesn't sub!() work?
 
-    return false if values[s].length == 0 ## Contradiction: no more values (no more digits can be assigned)
+    return false if values[s].length == 0 # Contradiction: no more values (no more digits can be assigned)
 
-    ## Remove digit from all peers
+    # Remove digit from all peers
+		# If the square has only one remaining possibility, that is the assigned value for the square and
+		# that value must be removed from all that square's peers.
     peers[s].each { |s2| return false unless eliminate(values, s2, values[s]) } if values[s].length == 1
 
-    ## Assign digit if, by elimination, there is only one square left 
-    ## in the units for this square that can hold the digit 
+    # Assign the digit to the square if, by elimination
+		# this is the only square that has the digit as a possibility
     units[s].each do |u|
       dplaces = Array.new
       u.each { |s2| dplaces << s2 if values[s2].include?(d) }
@@ -103,10 +113,11 @@ class SudokuSolver
     return values
   end
 
+	# Search if constraint satisfaction does not solve the puzzle
   def search(values)
     return false if values == false
 
-    solved = true ## assumption 
+    solved = true # assumption 
     squares.each do |s|
       unless values[s].length == 1
         solved = false
@@ -117,7 +128,7 @@ class SudokuSolver
       
     min = 10 
     start = nil
-    squares.each do |s| ## Chose the undetermined square s with the fewest possibilities
+    squares.each do |s| # Chose the undetermined square s with the fewest possibilities
       l = values[s].length
       if l > 1 && l < min
         min = l
@@ -132,6 +143,7 @@ class SudokuSolver
     return false
   end
     
+	# Print a text Sudoku grid to STDOUT
   def print_grid(values)
     return if values == false
     max = 0
@@ -163,6 +175,7 @@ class SudokuSolver
     return values
   end
   
+	# Transform the solution into an 81 character string
   def string_solution(values)
     solution = ""
     squares.each do |s|
@@ -171,6 +184,7 @@ class SudokuSolver
     return solution
   end
   
+	# Verify the Sudoku solution
   def check_solution(solution)
     values = Hash.new
     for s,d in squares.zip(solution.split(''))
@@ -189,9 +203,9 @@ class SudokuSolver
   
 end
 
-## Algorithm by Peter Norvig @ http://www.norvig.com/sudoku.html
+# Algorithm by Peter Norvig @ http://www.norvig.com/sudoku.html
 
-## More constraints:
-## http://www.scanraid.com/BasicStrategies.htm
-## http://www.krazydad.com/blog/2005/09/29/an-index-of-sudoku-strategies/
-## http://www2.warwick.ac.uk/fac/sci/moac/currentstudents/peter_cock/python/sudoku/
+# More constraints:
+# http://www.scanraid.com/BasicStrategies.htm
+# http://www.krazydad.com/blog/2005/09/29/an-index-of-sudoku-strategies/
+# http://www2.warwick.ac.uk/fac/sci/moac/currentstudents/peter_cock/python/sudoku/

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.2
 specification_version: 1
 name: sudokusolver
 version: !ruby/object:Gem::Version 
-  version: "1.3"
-date: 2007-04-15 00:00:00 -04:00
+  version: "1.4"
+date: 2007-04-22 00:00:00 -04:00
 summary: Commandline program and library for solving Sudoku puzzles
 require_paths: 
 - lib