fastercsv 0.2.1 → 1.0.0

data/CHANGELOG

@@ -2,6 +2,18 @@
 
 Below is a complete listing of changes for each revision of FasterCSV.
 
+== 1.0.0
+
+* Fixed FasterCSV.rewind() to reset the FasterCSV.lineno() counter.
+* Fixed FasterCSV.rewind() to reset the header processing.
+* Fixed documentation typos.
+* Switched STDOUT and STDERR usage to $stdout and $stderr where appropriate.
+* Added FasterCSV::Row.==().
+* Enhanced FasterCSV::Row.fields() to support Ranges, even for headers.
+* The slurping methods now return the new FasterCSV::Table objects.
+* Fixed parser so multibyte <tt>:col_sep</tt> works now.
+* Added a few examples for usage.
+
 == 0.2.1
 
 * Removed autorequire from GemSpec.
@@ -12,9 +24,9 @@ Below is a complete listing of changes for each revision of FasterCSV.
 
 * Added VERSION constant.
 * Significantly improved test speed.
-* Worked around Date::parse bug so tests will pass on Windows.
+* Worked around Date::parse() bug so tests will pass on Windows.
 * Documented test procedure.
-* Made FasterCSV#lineno CSV aware.
+* Made FasterCSV.lineno() CSV aware.
 * Added line numbers to MalformedCSVError messages.
 * <tt>:headers</tt> can now be set to an Array of headers to use.
 * <tt>:headers</tt> can now be set to an external CSV String of headers to use.
@@ -25,7 +37,7 @@ Below is a complete listing of changes for each revision of FasterCSV.
 * Added header information to FieldInfo Struct for conversions by header.
 * Added an alias to support <tt>require "fastercsv"</tt>.
 * Added FCSV alias for FasterCSV.
-* Added FasterCSV::instance and FasterCSV()/FCSV() shortcuts for easy output.
+* Added FasterCSV::instance() and FasterCSV()/FCSV() shortcuts for easy output.
 
 == 0.1.9
 

data/README

@@ -9,8 +9,8 @@ Welcome to FasterCSV.
 FasterCSV is intended as a replacement to Ruby's standard CSV library.  It was designed to address concerns users of that library had and it has three primary goals:
 
 1.  Be significantly faster than CSV while remaining a pure Ruby library.
-2.  Use a smaller and easier to maintain code base.  (We're about even now,
-    but not if you compare the features!)
+2.  Use a smaller and easier to maintain code base.  (FasterCSV is larger now, 
+    but considerably richer in features.  The parsing core remains quite small.)
 3.  Improve on the CSV interface.
 
 Obviously, the last one is subjective.  If you love CSV's interface, odds are

data/TODO

@@ -3,29 +3,4 @@
 The following is a list of planned expansions for FasterCSV, in no particular
 order.
 
-* Find a good headers solution for data like this:
-    "Experiment ID:	1",,,,,,,,,,,,
-    "Subject ID:	1013938829432171e868c340.
-    Trial,stimulus,time,type,field1,field2,text_response,Abs. time of
-    response,,,,,
-    26,undefined,14828,KEY,RETURN,UNUSED,DCS,Sat Oct 15 17:48:04 GMT-0400
-    2005,,,,,
-    23,undefined,15078,KEY,RETURN,UNUSED,244,Sat Oct 15 17:48:19 GMT-0400
-    2005,,,,,
-    7,nixontrialleft copy.pct [TAG: 1],5953,KEY,1,UNUSED,,Sat Oct 15
-    17:49:24 GMT-0400 2005,,,,,
-    8,nixontrialfront copy.pct [TAG: 3],6250,KEY,3,UNUSED,,Sat Oct 15
-    17:49:31 GMT-0400 2005,,,,,
-    9,nixontrialright copy.pct [TAG: 2],2469,KEY,2,UNUSED,,Sat Oct 15
-    17:49:34 GMT-0400 2005,,,,,
-    #####
-    more data
-    ######
-    ,,,,,,,,,,4374.347222,,
-    ,,,,,,,,,,,,1.00
-    ,,,,,,,,,,,,0.93
-    ### and a new block starts
-    "Experiment ID:	3",,,,,,,,,,,,0.92
-    ....
-* Add calculated fields.
-* Examples, examples, examples...
+  * Rent this space!

data/examples/csv_filter.rb

@@ -1,5 +1,10 @@
 #!/usr/local/bin/ruby -w
 
+# = csv_filter.rb -- Faster CSV Reading and Writing
+#
+#  Created by James Edward Gray II on 2006-04-01.
+#  Copyright 2006 Gray Productions. All rights reserved.
+
 require "faster_csv"
 
 running_total = 0
@@ -13,3 +18,6 @@ FasterCSV.filter( :headers           => true,
     row << (running_total += row[:quantity] * row[:price])
   end
 end
+# >> Quantity,Product Description,Price,Running Total
+# >> 1,Text Editor,25.0,25.0
+# >> 2,MacBook Pros,2499.0,5023.0

data/examples/csv_reading.rb

@@ -0,0 +1,57 @@
+#!/usr/local/bin/ruby -w
+
+# csv_reading.rb
+#
+#  Created by James Edward Gray II on 2006-11-05.
+#  Copyright 2006 Gray Productions. All rights reserved.
+
+require "faster_csv"
+
+CSV_FILE_PATH = File.join(File.dirname(__FILE__), "purchase.csv")
+CSV_STR       = <<END_CSV
+first,last
+James,Gray
+Dana,Gray
+END_CSV
+
+# read a file line by line
+FasterCSV.foreach(CSV_FILE_PATH) do |line|
+  puts line[1]
+end
+# >> Product Description
+# >> Text Editor
+# >> MacBook Pros
+
+# slurp file data
+data = FasterCSV.read(CSV_FILE_PATH)
+puts data.flatten.grep(/\A\d+\.\d+\Z/)
+# >> 25.00
+# >> 2499.00
+
+# read a string line by line
+FasterCSV.parse(CSV_STR) do |line|
+  puts line[0]
+end
+# >> first
+# >> James
+# >> Dana
+
+# slurp string data
+data = FasterCSV.parse(CSV_STR)
+puts data[1..-1].map { |line| "#{line[0][0, 1].downcase}.#{line[1].downcase}" }
+# >> j.gray
+# >> d.gray
+
+# adding options to make data manipulation easy
+total = 0
+FasterCSV.foreach( CSV_FILE_PATH, :headers           => true,
+                                  :header_converters => :symbol,
+                                  :converters        => :numeric ) do |line|
+  line_total = line[:quantity] * line[:price]
+  total += line_total
+  puts "%s: %.2f" % [line[:product_description], line_total]
+end
+puts "Total: %.2f" % total
+# >> Text Editor: 25.00
+# >> MacBook Pros: 4998.00
+# >> Total: 5023.00

data/examples/csv_table.rb

@@ -0,0 +1,56 @@
+#!/usr/local/bin/ruby -w
+
+# csv_table.rb
+#
+#  Created by James Edward Gray II on 2006-11-04.
+#  Copyright 2006 Gray Productions. All rights reserved.
+# 
+# Feature implementation and example code by Ara.T.Howard.
+
+require "faster_csv"
+
+table = FCSV.parse(DATA, :headers => true, :header_converters => :symbol)
+
+# row access
+table[0].class   # => FasterCSV::Row
+table[0].fields  # => ["zaphod", "beeblebrox", "42"]
+
+# column access
+table[:first_name]  # => ["zaphod", "ara"]
+
+# cell access
+table[1][0]            # => "ara"
+table[1][:first_name]  # => "ara"
+table[:first_name][1]  # => "ara"
+
+# manipulation
+table << %w[james gray 30]
+table[-1].fields  # => ["james", "gray", "30"]
+
+table[:type] = "name"
+table[:type]  # => ["name", "name", "name"]
+
+table[:ssn] = %w[123-456-7890 098-765-4321]
+table[:ssn]  # => ["123-456-7890", "098-765-4321", nil]
+
+# iteration
+table.each do |row|
+  # ...
+end
+
+table.by_col!
+table.each do |col_name, col_values|
+  # ...
+end
+
+# output
+puts table
+# >> first_name,last_name,age,type,ssn
+# >> zaphod,beeblebrox,42,name,123-456-7890
+# >> ara,howard,34,name,098-765-4321
+# >> james,gray,30,name,
+
+__END__
+first_name,last_name,age
+zaphod,beeblebrox,42
+ara,howard,34

data/examples/csv_writing.rb

@@ -0,0 +1,67 @@
+#!/usr/local/bin/ruby -w
+
+# csv_rails_import.rb
+#
+#  Created by James Edward Gray II on 2006-11-05.
+#  Copyright 2006 Gray Productions. All rights reserved.
+
+require "faster_csv"
+
+CSV_FILE_PATH = File.join(File.dirname(__FILE__), "output.csv")
+
+# writing to a file
+FasterCSV.open(CSV_FILE_PATH, "w") do |csv|
+  csv << %w[first last]
+  csv << %w[James Gray]
+  csv << %w[Dana Gray]
+end
+puts File.read(CSV_FILE_PATH)
+# >> first,last
+# >> James,Gray
+# >> Dana,Gray
+
+# appending to an existing file
+FasterCSV.open(CSV_FILE_PATH, "a") do |csv|
+  csv << %w[Gypsy]
+  csv << %w[Storm]
+end
+puts File.read(CSV_FILE_PATH)
+# >> first,last
+# >> James,Gray
+# >> Dana,Gray
+# >> Gypsy
+# >> Storm
+
+# writing to a string
+csv_str = FasterCSV.generate do |csv|
+  csv << %w[first last]
+  csv << %w[James Gray]
+  csv << %w[Dana Gray]
+end
+puts csv_str
+# >> first,last
+# >> James,Gray
+# >> Dana,Gray
+
+# appending to an existing string
+FasterCSV.generate(csv_str) do |csv|
+  csv << %w[Gypsy]
+  csv << %w[Storm]
+end
+puts csv_str
+# >> first,last
+# >> James,Gray
+# >> Dana,Gray
+# >> Gypsy
+# >> Storm
+
+# changing the output format
+csv_str = FasterCSV.generate(:col_sep => "\t") do |csv|
+  csv << %w[first last]
+  csv << %w[James Gray]
+  csv << %w[Dana Gray]
+end
+puts csv_str
+# >> first	last
+# >> James	Gray
+# >> Dana	Gray

data/examples/shortcut_interface.rb

@@ -30,3 +30,7 @@ FCSV(STDERR) do |f|
   f << %w( 0 1 2 )
   f << %w( A B C )
 end
+# >> a,b,c
+# >> d,e,f
+# >> q,r,s
+# >> x,y,z

data/lib/faster_csv.rb

@@ -69,13 +69,13 @@ require "stringio"
 # 
 # == Shortcut Interface
 # 
-#   FCSV            { |csv_out| csv_out << %w{my data here} }  # to STDOUT
-#   FCSV(csv = "")  { |csv_str| csv_str << %w{my data here} }  # to a String
-#   FCSV(STDERR)    { |csv_err| csv_err << %w{my data here} }  # to STDERR
+#   FCSV             { |csv_out| csv_out << %w{my data here} }  # to $stdout
+#   FCSV(csv = "")   { |csv_str| csv_str << %w{my data here} }  # to a String
+#   FCSV($stderr)    { |csv_err| csv_err << %w{my data here} }  # to $stderr
 # 
 class FasterCSV
   # The version of the installed library.
-  VERSION = "0.2.1".freeze
+  VERSION = "1.0.0".freeze
   
   # 
   # A FasterCSV::Row is part Array and part Hash.  It retains an order for the
@@ -95,7 +95,7 @@ class FasterCSV
     # FasterCSV::Row.header_row?() and FasterCSV::Row.field_row?(), that this is
     # a header row.  Otherwise, the row is assumes to be a field row.
     # 
-    def initialize( headers, fields, header_row = false )
+    def initialize(headers, fields, header_row = false)
       @header_row = header_row
       
       # handle extra headers or fields
@@ -106,6 +106,10 @@ class FasterCSV
       end
     end
     
+    # Internal data format used to compare equality.
+    attr_reader :row
+    protected   :row
+    
     # Returns +true+ if this is a header row.
     def header_row?
       @header_row
@@ -134,7 +138,7 @@ class FasterCSV
     # than the +offset+ index.  You can use this to find duplicate headers, 
     # without resorting to hard-coding exact indices.
     # 
-    def field( header_or_index, minimum_index = 0 )
+    def field(header_or_index, minimum_index = 0)
       # locate the pair
       finder = header_or_index.is_a?(Integer) ? :[] : :assoc
       pair   = @row[minimum_index..-1].send(finder, header_or_index)
@@ -157,7 +161,7 @@ class FasterCSV
     # to <tt>[nil, nil]</tt>.  Assigning to an unused header appends the new
     # pair.
     # 
-    def []=( *args )
+    def []=(*args)
       value = args.pop
       
       if args.first.is_a? Integer
@@ -190,7 +194,7 @@ class FasterCSV
     # 
     # This method returns the row for chaining.
     # 
-    def <<( arg )
+    def <<(arg)
       if arg.is_a?(Array) and arg.size == 2  # appending a header and name
         @row << arg
       elsif arg.is_a?(Hash)                  # append header and name pairs
@@ -209,7 +213,7 @@ class FasterCSV
     # 
     # This method returns the row for chaining.
     # 
-    def push( *args )
+    def push(*args)
       args.each { |arg| self << arg }
       
       self  # for chaining
@@ -225,7 +229,7 @@ class FasterCSV
     # located as described in FasterCSV::Row.field().  The deleted pair is 
     # returned, or +nil+ if a pair could not be found.
     # 
-    def delete( header_or_index, minimum_index = 0 )
+    def delete(header_or_index, minimum_index = 0)
       if header_or_index.is_a? Integer  # by index
         @row.delete_at(header_or_index)
       else                              # by header
@@ -240,7 +244,7 @@ class FasterCSV
     # 
     # This method returns the row for chaining.
     # 
-    def delete_if( &block )
+    def delete_if(&block)
       @row.delete_if(&block)
       
       self  # for chaining
@@ -248,16 +252,29 @@ class FasterCSV
     
     # 
     # This method accepts any number of arguments which can be headers, indices,
-    # or two-element Arrays containing a header and offset.  Each argument will
-    # be replaced with a field lookup as described in FasterCSV::Row.field().
+    # Ranges of either, or two-element Arrays containing a header and offset.  
+    # Each argument will be replaced with a field lookup as described in
+    # FasterCSV::Row.field().
     # 
     # If called with no arguments, all fields are returned.
     # 
-    def fields( *headers_and_or_indices )
+    def fields(*headers_and_or_indices)
       if headers_and_or_indices.empty?  # return all fields--no arguments
         @row.map { |pair| pair.last }
       else                              # or work like values_at()
-        headers_and_or_indices.map { |h_or_i| field(*Array(h_or_i)) }
+        headers_and_or_indices.inject(Array.new) do |all, h_or_i|
+          all + if h_or_i.is_a? Range
+            index_begin = h_or_i.begin.is_a?(Integer) ? h_or_i.begin :
+                                                        index(h_or_i.begin)
+            index_end   = h_or_i.end.is_a?(Integer)   ? h_or_i.end :
+                                                        index(h_or_i.end)
+            new_range   = h_or_i.exclude_end? ? (index_begin...index_end) :
+                                                (index_begin..index_end)
+            fields.values_at(new_range)
+          else
+            [field(*Array(h_or_i))]
+          end
+        end
       end
     end
     alias_method :values_at, :fields
@@ -271,7 +288,7 @@ class FasterCSV
     # The +offset+ can be used to locate duplicate header names, as described in
     # FasterCSV::Row.field().
     # 
-    def index( header, minimum_index = 0 )
+    def index(header, minimum_index = 0)
       # find the pair
       index = headers[minimum_index..-1].index(header)
       # return the index at the right offset, if we found one
@@ -279,7 +296,7 @@ class FasterCSV
     end
     
     # Returns +true+ if +name+ is a header for this row, and +false+ otherwise.
-    def header?( name )
+    def header?(name)
       headers.include? name
     end
     alias_method :include?, :header?
@@ -288,7 +305,7 @@ class FasterCSV
     # Returns +true+ if +data+ matches a field in this row, and +false+
     # otherwise.
     # 
-    def field?( data )
+    def field?(data)
       fields.include? data
     end
 
@@ -302,12 +319,20 @@ class FasterCSV
     # 
     # This method returns the row for chaining.
     # 
-    def each( &block )
+    def each(&block)
       @row.each(&block)
       
       self  # for chaining
     end
     
+    # 
+    # Returns +true+ if this row contains the same headers and fields in the 
+    # same order as +other+.
+    # 
+    def ==(other)
+      @row == other.row
+    end
+    
     # 
     # Collapses the row into a simple Hash.  Be warning that this discards field
     # order and clobbers duplicate fields.
@@ -322,11 +347,331 @@ class FasterCSV
     # 
     #   faster_csv_row.fields.to_csv( options )
     # 
-    def to_csv( options = Hash.new )
+    def to_csv(options = Hash.new)
       fields.to_csv(options)
     end
     alias_method :to_s, :to_csv
   end
+  
+  # 
+  # A FasterCSV::Table is a two-dimensional data structure for representing CSV
+  # documents.  Tables allow you to work with the data by row or column, 
+  # manipulate the data, and even convert the results back to CSV, if needed.
+  # 
+  # All tables returned by FasterCSV will be constructed from this class, if
+  # header row processing is activated.
+  # 
+  class Table
+    # 
+    # Construct a new FasterCSV::Table from +array_of_rows+, which are expected
+    # to be FasterCSV::Row objects.  All rows are assumed to have the same 
+    # headers.
+    # 
+    def initialize(array_of_rows)
+      @table = array_of_rows
+      @mode  = :col_or_row
+    end
+    
+    # The current access mode for indexing and iteration.
+    attr_reader :mode
+    
+    # Internal data format used to compare equality.
+    attr_reader :table
+    protected   :table
+    
+    # 
+    # Returns a duplicate table object, in column mode.  This is handy for 
+    # chaining in a single call without changing the table mode, but be aware 
+    # that this method can consume a fair amount of memory for bigger data sets.
+    # 
+    # This method returns the duplicate table for chaining.  Don't chain
+    # destructive methods (like []=()) this way though, since you are working
+    # with a duplicate.
+    # 
+    def by_col
+      self.class.new(@table.dup).by_col!
+    end
+    
+    # 
+    # Switches the mode of this table to column mode.  All calls to indexing and
+    # iteration methods will work with columns until the mode is changed again.
+    # 
+    # This method returns the table and is safe to chain.
+    # 
+    def by_col!
+      @mode = :col
+      
+      self
+    end
+    
+    # 
+    # Returns a duplicate table object, in mixed mode.  This is handy for 
+    # chaining in a single call without changing the table mode, but be aware 
+    # that this method can consume a fair amount of memory for bigger data sets.
+    # 
+    # This method returns the duplicate table for chaining.  Don't chain
+    # destructive methods (like []=()) this way though, since you are working
+    # with a duplicate.
+    # 
+    def by_col_or_row
+      self.class.new(@table.dup).by_col_or_row!
+    end
+    
+    # 
+    # Switches the mode of this table to mixed mode.  All calls to indexing and
+    # iteration methods will use the default intelligent indexing system until
+    # the mode is changed again.  In mixed mode an index is assumed to be a row
+    # reference while anything else is assumed to be column access by headers.
+    # 
+    # This method returns the table and is safe to chain.
+    # 
+    def by_col_or_row!
+      @mode = :col_or_row
+      
+      self
+    end
+    
+    # 
+    # Returns a duplicate table object, in row mode.  This is handy for chaining
+    # in a single call without changing the table mode, but be aware that this
+    # method can consume a fair amount of memory for bigger data sets.
+    # 
+    # This method returns the duplicate table for chaining.  Don't chain
+    # destructive methods (like []=()) this way though, since you are working
+    # with a duplicate.
+    # 
+    def by_row
+      self.class.new(@table.dup).by_row!
+    end
+    
+    # 
+    # Switches the mode of this table to row mode.  All calls to indexing and
+    # iteration methods will work with rows until the mode is changed again.
+    # 
+    # This method returns the table and is safe to chain.
+    # 
+    def by_row!
+      @mode = :row
+      
+      self
+    end
+    
+    # 
+    # Returns the headers for the first row of this table (assumed to match all
+    # other rows).  An empty Array is returned for empty tables.
+    # 
+    def headers
+      if @table.empty?
+        Array.new
+      else
+        @table.first.headers
+      end
+    end
+    
+    # 
+    # In the default mixed mode, this method returns rows for index access and
+    # columns for header access.  You can force the index association by first
+    # calling by_col!() or by_row!().
+    # 
+    # Columns are returned as an Array of values.  Altering that Array has no
+    # effect on the table.
+    # 
+    def [](index_or_header)
+      if @mode == :row or  # by index
+         (@mode == :col_or_row and index_or_header.is_a? Integer)
+        @table[index_or_header]
+      else                 # by header
+        @table.map { |row| row[index_or_header] }
+      end
+    end
+    
+    # 
+    # In the default mixed mode, this method assigns rows for index access and
+    # columns for header access.  You can force the index association by first
+    # calling by_col!() or by_row!().
+    # 
+    # Rows may be set to an Array of values (which will inherit the table's
+    # headers()) or a FasterCSV::Row.
+    # 
+    # Columns may be set to a single value, which is copied to each row of the 
+    # column, or an Array of values.  Arrays of values are assigned to rows top
+    # to bottom in row major order.  Excess values are ignored and if the Array
+    # does not have a value for each row the extra rows will receive a +nil+.
+    # 
+    # Assigning to an existing column or row clobbers the data.  Assigning to
+    # new columns creates them at the right end of the table.
+    # 
+    def []=(index_or_header, value)
+      if @mode == :row or  # by index
+         (@mode == :col_or_row and index_or_header.is_a? Integer)
+        if value.is_a? Array
+          @table[index_or_header] = Row.new(headers, value)
+        else
+          @table[index_or_header] = value
+        end
+      else                 # set column
+        if value.is_a? Array  # multiple values
+          @table.each_with_index do |row, i|
+            if row.header_row?
+              row[index_or_header] = index_or_header
+            else
+              row[index_or_header] = value[i]
+            end
+          end
+        else                  # repeated value
+          @table.each do |row|
+            if row.header_row?
+              row[index_or_header] = index_or_header
+            else
+              row[index_or_header] = value
+            end
+          end
+        end
+      end
+    end
+    
+    # 
+    # The mixed mode default is to treat a list of indices as row access,
+    # returning the rows indicated.  Anything else is considered columnar
+    # access.  For columnar access, the return set has an Array for each row
+    # with the values indicated by the headers in each Array.  You can force
+    # column or row mode using by_col!() or by_row!().
+    # 
+    # You cannot mix column and row access.
+    # 
+    def values_at(*indices_or_headers)
+      if @mode == :row or  # by indices
+         ( @mode == :col_or_row and indices_or_headers.all? do |index|
+                                      index.is_a?(Integer)         or
+                                      ( index.is_a?(Range)         and
+                                        index.first.is_a?(Integer) and
+                                        index.last.is_a?(Integer) )
+                                    end )
+        @table.values_at(*indices_or_headers)
+      else                 # by headers
+        @table.map { |row| row.values_at(*indices_or_headers) }
+      end
+    end
+
+    # 
+    # Adds a new row to the bottom end of this table.  You can provide an Array,
+    # which will be converted to a FasterCSV::Row (inheriting the table's
+    # headers()), or a FasterCSV::Row.
+    # 
+    # This method returns the table for chaining.
+    # 
+    def <<(row_or_array)
+      if row_or_array.is_a? Array  # append Array
+        @table << Row.new(headers, row_or_array)
+      else                         # append Row
+        @table << row_or_array
+      end
+      
+      self  # for chaining
+    end
+    
+    # 
+    # A shortcut for appending multiple rows.  Equivalent to:
+    # 
+    #   rows.each { |row| self << row }
+    # 
+    # This method returns the table for chaining.
+    # 
+    def push(*rows)
+      rows.each { |row| self << row }
+      
+      self  # for chaining
+    end
+
+    # 
+    # Removes and returns the indicated column or row.  In the default mixed
+    # mode indices refer to rows and everything else is assumed to be a column
+    # header.  Use by_col!() or by_row!() to force the lookup.
+    # 
+    def delete(index_or_header)
+      if @mode == :row or  # by index
+         (@mode == :col_or_row and index_or_header.is_a? Integer)
+        @table.delete_at(index_or_header)
+      else                 # by header
+        @table.map { |row| row.delete(index_or_header).last }
+      end
+    end
+    
+    # 
+    # Removes any column or row for which the block returns +true+.  In the
+    # default mixed mode or row mode, iteration is the standard row major
+    # walking of rows.  In column mode, interation will +yield+ two element
+    # tuples containing the column name and an Array of values for that column.
+    # 
+    # This method returns the table for chaining.
+    # 
+    def delete_if(&block)
+      if @mode == :row or @mode == :col_or_row  # by index
+        @table.delete_if(&block)
+      else                                      # by header
+        to_delete = Array.new
+        headers.each_with_index do |header, i|
+          to_delete << header if block[[header, self[header]]]
+        end
+        to_delete.map { |header| delete(header) }
+      end
+      
+      self  # for chaining
+    end
+    
+    include Enumerable
+    
+    # 
+    # In the default mixed mode or row mode, iteration is the standard row major
+    # walking of rows.  In column mode, interation will +yield+ two element
+    # tuples containing the column name and an Array of values for that column.
+    # 
+    # This method returns the table for chaining.
+    # 
+    def each(&block)
+      if @mode == :col
+        headers.each { |header| block[[header, self[header]]] }
+      else
+        @table.each(&block)
+      end
+      
+      self  # for chaining
+    end
+    
+    # Returns +true+ if all rows of this table ==() +other+'s rows.
+    def ==(other)
+      @table == other.table
+    end
+    
+    # 
+    # Returns the table as an Array of Arrays.  Headers will be the first row,
+    # then all of the field rows will follow.
+    # 
+    def to_a
+      @table.inject([headers]) do |array, row|
+        if row.header_row?
+          array
+        else
+          array + [row.fields]
+        end
+      end
+    end
+    
+    # 
+    # Returns the table as a complete CSV String.  Headers will be listed first,
+    # then all of the field rows.
+    # 
+    def to_csv(options = Hash.new)
+      @table.inject([headers.to_csv(options)]) do |rows, row|
+        if row.header_row?
+          rows
+        else
+          rows + [row.fields.to_csv(options)]
+        end
+      end.join
+    end
+    alias_method :to_s, :to_csv
+  end
 
   # The error thrown when the parser encounters illegal CSV formatting.
   class MalformedCSVError < RuntimeError; end
@@ -442,15 +787,15 @@ class FasterCSV
   # 
   def self.build_csv_interface
     Object.const_set(:CSV, Class.new).class_eval do
-      def self.foreach( path, rs = :auto, &block )  # :nodoc:
+      def self.foreach(path, rs = :auto, &block)  # :nodoc:
         FasterCSV.foreach(path, :row_sep => rs, &block)
       end
       
-      def self.generate_line( row, fs = ",", rs = "" )  # :nodoc:
+      def self.generate_line(row, fs = ",", rs = "")  # :nodoc:
         FasterCSV.generate_line(row, :col_sep => fs, :row_sep => rs)
       end
       
-      def self.open( path, mode, fs = ",", rs = :auto, &block )  # :nodoc:
+      def self.open(path, mode, fs = ",", rs = :auto, &block)  # :nodoc:
         if block and mode.include? "r"
           FasterCSV.open(path, mode, :col_sep => fs, :row_sep => rs) do |csv|
             csv.each(&block)
@@ -460,15 +805,15 @@ class FasterCSV
         end
       end
       
-      def self.parse( str_or_readable, fs = ",", rs = :auto, &block )  # :nodoc:
+      def self.parse(str_or_readable, fs = ",", rs = :auto, &block)  # :nodoc:
         FasterCSV.parse(str_or_readable, :col_sep => fs, :row_sep => rs, &block)
       end
       
-      def self.parse_line( src, fs = ",", rs = :auto )  # :nodoc:
+      def self.parse_line(src, fs = ",", rs = :auto)  # :nodoc:
         FasterCSV.parse_line(src, :col_sep => fs, :row_sep => rs)
       end
       
-      def self.readlines( path, rs = :auto )  # :nodoc:
+      def self.readlines(path, rs = :auto)  # :nodoc:
         FasterCSV.readlines(path, :row_sep => rs)
       end
     end
@@ -509,7 +854,7 @@ class FasterCSV
   # The +io+ parameter can be used to serialize to a File, and +options+ can be
   # anything FasterCSV::new() accepts.
   # 
-  def self.dump( ary_of_objs, io = "", options = Hash.new )
+  def self.dump(ary_of_objs, io = "", options = Hash.new)
     obj_template = ary_of_objs.first
     
     csv = FasterCSV.new(io, options)
@@ -566,7 +911,7 @@ class FasterCSV
   # 
   # The +input+ and +output+ arguments can be anything FasterCSV::new() accepts
   # (generally String or IO objects).  If not given, they default to 
-  # <tt>ARGF</tt> and <tt>STDOUT</tt>.
+  # <tt>ARGF</tt> and <tt>$stdout</tt>.
   # 
   # The +options+ parameter is also filtered down to FasterCSV::new() after some
   # clever key parsing.  Any key beginning with <tt>:in_</tt> or 
@@ -578,7 +923,7 @@ class FasterCSV
   # The <tt>:output_row_sep</tt> +option+ defaults to
   # <tt>$INPUT_RECORD_SEPARATOR</tt> (<tt>$/</tt>).
   # 
-  def self.filter( *args )
+  def self.filter(*args)
     # parse options for input, output, or both
     in_options, out_options = Hash.new, {:row_sep => $INPUT_RECORD_SEPARATOR}
     if args.last.is_a? Hash
@@ -595,8 +940,8 @@ class FasterCSV
       end
     end
     # build input and output wrappers
-    input   = FasterCSV.new(args.shift || ARGF,   in_options)
-    output  = FasterCSV.new(args.shift || STDOUT, out_options)
+    input   = FasterCSV.new(args.shift || ARGF,    in_options)
+    output  = FasterCSV.new(args.shift || $stdout, out_options)
     
     # read, yield, write
     input.each do |row|
@@ -610,9 +955,9 @@ class FasterCSV
   # pass a +path+ and any +options+ you wish to set for the read.  Each row of
   # file will be passed to the provided +block+ in turn.
   # 
-  # The +options+ parameter can be anthing FasterCSV::new() understands.
+  # The +options+ parameter can be anything FasterCSV::new() understands.
   # 
-  def self.foreach( path, options = Hash.new, &block )
+  def self.foreach(path, options = Hash.new, &block)
     open(path, options) do |csv|
       csv.each(&block)
     end
@@ -633,7 +978,7 @@ class FasterCSV
   # 
   # The +options+ parameter can be anthing FasterCSV::new() understands.
   # 
-  def self.generate( *args )
+  def self.generate(*args)
     # add a default empty String, if none was given
     if args.first.is_a? String
       io = StringIO.new(args.shift)
@@ -656,7 +1001,7 @@ class FasterCSV
   # The <tt>:row_sep</tt> +option+ defaults to <tt>$INPUT_RECORD_SEPARATOR</tt>
   # (<tt>$/</tt>) when calling this method.
   # 
-  def self.generate_line( row, options = Hash.new )
+  def self.generate_line(row, options = Hash.new)
     options = {:row_sep => $INPUT_RECORD_SEPARATOR}.merge(options)
     (new("", options) << row).string
   end
@@ -665,12 +1010,12 @@ class FasterCSV
   # This method will return a FasterCSV instance, just like FasterCSV::new(), 
   # but the instance will be cached and returned for all future calls to this 
   # method for the same +data+ object (tested by Object#object_id()) with the
-  # same +options+
+  # same +options+.
   # 
   # If a block is given, the instance is passed to the block and the return
   # value becomes the return value of the block.
   # 
-  def self.instance( data = STDOUT, options = Hash.new )
+  def self.instance(data = $stdout, options = Hash.new)
     # create a _signature_ for this method call, data object and options
     sig = [data.object_id] +
           options.values_at(*DEFAULT_OPTIONS.keys.sort_by { |sym| sym.to_s })
@@ -698,7 +1043,7 @@ class FasterCSV
   # something else, use +options+ to setup converters or provide a custom
   # csv_load() implementation.
   # 
-  def self.load( io_or_str, options = Hash.new )
+  def self.load(io_or_str, options = Hash.new)
     csv = FasterCSV.new(io_or_str, options)
     
     # load meta information
@@ -768,7 +1113,6 @@ class FasterCSV
   # * pid()
   # * pos()
   # * reopen()
-  # * rewind()
   # * seek()
   # * stat()
   # * sync()
@@ -778,7 +1122,7 @@ class FasterCSV
   # * to_io()
   # * tty?()
   # 
-  def self.open( *args )
+  def self.open(*args)
     # find the +options+ Hash
     options = if args.last.is_a? Hash then args.pop else Hash.new end
     # wrap a File opened with the remaining +args+
@@ -808,7 +1152,7 @@ class FasterCSV
   # You pass your +str+ to read from, and an optional +options+ Hash containing
   # anything FasterCSV::new() understands.
   # 
-  def self.parse( *args, &block )
+  def self.parse(*args, &block)
     csv = new(*args)
     if block.nil?  # slurp contents, if no block is given
       begin
@@ -828,7 +1172,7 @@ class FasterCSV
   # 
   # The +options+ parameter can be anthing FasterCSV::new() understands.
   # 
-  def self.parse_line( line, options = Hash.new )
+  def self.parse_line(line, options = Hash.new)
     new(line, options).shift
   end
   
@@ -836,12 +1180,12 @@ class FasterCSV
   # Use to slurp a CSV file into an Array of Arrays.  Pass the +path+ to the 
   # file and any +options+ FasterCSV::new() understands.
   # 
-  def self.read( path, options = Hash.new )
+  def self.read(path, options = Hash.new)
     open(path, options) { |csv| csv.read }
   end
   
   # Alias for FasterCSV::read().
-  def self.readlines( *args )
+  def self.readlines(*args)
     read(*args)
   end
   
@@ -906,7 +1250,9 @@ class FasterCSV
   #                                       Array of headers.  This setting causes
   #                                       FasterCSV.shift() to return rows as
   #                                       FasterCSV::Row objects instead of
-  #                                       Arrays.
+  #                                       Arrays and FasterCSV.read() to return
+  #                                       FasterCSV::Table objects instead of
+  #                                       an Array of Arrays.
   # <b><tt>:return_headers</tt></b>::     When +false+, header rows are silently
   #                                       swallowed.  If set to +true+, header
   #                                       rows are returned in a FasterCSV::Row
@@ -923,7 +1269,7 @@ class FasterCSV
   # Options cannot be overriden in the instance methods for performance reasons,
   # so be sure to set what you want here.
   # 
-  def initialize( data, options = Hash.new )
+  def initialize(data, options = Hash.new)
     # build the options for this read/write
     options = DEFAULT_OPTIONS.merge(options)
     
@@ -943,19 +1289,27 @@ class FasterCSV
     @lineno = 0
   end
   
+  ### IO and StringIO Delegation ###
+  
   # 
   # The line number of the last row read from this file.  Fields with nested 
   # line-end characters will not affect this count.
   # 
   attr_reader :lineno
   
-  ### IO and StringIO Delegation ###
-  
   extend Forwardable
   def_delegators :@io, :binmode, :close, :close_read, :close_write, :closed?,
                        :eof, :eof?, :fcntl, :fileno, :flush, :fsync, :ioctl,
-                       :isatty, :pid, :pos, :reopen, :rewind, :seek, :stat,
-                       :string, :sync, :sync=, :tell, :to_i, :to_io, :tty?
+                       :isatty, :pid, :pos, :reopen, :seek, :stat, :string,
+                       :sync, :sync=, :tell, :to_i, :to_io, :tty?
+  
+  # Rewinds the underlying IO object and resets FasterCSV's lineno() counter.
+  def rewind
+    @headers = nil
+    @lineno  = 0
+    
+    @io.rewind
+  end
 
   ### End Delegation ###
   
@@ -967,16 +1321,16 @@ class FasterCSV
   # 
   # The data source must be open for writing.
   # 
-  def <<( row )
+  def <<(row)
     # handle FasterCSV::Row objects
     row = row.fields if row.is_a? self.class::Row
     
     @io << row.map do |field|
-      if field.nil?  # reverse +nil+ fields as empty unquoted fields
+      if field.nil?  # represent +nil+ fields as empty unquoted fields
         ""
       else
         field = String(field)  # Stringify fields
-        # reverse empty fields as empty quoted fields
+        # represent empty fields as empty quoted fields
         if field.empty? or field.count(%Q{\r\n#{@col_sep}"}).nonzero?
           %Q{"#{field.gsub('"', '""')}"}  # escape quoted fields
         else
@@ -1005,7 +1359,7 @@ class FasterCSV
   # containing details about the field.  Again, the block should return a 
   # converted field or the field itself.
   # 
-  def convert( name = nil, &converter )
+  def convert(name = nil, &converter)
     add_converter(:converters, self.class::Converters, name, &converter)
   end
 
@@ -1020,7 +1374,7 @@ class FasterCSV
   # Note that this method must be called before header rows are read to have any
   # effect.
   # 
-  def header_convert( name = nil, &converter )
+  def header_convert(name = nil, &converter)
     add_converter( :header_converters,
                    self.class::HeaderConverters,
                    name,
@@ -1048,7 +1402,12 @@ class FasterCSV
   # The data source must be open for reading.
   # 
   def read
-    to_a
+    rows = to_a
+    if @use_headers
+      Table.new(rows)
+    else
+      rows
+    end
   end
   alias_method :readlines, :read
   
@@ -1112,7 +1471,7 @@ class FasterCSV
       # on these
       # 
       csv = if parse.sub!(@parsers[:leading_fields], "")
-        [nil] * $&.length
+        [nil] * ($&.length / @col_sep.length)
       else
         Array.new
       end
@@ -1176,12 +1535,11 @@ class FasterCSV
   # Stores the indicated separators for later use.
   # 
   # If auto-discovery was requested for <tt>@row_sep</tt>, this method will read
-  # ahead in the <tt>@io</tt> and try to find one.  <tt>ARGF</tt>,
-  # <tt>STDIN</tt>, <tt>STDOUT</tt>, <tt>STDERR</tt> and any stream open for
-  # output only with a default <tt>@row_sep</tt> of
-  # <tt>$INPUT_RECORD_SEPARATOR</tt> (<tt>$/</tt>).
+  # ahead in the <tt>@io</tt> and try to find one.  +ARGF+, +STDIN+, +STDOUT+,
+  # +STDERR+ and any stream open for output only with a default
+  # <tt>@row_sep</tt> of <tt>$INPUT_RECORD_SEPARATOR</tt> (<tt>$/</tt>).
   # 
-  def init_separators( options )
+  def init_separators(options)
     # store the selected separators
     @col_sep = options.delete(:col_sep)
     @row_sep = options.delete(:row_sep)
@@ -1222,11 +1580,11 @@ class FasterCSV
   end
   
   # Pre-compiles parsers and stores them by name for access during reads.
-  def init_parsers( options )
+  def init_parsers(options)
     # prebuild Regexps for faster parsing
     @parsers    = {
       :leading_fields =>
-        /\A#{Regexp.escape(@col_sep)}+/,         # for empty leading fields
+        /\A(?:#{Regexp.escape(@col_sep)})+/,     # for empty leading fields
       :csv_row        =>
         ### The Primary Parser ###
         / \G(?:^|#{Regexp.escape(@col_sep)})     # anchor the match
@@ -1250,7 +1608,7 @@ class FasterCSV
   # The <tt>:unconverted_fields</tt> option is also actived for 
   # <tt>:converters</tt> calls, if requested.
   # 
-  def init_converters( options, field_name = :converters )
+  def init_converters(options, field_name = :converters)
     if field_name == :converters
       @unconverted_fields = options.delete(:unconverted_fields)
     end
@@ -1280,7 +1638,7 @@ class FasterCSV
   end
   
   # Stores header row settings and loads header converters, if needed.
-  def init_headers( options )
+  def init_headers(options)
     @use_headers    = options.delete(:headers)
     @return_headers = options.delete(:return_headers)
 
@@ -1299,7 +1657,7 @@ class FasterCSV
   # normal parameters of the FasterCSV.convert() and FasterCSV.header_convert()
   # methods.
   # 
-  def add_converter( var_name, const, name = nil, &converter )
+  def add_converter(var_name, const, name = nil, &converter)
     if name.nil?  # custom converter
       instance_variable_get("@#{var_name}") << converter
     else          # named converter
@@ -1322,7 +1680,7 @@ class FasterCSV
   # the pipeline of conversion for that field.  This is primarily an efficiency
   # shortcut.
   # 
-  def convert_fields( fields, headers = false )
+  def convert_fields(fields, headers = false)
     # see if we are converting headers or fields
     converters = headers ? @header_converters : @converters
     
@@ -1350,7 +1708,7 @@ class FasterCSV
   # When +nil+, +row+ is assumed to be a header row not based on an actual row
   # of the stream.
   # 
-  def parse_headers( row = nil )
+  def parse_headers(row = nil)
     if @headers.nil?                # header row
       @headers = case @use_headers  # save headers
       when Array  then @use_headers                         # Array of headers
@@ -1377,7 +1735,7 @@ class FasterCSV
   # +row+ and an accessor method for it called unconverted_fields().  The
   # variable is set to the contents of +fields+.
   # 
-  def add_unconverted_fields( row, fields )
+  def add_unconverted_fields(row, fields)
     class << row
       attr_reader :unconverted_fields
     end
@@ -1390,25 +1748,25 @@ end
 FCSV = FasterCSV
 
 # Another name for FasterCSV::instance().
-def FasterCSV( *args, &block )
+def FasterCSV(*args, &block)
   FasterCSV.instance(*args, &block)
 end
 
 # Another name for FCSV::instance().
-def FCSV( *args, &block )
+def FCSV(*args, &block)
   FCSV.instance(*args, &block)
 end
 
 class Array
   # Equivalent to <tt>FasterCSV::generate_line(self, options)</tt>.
-  def to_csv( options = Hash.new )
+  def to_csv(options = Hash.new)
     FasterCSV.generate_line(self, options)
   end
 end
 
 class String
   # Equivalent to <tt>FasterCSV::parse_line(self, options)</tt>.
-  def parse_csv( options = Hash.new )
+  def parse_csv(options = Hash.new)
     FasterCSV.parse_line(self, options)
   end
 end