rubylabs 0.9.0 → 0.9.1

data/lib/recursionlab.rb

@@ -1,69 +1,86 @@
+module RubyLabs
 
 =begin rdoc
   
 == RecursionLab
 
-Divide and conquer algorithms for searching and sorting.
-The methods implemented in this module are +bsearch+ (binary search),
-+msort+ (merge sort), and +qsort!+ (QuickSort).  The module also
-contains 'helper methods' that can be used to trace the execution
+The RecursionLab module has definitions of methods from Chapter 5
+of <em>Explorations in Computing</em>.
+
+The methods implemented in this module show how a divide and conquer strategy
+can lead to more efficient algorithms for searching and sorting.
+The method defined here include +bsearch+ (binary search),
++msort+ (merge sort), and +qsort+ (QuickSort).  
+
+The module also contains 'helper methods' that can be used to trace the execution
 of the algorithms.
 
 =end
 
-module RubyLabs
-
 module RecursionLab
   
-=begin rdoc
-
-Linear search -- use for baseline tests.  Form that makes it easy to attach
-probe to count comparisons.
-=end
-
+# The linear search method from iterationlab.rb is replicated here so it can be
+# used  for baseline tests.
+#--
 # :begin :search
-	def search(a, k)
-	  i = 0
-	  while i < a.length
-	    return i if a[i] == k
-	    i += 1
-	  end
-		return nil
-	end
+  def search(a, k)  # :nodoc:
+    i = 0
+    while i < a.length
+      return i if a[i] == k
+      i += 1
+    end
+    return nil
+  end
 # :end :search
 
-	
-=begin rdoc
-
-Call <tt>bsearch(k, a)</tt> to search for item +k+ in array +a+, using
-the binary search algorithm.  Based on the specification in Introduction
-to Algorithms, by Cormen et al.
-
-=end
-
+# Search array +a+ for item +k+ using the binary search algorithm.  Returns
+# the location of +k+ if it's found, or +nil+ if +k+ is not in the array.
+# Note that the array must be sorted or the results are unpredictable.
+#
+# Example:
+#   >> a = TestArray.new(10).sort 
+#   => [5, 9, 10, 22, 38, 43, 74, 78, 86, 88]
+#   >> bsearch(a, 38)
+#   => 4
+#   >> bsearch(a, 26)
+#   => nil
+#
+# :call-seq:
+#   bsearch(a,k) => Fixnum
+#
+# Based on the specification in Introduction to Algorithms, by Cormen et al.
+#-- 
 # :begin :bsearch
-	def bsearch(a, k)
-	  lower = -1
-	  upper = a.length
-	  while true                              # iteration ends with return statement
-	    mid = (lower + upper) / 2             # set the mid point for this iteration
-	    return nil if upper == lower + 1      # search fails if the region is empty
-	    return mid if k == a[mid]             # search succeeds if k is at the midpoint
-	    if k < a[mid]
-	      upper = mid                         # next search: lower half of the region
-	    else
-	      lower = mid                         # next search: upper half
-	    end
-	  end	  
-	end
+  def bsearch(a, k)
+    lower = -1
+    upper = a.length
+    while true                              # iteration ends with return statement
+      mid = (lower + upper) / 2             # set the mid point for this iteration
+      return nil if upper == lower + 1      # search fails if the region is empty
+      return mid if k == a[mid]             # search succeeds if k is at the midpoint
+      if k < a[mid]
+        upper = mid                         # next search: lower half of the region
+      else
+        lower = mid                         # next search: upper half
+      end
+    end   
+  end
 # :end :bsearch
 
-=begin rdoc
-
-Recursive implementation of binary search.
-
-=end
-
+# An alternative implementation of binary search, using a recursive method.
+#
+# Example:
+#   >> a = TestArray.new(10).sort 
+#   => [5, 9, 10, 22, 38, 43, 74, 78, 86, 88]
+#   >> rbsearch(a, 38)
+#   => 4
+#   >> rbsearch(a, 26)
+#   => nil
+#
+# :call-seq:
+#   rbsearch(a,k) => Fixnum
+#
+#-- 
 # :begin :rbsearch
   def rbsearch(a, k, lower = -1, upper = a.length)
     mid = (lower + upper) / 2
@@ -77,12 +94,28 @@ Recursive implementation of binary search.
   end
 # :end :rbsearch
 
-=begin rdoc
-A helper method that can be called from a probe to display the contents
-of an array during a search or sort.
-=end
-
-	def brackets(a, left, right = a.length-1, mid = nil)    # :nodoc:
+# A helper method that can be called from a probe to display the contents
+# of an array during a search or sort.  See also IterationLab#brackets.
+#
+# The version implemented in this module accepts an additional argument,
+# which specifies the location of the right bracket in the output string
+# (if this argument is not give the right bracket is inserted at the end).
+#
+# An optional third argument, intended for experiments with binary search, tells
+# the method where to insert an asterisk before an item.
+#
+# Examples:
+#
+#   >> a = TestArray.new(15)
+#   => [22, 3, 70, 74, 35, 0, 82, 64, 90, 54, 88, 26, 75, 18, 17]
+#   >> puts brackets(a, 8, 10)
+#    22  3  70  74  35  0  82  64 [90  54  88] 26  75  18  17
+#   => nil
+#   >> puts brackets(a, 8, 10, 9)
+#    22  3  70  74  35  0  82  64 [90 *54  88] 26  75  18  17
+#   => nil
+#
+  def brackets(a, left, right = a.length-1, mid = nil)
     left = 0 if left < 0
     right = a.length-1 if right >= a.length
     pre = left == 0 ? "" : " " + a.slice(0..(left-1)).join("  ") + " "
@@ -93,29 +126,24 @@ of an array during a search or sort.
       res[res.index(a[mid].to_s)-1] = ?*
     end
     return res
-	end
-
-=begin rdoc
-
-A test harness for bsearch -- makes an array, gets an item not in the array,
-counts comparisons (assuming user has set a counting probe)
-
-=end
-
-  def bsearch_count(n)
-    a = TestArray.new(n)
-    x = a.random(:fail)
-    count { bsearch(a,x) }
   end
-  
-=begin rdoc
-  
-Merge sort.  Makes a copy of the input array, returns a sorted
-version of the copy.  Uses a "helper function" to
-combine successively bigger pieces of the input array.
-
-=end
-
+    
+
+# Return a copy of +a+, sorted using the merge sort algorithm.
+# Each iteration merges successively larger groups of sorted sub-arrays.
+# Since the group size doubles from one iteration to the next, the
+# method needs only log(n) iterations to sort an array with +n+ items.
+#
+# Example:
+#   >> a = TestArray.new(10)
+#   => [14, 23, 74, 83, 7, 19, 57, 29, 20, 1]
+#   >> msort(a)
+#   => [1, 7, 14, 19, 20, 23, 29, 57, 74, 83]
+#
+# :call-seq:
+#   msort(a) => Array
+#
+#-- 
 # :begin :msort :merge :merge_groups :less
 def msort(array)
   a = array.clone
@@ -124,12 +152,13 @@ def msort(array)
     merge_groups(a, size)
     size = size * 2
   end
-	return a
+  return a
 end
 # :end :msort
 
-# "Helper method" to merge all groups of size g
-
+# A helper method called from +msort+, used to merge adjacent groups of size +gs+
+# in array +a+.
+#--
 # :begin :merge_groups
 def merge_groups(a, gs)
   i = 0                            # first group starts here
@@ -141,11 +170,12 @@ def merge_groups(a, gs)
 end
 # :end :merge_groups
 
-# "Helper method" to merge two blocks.  A call of the form merge(a, i, n) creates
-# a new list by merging n-element lists starting at a[i] and a[i+n].
-
+# A helper method called from <tt>merge_groups</tt>.  A call of the form 
+# <tt>merge(a, i, n)</tt> creates a list formed by merging +n+-element 
+# lists starting at <tt>a[i]</tt> and <tt>a[i+n]</tt>.
+#--
 # :begin :merge
-  def merge(a, i, gs)    # :nodoc:
+  def merge(a, i, gs)
     ix = j = min(i + gs, a.length)
     jx = min(j + gs, a.length)
     res = []
@@ -162,74 +192,101 @@ end
   end
 # :end :merge
 
+# A copy of the +less+ method from iterationlab.rb, reimplemented here so
+# students can attach probes without loading IterationLab
+#--
 # :begin :less
-  def less(x, y)
+  def less(x, y)  # :nodoc:
     return x < y
   end
 # :end :less
 
-# Helper function to print brackets during merge sort
-
-  def msort_brackets(a, n)      # :nodoc:
-    # return " [" + a[i..i+2*n-1].join(" ") + "] "
-  	res = []
-  	i = 0
-  	while i < a.length
-  		res << a[i..((i+n)-1)].join(" ")
-  		i += n
-  	end
-  	return "[" + res.join("] [") + "]"
+# A method designed to be used in experiments with the merge sort algorithm.
+# A call of the form <tt>msort_brackets(a, n)</tt> will create a string with
+# every item from +a+, with brackets around each group of size +n+.
+#
+# Example:
+#   >> a = TestArray.new(16)
+#   => [45, 10, 33, 41, 57, 84, 7, 96, 18, 44, 89, 94, 36, 90, 87, 97]
+#   >> puts msort_brackets(a, 4)
+#   [45 10 33 41] [57 84 7 96] [18 44 89 94] [36 90 87 97]
+#   => nil
+#
+# :call-seq:
+#   msort_brackets(a,n) => String
+#
+  def msort_brackets(a, n)
+    res = []
+    i = 0
+    while i < a.length
+      res << a[i..((i+n)-1)].join(" ")
+      i += n
+    end
+    return "[" + res.join("] [") + "]"
   end
-  
-=begin rdoc
-  
-QuickSort, based on the description from Cormen et al.  Sorts the input array in place.  
-The parameters (using notation from Cormen et al): +p+ is the left boundary of the region 
-to sort, and +r+ is right boundary.  The call to +partition+ sets +q+, the new boundary 
-between two sub-regions.
-
-=end
-
+    
+# Return a sorted copy of +a+, sorted using the QuickSort algorithm.  
+# The parameters +p+ and +q+ represent the left and right boundaries of
+# the region to sort.  The top level call to +qsort+ should not include
+# values for +p+ and +q+, so they are initially set to the the beginning
+# and ending locations in the array. Recursive calls will pass values for
+# +p+ and +q+ that define successively smaller regions to sort.
+#
+# Example:
+#   >> a = TestArray.new(10)
+#   => [58, 94, 62, 63, 85, 22, 64, 45, 30, 77]
+#   >> qsort(a)
+#   => [22, 30, 45, 58, 62, 63, 64, 77, 85, 94]
+# 
+# Based on the specification in Introduction to Algorithms, by Cormen et al.
+#
+#-- 
 # :begin :qsort :partition
-	def qsort(a, p = 0, r = a.length-1)       # sort the region bounded by p and r
-	  a = a.dup if p == 0 && r == a.length-1  # don't modify the input array (top level only)
-	  if p < r
-	    q = partition(a, p, r)    # q is boundary between small items and large items
-	    qsort(a, p, q)            # sort small items (range from p to q)
-	    qsort(a, q+1, r)          # sort large items (range from q+1 to r)
-	  end
-	  return a
-	end
+  def qsort(a, p = 0, r = a.length-1)       # sort the region bounded by p and r
+    a = a.dup if p == 0 && r == a.length-1  # don't modify the input array (top level only)
+    if p < r
+      q = partition(a, p, r)                # q is boundary between small items and large items
+      qsort(a, p, q)                        # sort small items (range from p to q)
+      qsort(a, q+1, r)                      # sort large items (range from q+1 to r)
+    end
+    return a
+  end
 # :end :qsort
 
+# Helper method for +qsort+.  Rearrange array +a+ so that all the items in
+# the region between <tt>a[p]</tt> and <tt>a[r]</tt> are divided into two
+# groups, such that every item in the left group is smaller than any item
+# in the right group.  The return value is the location of the boundary
+# between the groups.
+#
+#--
 # :begin :partition
-	def partition(a, p, r)        # partition the region bounded by p and r
-	  x = a[p]                    # x is the pivot value
-	  i = p - 1
-	  j = r + 1
-	  while true                  # squeeze i, j until they point at items to exchange
-	    loop { j = j - 1; break if a[j] <= x }
-	    loop { i = i + 1; break if a[i] >= x }
-	    if i < j                  
-	      a[i], a[j] = a[j], a[i] # exchange items at locations i and j
-	    else
-	      return j                # no more exchanges; return location that separates regions
-	    end
-	  end
-	end
+  def partition(a, p, r)        # partition the region bounded by p and r
+    x = a[p]                    # x is the pivot value
+    i = p - 1
+    j = r + 1
+    while true                  # squeeze i, j until they point at items to exchange
+      loop { j = j - 1; break if a[j] <= x }
+      loop { i = i + 1; break if a[i] >= x }
+      if i < j                  
+        a[i], a[j] = a[j], a[i] # exchange items at locations i and j
+      else
+        return j                # no more exchanges; return location that separates regions
+      end
+    end
+  end
 # :end :partition
 
-# Helper procedure used to trace the execution of qsort
-
-	def qsort_brackets(a, left, right)       # :nodoc:
-	  tmp = []
-	  tmp += a[ 0 .. (left-1) ] if left > 0
-	  tmp << "["
-	  tmp += a[ left .. right ] if right >= 0
-	  tmp << "]"
-	  tmp += a[ (right+1) .. (a.length-1) ] if right < a.length
-	  return tmp.join(" ")
-	end
+# Helper procedure used to trace the execution of qsort.
+  def qsort_brackets(a, left, right)
+    tmp = []
+    tmp += a[ 0 .. (left-1) ] if left > 0
+    tmp << "["
+    tmp += a[ left .. right ] if right >= 0
+    tmp << "]"
+    tmp += a[ (right+1) .. (a.length-1) ] if right < a.length
+    return tmp.join(" ")
+  end
 
 end # RecursionLab