tablestakes 0.8.5 → 0.9.0

data/doc/created.rid

@@ -1,2 +1,2 @@
-Wed, 02 Jul 2014 13:58:48 -0400
-lib/tablestakes.rb	Wed, 02 Jul 2014 13:58:12 -0400
+Wed, 06 Aug 2014 07:36:36 -0400
+lib/tablestakes.rb	Fri, 25 Jul 2014 07:05:42 -0400

data/doc/index.html

@@ -50,6 +50,8 @@
 
   <ul class="link-list">
   
+    <li><a href="./OrderedRow.html">OrderedRow</a>
+  
     <li><a href="./Table.html">Table</a>
   
   </ul>

data/doc/js/search_index.js

@@ -1 +1 @@
-var search_data = {"index":{"searchIndex":["table","bottom()","column()","count()","get_columns()","get_rows()","intersect()","join()","length()","new()","row()","select()","size()","sub()","sub!()","tally()","to_a()","to_s()","top()","union()","where()","write_file()"],"longSearchIndex":["table","table#bottom()","table#column()","table#count()","table#get_columns()","table#get_rows()","table#intersect()","table#join()","table#length()","table::new()","table#row()","table#select()","table#size()","table#sub()","table#sub!()","table#tally()","table#to_a()","table#to_s()","table#top()","table#union()","table#where()","table#write_file()"],"info":[["Table","","Table.html","","<p>This class is a Ruby representation of a table. All data is captured as\ntype <code>String</code> by default. Columns …\n"],["bottom","Table","Table.html#method-i-bottom","(colname, num=1)","<p>Counts the number of instances of a particular string, given a column name,\nand returns an integer &gt;= …\n"],["column","Table","Table.html#method-i-column","(colname)","<p>Return a copy of a column from the table, identified by column name.\nReturns <code>nil</code> if column name not found. …\n"],["count","Table","Table.html#method-i-count","(colname=nil, value=nil)","<p>Counts the number of instances of a particular string, given a column name,\nand returns an integer &gt;= …\n"],["get_columns","Table","Table.html#method-i-get_columns","(*columns)",""],["get_rows","Table","Table.html#method-i-get_rows","(colname, condition=nil)",""],["intersect","Table","Table.html#method-i-intersect","(table2, colname, col2name=nil)","<p>Return the intersection of columns from different tables, eliminating\nduplicates. Return nil if a column …\n"],["join","Table","Table.html#method-i-join","(table2, colname, col2name=nil)","<p>Given a second table to join against, and a field/column, return a\n<code>Table</code> which contains a join of the …\n"],["length","Table","Table.html#method-i-length","(colname=nil, value=nil)",""],["new","Table","Table.html#method-c-new","(input=nil)","<p>Instantiate a <code>Table</code> object using a tab-delimited file\n<p>input &mdash; OPTIONAL <code>Array</code> of rows or <code>String</code> to identify …\n\n"],["row","Table","Table.html#method-i-row","(index)","<p>Return a copy of a row from the table as an <code>Array</code>, given an\nindex (i.e. row number). Returns empty Array …\n"],["select","Table","Table.html#method-i-select","(*columns)","<p>Select columns from the table, given one or more column names. Returns an\ninstance of <code>Table</code> with the …\n"],["size","Table","Table.html#method-i-size","(colname=nil, value=nil)",""],["sub","Table","Table.html#method-i-sub","(colname, re, replace)","<p>Given a field/column, and a regular expression to match against, and a\nreplacement string, update the …\n"],["sub!","Table","Table.html#method-i-sub-21","(colname, re, replace)",""],["tally","Table","Table.html#method-i-tally","(colname)","<p>Count instances in a particular field/column and return a\n<code>Table</code> of the results. Returns <code>nil</code> if the column …\n"],["to_a","Table","Table.html#method-i-to_a","()","<p>Converts a <code>Table</code> object to an array of arrays (each row)\n<p>none\n"],["to_s","Table","Table.html#method-i-to_s","()","<p>Converts a <code>Table</code> object to a tab-delimited string.\n<p>none\n"],["top","Table","Table.html#method-i-top","(colname, num=1)","<p>Counts the number of instances of a particular string, given a column name,\nand returns an integer &gt;= …\n"],["union","Table","Table.html#method-i-union","(table2, colname, col2name=nil)","<p>Return the union of columns from different tables, eliminating duplicates.\nReturn nil if a column is …\n"],["where","Table","Table.html#method-i-where","(colname, condition=nil)","<p>Given a particular condition for a given column field/column, return a\nsubtable that matches the condition. …\n"],["write_file","Table","Table.html#method-i-write_file","(filename)","<p>Write a representation of the <code>Table</code> object to a file (tab\ndelimited).\n<p>filename &mdash; <code>String</code> to identify the …\n\n"]]}}
+var search_data = {"index":{"searchIndex":["orderedrow","table","<=>()","add_column()","add_row()","add_rows()","bottom()","column()","count()","data()","del_column()","del_row()","each()","empty?()","get_columns()","get_rows()","intersect()","join()","length()","new()","new()","row()","select()","size()","sort()","sort!()","sub()","sub!()","tally()","to_a()","to_s()","top()","union()","where()","write_file()"],"longSearchIndex":["orderedrow","table","orderedrow#<=>()","table#add_column()","table#add_row()","table#add_rows()","table#bottom()","table#column()","table#count()","orderedrow#data()","table#del_column()","table#del_row()","table#each()","table#empty?()","table#get_columns()","table#get_rows()","table#intersect()","table#join()","table#length()","orderedrow::new()","table::new()","table#row()","table#select()","table#size()","table#sort()","table#sort!()","table#sub()","table#sub!()","table#tally()","table#to_a()","table#to_s()","table#top()","table#union()","table#where()","table#write_file()"],"info":[["OrderedRow","","OrderedRow.html","","<p>This class functions as a temporary representation of a row. The OrderedRow\ncontains information about …\n"],["Table","","Table.html","","<p>This class is a Ruby representation of a table. All data is captured as\ntype <code>String</code> by default. Columns …\n"],["<=>","OrderedRow","OrderedRow.html#method-i-3C-3D-3E","(other)","<p>Implements comparable\n<p>Attributes\n<p>other &mdash; The row to be compared\n"],["add_column","Table","Table.html#method-i-add_column","(*args)","<p>Add a column to the Table. Raises ArgumentError if the column name is\nalready taken  or there are not …\n"],["add_row","Table","Table.html#method-i-add_row","(*row)","<p>Add a row to the Table, appending it to the end. Raises ArgumentError if \nthere are not the correct number …\n"],["add_rows","Table","Table.html#method-i-add_rows","(array_of_rows)","<p>Add one or more rows to the Table, appending it to the end. Raises\nArgumentError if  there are not the …\n"],["bottom","Table","Table.html#method-i-bottom","(colname, num=1)","<p>Returns counts of the least frequent values found in a given column in the\nform of a Table.  Raises  …\n"],["column","Table","Table.html#method-i-column","(colname)","<p>Return a copy of a column from the table, identified by column name.\nReturns empty Array if column name …\n"],["count","Table","Table.html#method-i-count","(colname=nil, value=nil)","<p>Counts the number of instances of a particular string, given a column name,\nand returns an integer &gt;= …\n"],["data","OrderedRow","OrderedRow.html#method-i-data","()","<p>Returns the row elements in an <code>Array</code>\n<p>Attributes\n<p>none\n"],["del_column","Table","Table.html#method-i-del_column","(colname)","<p>Delete a column from the Table. Raises ArgumentError if the column name\ndoes not exist.\n<p>Attributes\n<p>colname … &mdash; "],["del_row","Table","Table.html#method-i-del_row","(rownum)","<p>Delete a row from the Table. Raises ArgumentError if the row number is not\nfound\n<p>Attributes\n<p>rownum &mdash; <code>FixNum</code> …\n"],["each","Table","Table.html#method-i-each","()","<p>Defines an iterator for <code>Table</code> which produces rows of data\n(headers omitted) for its calling block.\n"],["empty?","Table","Table.html#method-i-empty-3F","()","<p>Return true if the Table is empty, false otherwise.\n"],["get_columns","Table","Table.html#method-i-get_columns","(*columns)",""],["get_rows","Table","Table.html#method-i-get_rows","(colname, condition=nil)",""],["intersect","Table","Table.html#method-i-intersect","(table2, colname, col2name=colname)","<p>Return an Array with the intersection of columns from different tables,\neliminating duplicates. Return …\n"],["join","Table","Table.html#method-i-join","(table2, colname, col2name=colname)","<p>Given a second table to join against, and a field/column, return a\n<code>Table</code> which contains a join of the …\n"],["length","Table","Table.html#method-i-length","(colname=nil, value=nil)",""],["new","OrderedRow","OrderedRow.html#method-c-new","(my_array, index)","<p>Creates a new OrderedRow. Callers must specify the index of the row element\nwhich will be used for order …\n"],["new","Table","Table.html#method-c-new","(input=nil)","<p>Instantiate a <code>Table</code> object using a tab-delimited file\n<p>Attributes\n<p>input &mdash; OPTIONAL <code>Array</code> of rows or <code>String</code> …\n"],["row","Table","Table.html#method-i-row","(index)","<p>Return a copy of a row from the table as an <code>Array</code>, given an\nindex (i.e. row number). Returns empty Array …\n"],["select","Table","Table.html#method-i-select","(*columns)","<p>Select columns from the table, given one or more column names. Returns an\ninstance of <code>Table</code> with the …\n"],["size","Table","Table.html#method-i-size","(colname=nil, value=nil)",""],["sort","Table","Table.html#method-i-sort","(column=nil, &block)","<p>Sort the table based on given column. Uses precedence as defined in the \ncolumn. By default will sort …\n"],["sort!","Table","Table.html#method-i-sort-21","(column=nil, &block)",""],["sub","Table","Table.html#method-i-sub","(colname, re, replace)","<p>Given a field/column, and a regular expression to match against, and a\nreplacement string, update the …\n"],["sub!","Table","Table.html#method-i-sub-21","(colname, re, replace)",""],["tally","Table","Table.html#method-i-tally","(colname)","<p>Count instances in a particular field/column and return a\n<code>Table</code> of the results. Raises ArgumentError …\n"],["to_a","Table","Table.html#method-i-to_a","()","<p>Converts a <code>Table</code> object to an array of arrays (each row). The\nfirst entry are the table headers.\n<p>Attributes …\n"],["to_s","Table","Table.html#method-i-to_s","()","<p>Converts a <code>Table</code> object to a tab-delimited string.\n<p>Attributes\n<p>none\n"],["top","Table","Table.html#method-i-top","(colname, num=1)","<p>Returns counts of the most frequent values found in a given column in the\nform of a Table.  Raises ArgumentError …\n"],["union","Table","Table.html#method-i-union","(table2, colname, col2name=colname)","<p>Return Array with the union of elements columns in the given tables,\neliminating duplicates. Raises an …\n"],["where","Table","Table.html#method-i-where","(colname, condition=nil)","<p>Given a particular condition for a given column field/column, return a\nsubtable that matches the condition. …\n"],["write_file","Table","Table.html#method-i-write_file","(filename)","<p>Write a representation of the <code>Table</code> object to a file (tab\ndelimited).\n<p>Attributes\n<p>filename &mdash; <code>String</code> to identify …\n"]]}}

data/doc/table_of_contents.html

@@ -27,6 +27,9 @@
 <h2 id="classes">Classes/Modules</h2>
 <ul>
   <li class="class">
+    <a href="OrderedRow.html">OrderedRow</a>
+  </li>
+    <li class="class">
     <a href="Table.html">Table</a>
   </li>
   
@@ -37,12 +40,32 @@
   
     <li class="method"><a href="Table.html#method-c-new">::new &mdash; Table</a>
   
+    <li class="method"><a href="OrderedRow.html#method-c-new">::new &mdash; OrderedRow</a>
+  
+    <li class="method"><a href="OrderedRow.html#method-i-3C-3D-3E">#<=> &mdash; OrderedRow</a>
+  
+    <li class="method"><a href="Table.html#method-i-add_column">#add_column &mdash; Table</a>
+  
+    <li class="method"><a href="Table.html#method-i-add_row">#add_row &mdash; Table</a>
+  
+    <li class="method"><a href="Table.html#method-i-add_rows">#add_rows &mdash; Table</a>
+  
     <li class="method"><a href="Table.html#method-i-bottom">#bottom &mdash; Table</a>
   
     <li class="method"><a href="Table.html#method-i-column">#column &mdash; Table</a>
   
     <li class="method"><a href="Table.html#method-i-count">#count &mdash; Table</a>
   
+    <li class="method"><a href="OrderedRow.html#method-i-data">#data &mdash; OrderedRow</a>
+  
+    <li class="method"><a href="Table.html#method-i-del_column">#del_column &mdash; Table</a>
+  
+    <li class="method"><a href="Table.html#method-i-del_row">#del_row &mdash; Table</a>
+  
+    <li class="method"><a href="Table.html#method-i-each">#each &mdash; Table</a>
+  
+    <li class="method"><a href="Table.html#method-i-empty-3F">#empty? &mdash; Table</a>
+  
     <li class="method"><a href="Table.html#method-i-get_columns">#get_columns &mdash; Table</a>
   
     <li class="method"><a href="Table.html#method-i-get_rows">#get_rows &mdash; Table</a>
@@ -59,6 +82,10 @@
   
     <li class="method"><a href="Table.html#method-i-size">#size &mdash; Table</a>
   
+    <li class="method"><a href="Table.html#method-i-sort">#sort &mdash; Table</a>
+  
+    <li class="method"><a href="Table.html#method-i-sort-21">#sort! &mdash; Table</a>
+  
     <li class="method"><a href="Table.html#method-i-sub">#sub &mdash; Table</a>
   
     <li class="method"><a href="Table.html#method-i-sub-21">#sub! &mdash; Table</a>

data/lib/tablestakes.rb

@@ -16,8 +16,11 @@
 # serving as the header names. 
 
 class Table
+  include Enumerable
+
   # The headers attribute contains the table headers used to reference
   # columns in the +Table+.  All headers are represented as +String+ types.
+  # 
   attr_reader :headers
   @headers =[]
   @table = {}
@@ -28,7 +31,15 @@ class Table
 
   # Instantiate a +Table+ object using a tab-delimited file
   # 
+  # ==== Attributes
   # +input+:: OPTIONAL +Array+ of rows or +String+ to identify the name of the tab-delimited file to read
+  #
+  # ==== Examples
+  #     cities = Table.new() # empty table
+  #     cities = Table.new([ ["City", "State], ["New York", "NY"], ["Dallas", "TX"] ]) # create from Array of rows
+  #     cities = Table.new("cities.txt") # read from file
+  #     cities = Table.new(capitals)  # create from table
+  #
   def initialize(input=nil)
     @headers = []
     @table = {}
@@ -36,32 +47,49 @@ class Table
     
     if input.respond_to?(:fetch)
       if input[0].respond_to?(:fetch)
-        #create +Table+ from rows
+        #create Table from rows
         add_rows(input)
       end
     elsif input.respond_to?(:upcase)
       # a string, then read_file
       read_file(input)
     elsif input.respond_to?(:headers)
-      init(input)
+      input.each {|row| add_row(row) }
     end
     # else create empty +Table+
   end
+
+  # Defines an iterator for +Table+ which produces rows of data (headers omitted)
+  # for its calling block.
+  #
+  def each
+    @table[@headers.first].each_index do |index|
+      nextrow = []
+      @headers.each do |col|
+        nextrow << @table[col][index].clone
+      end
+      yield nextrow
+    end
+  end
     
   # Return a copy of a column from the table, identified by column name.
-  # Returns +nil+ if column name not found.
+  # Returns empty Array if column name not found.
   # 
+  # ==== Attributes
   # +colname+:: +String+ to identify the name of the column
   def column(colname)
-    # check arguments
-    return nil unless @table.has_key?(colname)
-
-    Array(@table[colname])
+    # return empty Array if column name not found
+    unless @table.has_key?(colname) 
+      Array.new()
+    else
+      Array(@table[colname])
+    end
   end
   
   # Return a copy of a row from the table as an +Array+, given an index
   # (i.e. row number). Returns empty Array if the index is out of bounds.
   # 
+  # ==== Attributes
   # +index+:: +FixNum+ indicating index of the row.
   def row(index)    
     Array(get_row(index))
@@ -76,15 +104,16 @@ class Table
   # Add a column to the Table. Raises ArgumentError if the column name is already taken 
   # or there are not the correct number of values.
   #
-  # +colname+:: +String+ to identify the name of the column
-  # +column_vals+:: +Array+ to hold the column values
-  # Examples:
-  #     add_column("Header", [e1, e2, e3])
-  #     add_column(array_including_header)
-  #     add_column("Header", "e1", "e2", ...)
+  # ==== Attributes
+  # +args+:: Array of +String+ to identify the name of the column (see examples)
+  #
+  # ==== Examples
+  #     cities.add_column("City", ["New York", "Dallas", "San Franscisco"])
+  #     cities.add_column(["City","New York", "Dallas", "San Franscisco"])
+  #     cities.add_column("City", "New York", "Dallas", "San Franscisco")
   def add_column(*args)
     if args.kind_of? Array
-      args = args.flatten
+      args.flatten!
       colname = args.shift
       column_vals = args
     else
@@ -104,9 +133,11 @@ class Table
   # there are not the correct number of values.  The first row becomes the table headers
   # if currently undefined.
   #
+  # ==== Attributes
   # +array_of_rows+:: +Array+ of +Arrays+ to hold the rows values
-  # Examples:
-  #     add_rows([ [e1, e2, e3], [e1, e2, e3] ])
+  #
+  # ==== Examples
+  #     cities.add_rows([ ["New York", "NY"], ["Austin", "TX"] ])
   def add_rows(array_of_rows)
     array_of_rows.each do |r|
       add_row(r.clone)
@@ -117,10 +148,13 @@ class Table
   # Add a row to the Table, appending it to the end. Raises ArgumentError if 
   # there are not the correct number of values.
   #
+  # ==== Attributes
   # +row+:: +Array+ to hold the row values
-  # Examples:
-  #     add_row([e1, e2, e3])
-  #     add_row("e1", "e2", "e3", ...)
+  #
+  # ==== Examples
+  #     cities = Table.new.add_row( ["City", "State"] ) # create new Table with headers
+  #     cities.add_row("New York", "NY") # add data row to Table
+  #
   def add_row(*row)
     if row.kind_of? Array
       row = row.flatten
@@ -140,7 +174,11 @@ class Table
 
   # Delete a column from the Table. Raises ArgumentError if the column name does not exist. 
   #
+  # ==== Attributes
   # +colname+:: +String+ to identify the name of the column
+  #
+  # ==== Examples
+  #     cities.del_column("State") # returns table without "State" column
   def del_column(colname)
     # check arguments
     raise ArgumentError, "Column name does not exist!" unless @table.has_key?(colname)
@@ -151,13 +189,19 @@ class Table
   end
 
   # Delete a row from the Table. Raises ArgumentError if
-  # the row number is not found.
+  # the row number is not found
   #
+  # ==== Attributes
   # +rownum+:: +FixNum+ to hold the row number
+  #
+  # ==== Examples
+  #     cities.del_row(3)  # deletes row with index 3 (4th row)
+  #     cities.del_row(-1) # deletes last row (per Ruby convention)
   def del_row(rownum)
     # check arguments
-    raise ArgumentError, "Row number does not exist!" unless rownum <= @table[@headers.first].length
-
+    if self.empty? || rownum >= @table[@headers.first].length
+      raise ArgumentError, "Row number does not exist!" 
+    end
     @headers.each do |col|
       @table[col].delete_at(rownum)
     end
@@ -167,13 +211,14 @@ class Table
 
   # Converts a +Table+ object to a tab-delimited string.
   # 
+  # ==== Attributes
   # none
   def to_s
     result = @headers.join("\t") << "\n"
     
-    @table[@headers.first].length.times do |row|
+    @table[@headers.first].each_index do |index|
       @headers.each do |col|
-        result << @table[col][row].to_s
+        result << @table[col][index].to_s
         unless col == @headers.last
           result << "\t"
         else
@@ -184,16 +229,18 @@ class Table
     result
   end
   
-  # Converts a +Table+ object to an array of arrays (each row)
+  # Converts a +Table+ object to an array of arrays (each row). The first
+  # entry are the table headers.
   # 
+  # ==== Attributes
   # none
   def to_a
     result = [ Array(@headers) ]
     
-    @table[@headers.first].length.times do |row|
+    @table[@headers.first].each_index do |index|
       items = []
       @headers.each do |col|
-        items << @table[col][row]
+        items << @table[col][index]
       end
       result << items
     end
@@ -204,16 +251,25 @@ class Table
   # and returns an integer >= 0. Returns +nil+ if the column is not found. If
   # no parameters are given, returns the number of rows in the table.
   # 
+  # ==== Attributes
   # +colname+:: OPTIONAL +String+ to identify the column to count
   # +value+:: OPTIONAL +String+ value to count
+  #
+  # ==== Examples
+  #     cities.count  # returns number of rows in cities Table
+  #     cities.size   # same as cities.count
+  #     cities.length # same as cities.count
+  #     cities.count("State", "NY")  # returns the number of rows with State == "NY"
+  #
   def count(colname=nil, value=nil)
     if colname.nil? || value.nil?
       if @table.size > 0
         @table.each_key {|e| return @table.fetch(e).length }
       else
-        return nil
+        return 0
       end
     end
+    raise ArgumentError, "Invalid column name" unless @headers.include?(colname)
     
     if @table[colname]
       result = 0
@@ -229,24 +285,36 @@ class Table
   alias :size :count
   alias :length :count
   
-  # Counts the number of instances of a particular string, given a column name,
-  # and returns an integer >= 0. Returns +nil+ if the column is not found. If
-  # no parameters are given, returns the number of rows in the table.
+  # Returns counts of the most frequent values found in a given column in the form of a
+  # Table.  Raises ArgumentError if the column is not found.  If no limit is given
+  # to the number of values, only the top value will be returned.
   # 
+  # ==== Attributes
   # +colname+:: +String+ to identify the column to count
   # +num+:: OPTIONAL +String+ number of values to return
+  #
+  # ==== Examples
+  #     cities.top("State")  # returns a Table with the most frequent state in the cities Table
+  #     cities.top("State", 10)  # returns a Table with the 10 most frequent states in the cities Table
+  #
   def top(colname, num=1)
     freq = tally(colname).to_a[1..-1].sort_by {|k,v| v }.reverse
     return Table.new(freq[0..num-1].unshift([colname,"Count"]))
   end
 
 
-  # Counts the number of instances of a particular string, given a column name,
-  # and returns an integer >= 0. Returns +nil+ if the column is not found. If
-  # no parameters are given, returns the number of rows in the table.
+  # Returns counts of the least frequent values found in a given column in the form of a
+  # Table.  Raises ArgumentError if the column is not found.  If no limit is given
+  # to the number of values, only the least frequent value will be returned.
   # 
+  # ==== Attributes
   # +colname+:: +String+ to identify the column to count
   # +num+:: OPTIONAL +String+ number of values to return
+  #
+  # ==== Examples
+  #     cities.bottom("State")  # returns a Table with the least frequent state in the cities Table
+  #     cities.bottom("State", 10)  # returns a Table with the 10 least frequent states in the cities Table
+  #
   def bottom(colname, num=1)
     freq = tally(colname).to_a[1..-1].sort_by {|k,v| v }
     return Table.new(freq[0..num-1].unshift([colname,"Count"]))
@@ -255,12 +323,17 @@ class Table
 
 
   # Count instances in a particular field/column and return a +Table+ of the results.
-  # Returns +nil+ if the column is not found.
+  # Raises ArgumentError if the column is not found.
   # 
+  # ==== Attributes
   # +colname+:: +String+ to identify the column to tally
+  #
+  # ==== Examples
+  #     cities.tally("State")  # returns each State in the cities Table with number of occurences
+  #
   def tally(colname)
     # check arguments
-    return nil unless @table.has_key?(colname)
+    raise ArgumentError, "Invalid column name"  unless @table.has_key?(colname)
 
     result = {}
     @table[colname].each do |val|
@@ -270,31 +343,35 @@ class Table
   end
 
   # Select columns from the table, given one or more column names. Returns an instance
-  # of +Table+ with the results.  Returns nil if any column is not valid.
+  # of +Table+ with the results.  Raises ArgumentError if any column is not valid.
   # 
+  # ==== Attributes
   # +columns+:: Variable +String+ arguments to identify the columns to select
+  #
+  # ==== Examples
+  #     cities.select("City", "State")  # returns a Table of "City" and "State" columns
+  #     cities.select(cities.headers)  # returns a new Table that is a duplicate of cities
+  #
   def select(*columns)
     # check arguments
+    raise ArgumentError, "Invalid column name(s)" unless columns
+    columns.kind_of?(Array) ? columns.flatten! : nil
     columns.each do |c|
-      return nil unless @table.has_key?(c)
+      raise ArgumentError, "Invalid column name" unless @table.has_key?(c)
     end
 
     result = []
     result_headers = []
     columns.each { |col| @headers.include?(col) ? result_headers << col : nil }
     result << result_headers
-    @table[@headers.first].length.times do |row|
+    @table[@headers.first].each_index do |index|
       this_row = []
       result_headers.each do |col|
-        this_row << @table[col][row]
+        this_row << @table[col][index]
       end
       result << this_row
     end
-    unless result_headers.empty?
-      return Table.new(result)
-    else
-      return nil
-    end
+    result_headers.empty? ? Table.new() : Table.new(result)
   end
   
   alias :get_columns :select
@@ -302,24 +379,31 @@ class Table
   # Given a particular condition for a given column field/column, return a subtable
   # that matches the condition. If no condition is given, a new +Table+ is returned with
   # all records.
-  # Returns +nil+ if the condition is not met or the column is not found.
+  # Returns an empty table if the condition is not met or the column is not found.
   # 
+  # ==== Attributes
   # +colname+:: +String+ to identify the column to tally
   # +condition+:: OPTIONAL +String+ containing a ruby condition to evaluate
+  #
+  # ==== Examples
+  #     cities.where("State", "=='NY'")  # returns a Table of cities in New York state 
+  #     cities.where("State", "=~ /New.*/")  # returns a Table of cities in states that start with "New"
+  #     cities.where("Population", ".to_i > 1000000")  # returns a Table of cities with population over 1 million
+  #
   def where(colname, condition=nil)
     # check arguments
-    return nil unless @table.has_key?(colname)
+    raise ArgumentError, "Invalid Column Name" unless @headers.include?(colname)
 
     result = []
     result << @headers
-    @table[colname].each_index do |index|
+    self.each do |row|
       if condition
-        eval(%q["#{@table[colname][index]}"] << "#{condition}") ? result << get_row(index) : nil
+        eval(%q["#{row[headers.index(colname)]}"] << "#{condition}") ? result << row : nil
       else
-        result << get_row(index)
+        result << row
       end
     end
-    result.length > 1 ? Table.new(result) : nil
+    result.length > 1 ? Table.new(result) : Table.new()
   end
 
   alias :get_rows :where
@@ -329,29 +413,23 @@ class Table
   # the column name of the first table (if different from the name of thee second).
   # All columns from both tables are returned. Returns +nil+ if the column is not found.
   # 
+  # ==== Attributes
   # +table2+:: +Table+ to identify the secondary table in the join
   # +colname+:: +String+ to identify the column to join on
   # +col2name+:: OPTIONAL +String+ to identify the column in the second table to join on
-  def join(table2, colname, col2name=nil)
+  #
+  # ==== Examples
+  #     cities.join(capitals, "City", "Capital")  # returns a Table of cities that are also state capitals
+  #     capitals.join(cities, "State")  # returns a Table of capital cities with populations info from the cities table
+  #
+  def join(table2, colname, col2name=colname)
     # check arguments
     raise ArgumentError, "Invalid table!" unless table2.is_a?(Table)
-    return nil unless @table.has_key?(colname)
-    if col2name.nil?   # Assume colname applies for both tables
-      col2name = colname
-    end
+    raise ArgumentError, "Invalid column name" unless @table.has_key?(colname)
+    raise ArgumentError, "Invalid column name" unless table2.headers.include?(col2name)
     t2_col_index = table2.headers.index(col2name)
-    return nil unless t2_col_index # is not nil
-
     
-    # ensure no duplication of header values
-    table2.headers.each do |h|
-      if @headers.include?(h)
-        update_header(h, '_' << h )
-        if h == colname
-          colname = '_' << colname
-        end
-      end
-    end
+    dedupe_headers(table2, colname)
 
     result = [ Array(@headers) + Array(table2.headers) ]
     @table[colname].each_index do |index|
@@ -372,14 +450,20 @@ class Table
   # update the table such that it substitutes the column data with the replacement string.
   # Returns +nil+ if the column is not found.
   # 
+  # ==== Attributes
   # +colname+:: +String+ to identify the column to join on
   # +re+:: +Regexp+ to match the value in the selected column
   # +replace+:: +String+ to specify the replacement text for the given +Regexp+
+  #
+  # ==== Examples
+  #     cities.sub("Population", /(.*?),(.*?)/, '\1\2')  # eliminate commas
+  #     capitals.sub("State", /NY/, "New York")  # replace acronym with full name
+  #
   def sub(colname, re, replace)
     # check arguments
     raise ArgumentError, "No regular expression to match against" unless re
     raise ArgumentError, "No replacement string specified" unless replace
-    return nil unless @table.has_key?(colname)
+    raise ArgumentError, "Invalid column name" unless @table.has_key?(colname)
     
     @table[colname].each do |item|
       item.sub!(re, replace)
@@ -387,46 +471,91 @@ class Table
     return self
   end
 
-  # Return the union of columns from different tables, eliminating duplicates.
-  # Return nil if a column is not found.
+  # Return Array with the union of elements columns in the given tables, eliminating duplicates.
+  # Raises an ArgumentError if a column is not found.
   #
+  # ==== Attributes
   # +table2+:: +Table+ to identify the secondary table in the union
   # +colname+:: +String+ to identify the column to union
   # +col2name+:: OPTIONAL +String+ to identify the column in the second table to union
-  def union(table2, colname, col2name=nil)
+  #
+  # ==== Examples
+  #     cities.union(capitals, "City", "Capital")  # returns Array with all cities in both tables
+  #
+  def union(table2, colname, col2name=colname)
     # check arguments
     raise ArgumentError, "Invalid table!" unless table2.is_a?(Table)
-    return nil unless @table.has_key?(colname)
-    if col2name.nil?   # Assume colname applies for both tables
-      col2name = colname
-    end
-    return nil unless table2.headers.include?(col2name)
+    raise ArgumentError, "Invalid column name" unless @table.has_key?(colname)
+    raise ArgumentError, "Invalid column name" unless table2.headers.include?(col2name)
 
     return self.column(colname) | table2.column(col2name)
   end
 
-  # Return the intersection of columns from different tables, eliminating duplicates.
+  # Return an Array with the intersection of columns from different tables, eliminating duplicates.
   # Return nil if a column is not found.
   #
+  # ==== Attributes
   # +table2+:: +Table+ to identify the secondary table in the intersection
   # +colname+:: +String+ to identify the column to intersection
   # +col2name+:: OPTIONAL +String+ to identify the column in the second table to intersection
-  def intersect(table2, colname, col2name=nil)
+  #
+  # ==== Examples
+  #     cities.intersect(capitals, "City", "Capital")  # returns Array with all capitals that are also in the cities table
+  #
+  def intersect(table2, colname, col2name=colname)
     # check arguments
     raise ArgumentError, "Invalid table!" unless table2.is_a?(Table)
-    return nil unless @table.has_key?(colname)
-    if col2name.nil?   # Assume colname applies for both tables
-      col2name = colname
-    end
-    return nil unless table2.headers.include?(col2name)
+    raise ArgumentError, "Invalid column name" unless @table.has_key?(colname)
+    raise ArgumentError, "Invalid column name" unless table2.headers.include?(col2name)
 
     return self.column(colname) & table2.column(col2name)
   end
 
   alias :sub! :sub  
-  
+
+  # Sort the table based on given column. Uses precedence as defined in the 
+  # column. By default will sort by the value in the first column.
+  #
+  # ==== Attributes
+  # +args+:: OPTIONAL +String+ to identify the column on which to sort
+  #
+  # ==== Options
+  #     datatype => :Fixnum
+  #     datatype => :Float
+  #     datatype => :Date
+  #
+  # ==== Examples
+  #     cities.sort("State")  # Re-orders the cities table based on State name
+  #     cities.sort { |a,b| b<=>a }  # Reverse the order of the cities table
+  #     cities.sort("State") { |a,b| b<=>a }  # Sort by State in reverse alpha order
+  #
+  def sort(column=nil, &block)
+    col_index = 0
+    if column.kind_of? String
+      col_index = @headers.index(column)
+    elsif column.kind_of? Fixnum
+      col_index = column 
+    end
+    # return empty Table if empty
+    if self.empty? 
+      return Table.new() 
+    end
+
+    neworder = []
+    self.each { |row| neworder << OrderedRow.new(row,col_index) }
+
+    result = [neworder.shift.data] # take off headers
+    block_given? ? neworder.sort!(&block) : neworder.sort!
+    neworder.each { |row| result << row.data }
+
+    return Table.new(result)
+  end
+
+  alias :sort! :sort
+
   # Write a representation of the +Table+ object to a file (tab delimited).
   # 
+  # ==== Attributes
   # +filename+:: +String+ to identify the name of the file to write
   def write_file(filename)
     file = File.open(filename, "w")
@@ -437,26 +566,19 @@ class Table
 
   def read_file(filename)
     file = File.open(filename, "r")
-    @headers = file.gets.chomp.split("\t")
-    @headers.each {|col| @table.store(col, []) }
-    file.each_line do |line|    
-      fields = line.chomp.split("\t")
-      if fields.length < @headers.length
-        (@headers.length - fields.length).times { fields << "" } 
-      elsif fields.length > @headers.length
-        $stderr.write "INVALID NUMBER OF FIELDS: #{fields.join(';')}\n"
-      else    
-        @headers.each { |col|  @table[col] << fields.shift }
-      end
-    nil
+    result = []
+    file.each_line do |line|
+      result << line.chomp.split("\t")
     end
+    add_rows(result)
   end
   
   def get_row(index)
     result = []
-    @headers.each do |col|
-      result << @table[col][index].to_s
-    end
+    if index >= @table[@headers.first].length
+      return result
+    end 
+    @headers.each { |col| result << @table[col][index].to_s }
     return result
   end
   
@@ -476,27 +598,63 @@ class Table
     @table[colname] = Array.new(column_vals)
     return self
   end
-
-  def copy
-    result = []
-    result << @headers
-    @table[@headers.first].each_index do |index|
-      result << get_row(index)
-    end
-    result.length > 1 ? Table.new(result) : Table.new()
-  end
   
   def update_header(item, new_item)
     i = @headers.index(item)    
     @headers[i] = new_item unless i.nil?
     @table.fetch(item,nil).nil? ? nil : @table[new_item] = @table[item] 
   end
-  
-  def init(table)
-    @headers = table.headers.map {|x| x }
-    @headers.each do |key|
-      @table[key] = table.table[key].map {|x| x }
+
+  def dedupe_headers(table2, colname)
+    # ensure no duplication of header values
+    table2.headers.each do |header|
+      if @headers.include?(header)
+        update_header(header, '_' << header )
+        if header == colname
+          colname = '_' << colname
+        end
+      end
     end
-    @indices = {}
   end
-end
+
+end #Table
+
+# This class functions as a temporary representation of a row. The OrderedRow
+# contains information about which column it should be sorted on, so that 
+# Comparable can be implemented.
+
+class OrderedRow
+  # Contains data elements of the row
+  @data = []
+  # Indicates which row element (column) on which to sort
+  @sort_index = 0
+
+  # Creates a new OrderedRow. Callers must specify the index of the row
+  # element which will be used for order comparisons.
+  # 
+  # ==== Attributes
+  # +my_array+:: An array representing a row from +Table+
+  # +index+:: A Fixnum value which represents the comparison value
+  #
+  def initialize(my_array, index)
+    @data = my_array
+    @sort_index = index
+  end
+
+  # Returns the row elements in an +Array+
+  #
+  # ==== Attributes
+  # none
+  def data
+    return @data
+  end
+
+  # Implements comparable
+  # 
+  # ==== Attributes
+  # +other+:: The row to be compared
+  def <=>(other)
+    self.data[@sort_index] <=> other.data[@sort_index]
+  end
+
+end