csv 3.1.7 → 3.2.1

data/lib/csv/table.rb

@@ -4,12 +4,12 @@ require "forwardable"
 
 class CSV
   # = \CSV::Table
-  # A \CSV::Table instance is an object representing \CSV data.
+  # A \CSV::Table instance represents \CSV data.
   # (see {class CSV}[../CSV.html]).
   #
   # The instance may have:
-  # - Rows:  each is a Table::Row object.
-  # - Headers:  names for the columns.
+  # - Rows: each is a Table::Row object.
+  # - Headers: names for the columns.
   #
   # === Instance Methods
   #
@@ -143,7 +143,7 @@ class CSV
   #   table['Name'] # => ["Foo", "Bar", "Baz"]
   class Table
     # :call-seq:
-    #   CSV::Table.new(array_of_rows, headers = nil)
+    #   CSV::Table.new(array_of_rows, headers = nil) -> csv_table
     #
     # Returns a new \CSV::Table object.
     #
@@ -223,7 +223,7 @@ class CSV
     def_delegators :@table, :empty?, :length, :size
 
     # :call-seq:
-    #   table.by_col
+    #   table.by_col -> table_dup
     #
     # Returns a duplicate of +self+, in column mode
     # (see {Column Mode}[#class-CSV::Table-label-Column+Mode]):
@@ -244,7 +244,7 @@ class CSV
     end
 
     # :call-seq:
-    #   table.by_col!
+    #   table.by_col! -> self
     #
     # Sets the mode for +self+ to column mode
     # (see {Column Mode}[#class-CSV::Table-label-Column+Mode]); returns +self+:
@@ -261,7 +261,7 @@ class CSV
     end
 
     # :call-seq:
-    #   table.by_col_or_row
+    #   table.by_col_or_row -> table_dup
     #
     # Returns a duplicate of +self+, in mixed mode
     # (see {Mixed Mode}[#class-CSV::Table-label-Mixed+Mode]):
@@ -282,7 +282,7 @@ class CSV
     end
 
     # :call-seq:
-    #   table.by_col_or_row!
+    #   table.by_col_or_row! -> self
     #
     # Sets the mode for +self+ to mixed mode
     # (see {Mixed Mode}[#class-CSV::Table-label-Mixed+Mode]); returns +self+:
@@ -299,7 +299,7 @@ class CSV
     end
 
     # :call-seq:
-    #   table.by_row
+    #   table.by_row -> table_dup
     #
     # Returns a duplicate of +self+, in row mode
     # (see {Row Mode}[#class-CSV::Table-label-Row+Mode]):
@@ -320,7 +320,7 @@ class CSV
     end
 
     # :call-seq:
-    #   table.by_row!
+    #   table.by_row! -> self
     #
     # Sets the mode for +self+ to row mode
     # (see {Row Mode}[#class-CSV::Table-label-Row+Mode]); returns +self+:
@@ -337,7 +337,7 @@ class CSV
     end
 
     # :call-seq:
-    #   table.headers
+    #   table.headers -> array_of_headers
     #
     # Returns a new \Array containing the \String headers for the table.
     #
@@ -365,14 +365,152 @@ class CSV
       end
     end
 
+    # :call-seq:
+    #   table[n] -> row or column_data
+    #   table[range] -> array_of_rows or array_of_column_data
+    #   table[header] -> array_of_column_data
+    #
+    # Returns data from the table;  does not modify the table.
+    #
+    # ---
+    #
+    # Fetch a \Row by Its \Integer Index::
+    # - Form: <tt>table[n]</tt>, +n+ an integer.
+    # - Access mode: <tt>:row</tt> or <tt>:col_or_row</tt>.
+    # - Return value: _nth_ row of the table, if that row exists;
+    #   otherwise +nil+.
+    #
+    # Returns the _nth_ row of the table if that row exists:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.by_row! # => #<CSV::Table mode:row row_count:4>
+    #   table[1] # => #<CSV::Row "Name":"bar" "Value":"1">
+    #   table.by_col_or_row! # => #<CSV::Table mode:col_or_row row_count:4>
+    #   table[1] # => #<CSV::Row "Name":"bar" "Value":"1">
+    #
+    # Counts backward from the last row if +n+ is negative:
+    #   table[-1] # => #<CSV::Row "Name":"baz" "Value":"2">
+    #
+    # Returns +nil+ if +n+ is too large or too small:
+    #   table[4] # => nil
+    #   table[-4] # => nil
+    #
+    # Raises an exception if the access mode is <tt>:row</tt>
+    # and +n+ is not an \Integer:
+    #   table.by_row! # => #<CSV::Table mode:row row_count:4>
+    #   # Raises TypeError (no implicit conversion of String into Integer):
+    #   table['Name']
+    #
+    # ---
+    #
+    # Fetch a Column by Its \Integer Index::
+    # - Form: <tt>table[n]</tt>, +n+ an \Integer.
+    # - Access mode: <tt>:col</tt>.
+    # - Return value: _nth_ column of the table, if that column exists;
+    #   otherwise an \Array of +nil+ fields of length <tt>self.size</tt>.
+    #
+    # Returns the _nth_ column of the table if that column exists:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.by_col! # => #<CSV::Table mode:col row_count:4>
+    #   table[1] # => ["0", "1", "2"]
+    #
+    # Counts backward from the last column if +n+ is negative:
+    #   table[-2] # => ["foo", "bar", "baz"]
+    #
+    # Returns an \Array of +nil+ fields if +n+ is too large or too small:
+    #   table[4] # => [nil, nil, nil]
+    #   table[-4] # => [nil, nil, nil]
+    #
+    # ---
+    #
+    # Fetch Rows by \Range::
+    # - Form: <tt>table[range]</tt>, +range+ a \Range object.
+    # - Access mode: <tt>:row</tt> or <tt>:col_or_row</tt>.
+    # - Return value: rows from the table, beginning at row <tt>range.start</tt>,
+    #   if those rows exists.
+    #
+    # Returns rows from the table, beginning at row <tt>range.first</tt>,
+    # if those rows exist:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.by_row! # => #<CSV::Table mode:row row_count:4>
+    #   rows = table[1..2] # => #<CSV::Row "Name":"bar" "Value":"1">
+    #   rows # => [#<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"baz" "Value":"2">]
+    #   table.by_col_or_row! # => #<CSV::Table mode:col_or_row row_count:4>
+    #   rows = table[1..2] # => #<CSV::Row "Name":"bar" "Value":"1">
+    #   rows # => [#<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"baz" "Value":"2">]
+    #
+    # If there are too few rows, returns all from <tt>range.start</tt> to the end:
+    #   rows = table[1..50] # => #<CSV::Row "Name":"bar" "Value":"1">
+    #   rows # => [#<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"baz" "Value":"2">]
+    #
+    # Special case: if <tt>range.start == table.size</tt>, returns an empty \Array:
+    #   table[table.size..50] # => []
+    #
+    # If <tt>range.end</tt> is negative, calculates the ending index from the end:
+    #   rows = table[0..-1]
+    #   rows # => [#<CSV::Row "Name":"foo" "Value":"0">, #<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"baz" "Value":"2">]
+    #
+    # If <tt>range.start</tt> is negative, calculates the starting index from the end:
+    #   rows = table[-1..2]
+    #   rows # => [#<CSV::Row "Name":"baz" "Value":"2">]
+    #
+    # If <tt>range.start</tt> is larger than <tt>table.size</tt>, returns +nil+:
+    #   table[4..4] # => nil
+    #
+    # ---
+    #
+    # Fetch Columns by \Range::
+    # - Form: <tt>table[range]</tt>, +range+ a \Range object.
+    # - Access mode: <tt>:col</tt>.
+    # - Return value: column data from the table, beginning at column <tt>range.start</tt>,
+    #   if those columns exist.
+    #
+    # Returns column values from the table, if the column exists;
+    # the values are arranged by row:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.by_col!
+    #   table[0..1] # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+    #
+    # Special case: if <tt>range.start == headers.size</tt>,
+    # returns an \Array (size: <tt>table.size</tt>) of empty \Arrays:
+    #   table[table.headers.size..50] # => [[], [], []]
+    #
+    # If <tt>range.end</tt> is negative, calculates the ending index from the end:
+    #   table[0..-1] # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+    #
+    # If <tt>range.start</tt> is negative, calculates the starting index from the end:
+    #   table[-2..2] # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
     #
-    # 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!().
+    # If <tt>range.start</tt> is larger than <tt>table.size</tt>,
+    # returns an \Array of +nil+ values:
+    #   table[4..4] # => [nil, nil, nil]
     #
-    # Columns are returned as an Array of values.  Altering that Array has no
-    # effect on the table.
+    # ---
+    #
+    # Fetch a Column by Its \String Header::
+    # - Form: <tt>table[header]</tt>, +header+ a \String header.
+    # - Access mode: <tt>:col</tt> or <tt>:col_or_row</tt>
+    # - Return value: column data from the table, if that +header+ exists.
+    #
+    # Returns column values from the table, if the column exists:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.by_col! # => #<CSV::Table mode:col row_count:4>
+    #   table['Name'] # => ["foo", "bar", "baz"]
+    #   table.by_col_or_row! # => #<CSV::Table mode:col_or_row row_count:4>
+    #   col = table['Name']
+    #   col # => ["foo", "bar", "baz"]
     #
+    # Modifying the returned column values does not modify the table:
+    #   col[0] = 'bat'
+    #   col # => ["bat", "bar", "baz"]
+    #   table['Name'] # => ["foo", "bar", "baz"]
+    #
+    # Returns an \Array of +nil+ values if there is no such column:
+    #   table['Nosuch'] # => [nil, nil, nil]
     def [](index_or_header)
       if @mode == :row or  # by index
          (@mode == :col_or_row and (index_or_header.is_a?(Integer) or index_or_header.is_a?(Range)))
@@ -382,22 +520,132 @@ class CSV
       end
     end
 
+    # :call-seq:
+    #   table[n] = row -> row
+    #   table[n] = field_or_array_of_fields -> field_or_array_of_fields
+    #   table[header] = field_or_array_of_fields -> field_or_array_of_fields
+    #
+    # Puts data onto the table.
+    #
+    # ---
+    #
+    # Set a \Row by Its \Integer Index::
+    # - Form: <tt>table[n] = row</tt>, +n+ an \Integer,
+    #   +row+ a \CSV::Row instance or an \Array of fields.
+    # - Access mode: <tt>:row</tt> or <tt>:col_or_row</tt>.
+    # - Return value: +row+.
+    #
+    # If the row exists, it is replaced:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   new_row = CSV::Row.new(['Name', 'Value'], ['bat', 3])
+    #   table.by_row! # => #<CSV::Table mode:row row_count:4>
+    #   return_value = table[0] = new_row
+    #   return_value.equal?(new_row) # => true # Returned the row
+    #   table[0].to_h # => {"Name"=>"bat", "Value"=>3}
     #
-    # 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!().
+    # With access mode <tt>:col_or_row</tt>:
+    #   table.by_col_or_row! # => #<CSV::Table mode:col_or_row row_count:4>
+    #   table[0] = CSV::Row.new(['Name', 'Value'], ['bam', 4])
+    #   table[0].to_h # => {"Name"=>"bam", "Value"=>4}
+    #
+    # With an \Array instead of a \CSV::Row, inherits headers from the table:
+    #   array = ['bad', 5]
+    #   return_value = table[0] = array
+    #   return_value.equal?(array) # => true # Returned the array
+    #   table[0].to_h # => {"Name"=>"bad", "Value"=>5}
+    #
+    # If the row does not exist, extends the table by adding rows:
+    # assigns rows with +nil+ as needed:
+    #   table.size # => 3
+    #   table[5] = ['bag', 6]
+    #   table.size # => 6
+    #   table[3] # => nil
+    #   table[4]# => nil
+    #   table[5].to_h # => {"Name"=>"bag", "Value"=>6}
+    #
+    # Note that the +nil+ rows are actually +nil+, not a row of +nil+ fields.
+    #
+    # ---
+    #
+    # Set a Column by Its \Integer Index::
+    # - Form: <tt>table[n] = array_of_fields</tt>, +n+ an \Integer,
+    #   +array_of_fields+ an \Array of \String fields.
+    # - Access mode: <tt>:col</tt>.
+    # - Return value: +array_of_fields+.
+    #
+    # If the column exists, it is replaced:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   new_col = [3, 4, 5]
+    #   table.by_col! # => #<CSV::Table mode:col row_count:4>
+    #   return_value = table[1] = new_col
+    #   return_value.equal?(new_col) # => true # Returned the column
+    #   table[1] # => [3, 4, 5]
+    #   # The rows, as revised:
+    #   table.by_row! # => #<CSV::Table mode:row row_count:4>
+    #   table[0].to_h # => {"Name"=>"foo", "Value"=>3}
+    #   table[1].to_h # => {"Name"=>"bar", "Value"=>4}
+    #   table[2].to_h # => {"Name"=>"baz", "Value"=>5}
+    #   table.by_col! # => #<CSV::Table mode:col row_count:4>
+    #
+    # If there are too few values, fills with +nil+ values:
+    #   table[1] = [0]
+    #   table[1] # => [0, nil, nil]
+    #
+    # If there are too many values, ignores the extra values:
+    #   table[1] = [0, 1, 2, 3, 4]
+    #   table[1] # => [0, 1, 2]
+    #
+    # If a single value is given, replaces all fields in the column with that value:
+    #   table[1] = 'bat'
+    #   table[1] # => ["bat", "bat", "bat"]
+    #
+    # ---
+    #
+    # Set a Column by Its \String Header::
+    # - Form: <tt>table[header] = field_or_array_of_fields</tt>,
+    #   +header+ a \String header, +field_or_array_of_fields+ a field value
+    #   or an \Array of \String fields.
+    # - Access mode: <tt>:col</tt> or <tt>:col_or_row</tt>.
+    # - Return value: +field_or_array_of_fields+.
+    #
+    # If the column exists, it is replaced:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   new_col = [3, 4, 5]
+    #   table.by_col! # => #<CSV::Table mode:col row_count:4>
+    #   return_value = table['Value'] = new_col
+    #   return_value.equal?(new_col) # => true # Returned the column
+    #   table['Value'] # => [3, 4, 5]
+    #   # The rows, as revised:
+    #   table.by_row! # => #<CSV::Table mode:row row_count:4>
+    #   table[0].to_h # => {"Name"=>"foo", "Value"=>3}
+    #   table[1].to_h # => {"Name"=>"bar", "Value"=>4}
+    #   table[2].to_h # => {"Name"=>"baz", "Value"=>5}
+    #   table.by_col! # => #<CSV::Table mode:col row_count:4>
     #
-    # Rows may be set to an Array of values (which will inherit the table's
-    # headers()) or a CSV::Row.
+    # If there are too few values, fills with +nil+ values:
+    #   table['Value'] = [0]
+    #   table['Value'] # => [0, nil, nil]
     #
-    # 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+.
+    # If there are too many values, ignores the extra values:
+    #   table['Value'] = [0, 1, 2, 3, 4]
+    #   table['Value'] # => [0, 1, 2]
     #
-    # Assigning to an existing column or row clobbers the data. Assigning to
-    # new columns creates them at the right end of the table.
+    # If the column does not exist, extends the table by adding columns:
+    #   table['Note'] = ['x', 'y', 'z']
+    #   table['Note'] # => ["x", "y", "z"]
+    #   # The rows, as revised:
+    #   table.by_row!
+    #   table[0].to_h # => {"Name"=>"foo", "Value"=>0, "Note"=>"x"}
+    #   table[1].to_h # => {"Name"=>"bar", "Value"=>1, "Note"=>"y"}
+    #   table[2].to_h # => {"Name"=>"baz", "Value"=>2, "Note"=>"z"}
+    #   table.by_col!
     #
+    # If a single value is given, replaces all fields in the column with that value:
+    #   table['Value'] = 'bat'
+    #   table['Value'] # => ["bat", "bat", "bat"]
     def []=(index_or_header, value)
       if @mode == :row or  # by index
          (@mode == :col_or_row and index_or_header.is_a? Integer)
@@ -431,15 +679,58 @@ class CSV
       end
     end
 
+    # :call-seq:
+    #   table.values_at(*indexes) -> array_of_rows
+    #   table.values_at(*headers) -> array_of_columns_data
+    #
+    # If the access mode is <tt>:row</tt> or <tt>:col_or_row</tt>,
+    # and each argument is either an \Integer or a \Range,
+    # returns rows.
+    # Otherwise, returns columns data.
+    #
+    # In either case, the returned values are in the order
+    # specified by the arguments.  Arguments may be repeated.
     #
-    # 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!().
+    # ---
+    #
+    # Returns rows as an \Array of \CSV::Row objects.
+    #
+    # No argument:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.values_at # => []
     #
-    # You cannot mix column and row access.
+    # One index:
+    #   values = table.values_at(0)
+    #   values # => [#<CSV::Row "Name":"foo" "Value":"0">]
     #
+    # Two indexes:
+    #   values = table.values_at(2, 0)
+    #   values # => [#<CSV::Row "Name":"baz" "Value":"2">, #<CSV::Row "Name":"foo" "Value":"0">]
+    #
+    # One \Range:
+    #   values = table.values_at(1..2)
+    #   values # => [#<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"baz" "Value":"2">]
+    #
+    # \Ranges and indexes:
+    #   values = table.values_at(0..1, 1..2, 0, 2)
+    #   pp values
+    # Output:
+    #   [#<CSV::Row "Name":"foo" "Value":"0">,
+    #    #<CSV::Row "Name":"bar" "Value":"1">,
+    #    #<CSV::Row "Name":"bar" "Value":"1">,
+    #    #<CSV::Row "Name":"baz" "Value":"2">,
+    #    #<CSV::Row "Name":"foo" "Value":"0">,
+    #    #<CSV::Row "Name":"baz" "Value":"2">]
+    #
+    # ---
+    #
+    # Returns columns data as row Arrays,
+    # each consisting of the specified columns data for that row:
+    #   values = table.values_at('Name')
+    #   values # => [["foo"], ["bar"], ["baz"]]
+    #   values = table.values_at('Value', 'Name')
+    #   values # => [["0", "foo"], ["1", "bar"], ["2", "baz"]]
     def values_at(*indices_or_headers)
       if @mode == :row or  # by indices
          ( @mode == :col_or_row and indices_or_headers.all? do |index|
@@ -454,13 +745,20 @@ class CSV
       end
     end
 
+    # :call-seq:
+    #   table << row_or_array -> self
     #
-    # Adds a new row to the bottom end of this table. You can provide an Array,
-    # which will be converted to a CSV::Row (inheriting the table's headers()),
-    # or a CSV::Row.
-    #
-    # This method returns the table for chaining.
+    # If +row_or_array+ is a \CSV::Row object,
+    # it is appended to the table:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table << CSV::Row.new(table.headers, ['bat', 3])
+    #   table[3] # => #<CSV::Row "Name":"bat" "Value":3>
     #
+    # If +row_or_array+ is an \Array, it is used to create a new
+    # \CSV::Row object which is then appended to the table:
+    #   table << ['bam', 4]
+    #   table[4] # => #<CSV::Row "Name":"bam" "Value":4>
     def <<(row_or_array)
       if row_or_array.is_a? Array  # append Array
         @table << Row.new(headers, row_or_array)
@@ -472,23 +770,67 @@ class CSV
     end
 
     #
-    # A shortcut for appending multiple rows. Equivalent to:
-    #
-    #   rows.each { |row| self << row }
+    # :call-seq:
+    #   table.push(*rows_or_arrays) -> self
     #
-    # This method returns the table for chaining.
+    # A shortcut for appending multiple rows. Equivalent to:
+    #   rows.each {|row| self << row }
     #
+    # Each argument may be either a \CSV::Row object or an \Array:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   rows = [
+    #     CSV::Row.new(table.headers, ['bat', 3]),
+    #     ['bam', 4]
+    #   ]
+    #   table.push(*rows)
+    #   table[3..4] # => [#<CSV::Row "Name":"bat" "Value":3>, #<CSV::Row "Name":"bam" "Value":4>]
     def push(*rows)
       rows.each { |row| self << row }
 
       self # for chaining
     end
 
+    # :call-seq:
+    #   table.delete(*indexes) -> deleted_values
+    #   table.delete(*headers) -> deleted_values
+    #
+    # If the access mode is <tt>:row</tt> or <tt>:col_or_row</tt>,
+    # and each argument is either an \Integer or a \Range,
+    # returns deleted rows.
+    # Otherwise, returns deleted columns data.
+    #
+    # In either case, the returned values are in the order
+    # specified by the arguments.  Arguments may be repeated.
+    #
+    # ---
+    #
+    # Returns rows as an \Array of \CSV::Row objects.
+    #
+    # One index:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   deleted_values = table.delete(0)
+    #   deleted_values # => [#<CSV::Row "Name":"foo" "Value":"0">]
+    #
+    # Two indexes:
+    #   table = CSV.parse(source, headers: true)
+    #   deleted_values = table.delete(2, 0)
+    #   deleted_values # => [#<CSV::Row "Name":"baz" "Value":"2">, #<CSV::Row "Name":"foo" "Value":"0">]
+    #
+    # ---
     #
-    # Removes and returns the indicated columns or rows. In the default mixed
-    # mode indices refer to rows and everything else is assumed to be a column
-    # headers. Use by_col!() or by_row!() to force the lookup.
+    # Returns columns data as column Arrays.
+    #
+    # One header:
+    #   table = CSV.parse(source, headers: true)
+    #   deleted_values = table.delete('Name')
+    #   deleted_values # => ["foo", "bar", "baz"]
     #
+    # Two headers:
+    #   table = CSV.parse(source, headers: true)
+    #   deleted_values = table.delete('Value', 'Name')
+    #   deleted_values # => [["0", "1", "2"], ["foo", "bar", "baz"]]
     def delete(*indexes_or_headers)
       if indexes_or_headers.empty?
         raise ArgumentError, "wrong number of arguments (given 0, expected 1+)"
@@ -513,16 +855,35 @@ class CSV
       end
     end
 
+    # :call-seq:
+    #   table.delete_if {|row_or_column| ... } -> self
     #
-    # 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, iteration will +yield+ two element
-    # tuples containing the column name and an Array of values for that column.
+    # Removes rows or columns for which the block returns a truthy value;
+    # returns +self+.
     #
-    # This method returns the table for chaining.
+    # Removes rows when the access mode is <tt>:row</tt> or <tt>:col_or_row</tt>;
+    # calls the block with each \CSV::Row object:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.by_row! # => #<CSV::Table mode:row row_count:4>
+    #   table.size # => 3
+    #   table.delete_if {|row| row['Name'].start_with?('b') }
+    #   table.size # => 1
     #
-    # If no block is given, an Enumerator is returned.
+    # Removes columns when the access mode is <tt>:col</tt>;
+    # calls the block with each column as a 2-element array
+    # containing the header and an \Array of column fields:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.by_col! # => #<CSV::Table mode:col row_count:4>
+    #   table.headers.size # => 2
+    #   table.delete_if {|column_data| column_data[1].include?('2') }
+    #   table.headers.size # => 1
     #
+    # Returns a new \Enumerator if no block is given:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.delete_if # => #<Enumerator: #<CSV::Table mode:col_or_row row_count:4>:delete_if>
     def delete_if(&block)
       return enum_for(__method__) { @mode == :row or @mode == :col_or_row ? size : headers.size } unless block_given?
 
@@ -540,20 +901,40 @@ class CSV
 
     include Enumerable
 
+    # :call-seq:
+    #  table.each {|row_or_column| ... ) -> self
     #
-    # In the default mixed mode or row mode, iteration is the standard row major
-    # walking of rows. In column mode, iteration will +yield+ two element
-    # tuples containing the column name and an Array of values for that column.
+    # Calls the block with each row or column; returns +self+.
     #
-    # This method returns the table for chaining.
+    # When the access mode is <tt>:row</tt> or <tt>:col_or_row</tt>,
+    # calls the block with each \CSV::Row object:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.by_row! # => #<CSV::Table mode:row row_count:4>
+    #   table.each {|row| p row }
+    # Output:
+    #   #<CSV::Row "Name":"foo" "Value":"0">
+    #   #<CSV::Row "Name":"bar" "Value":"1">
+    #   #<CSV::Row "Name":"baz" "Value":"2">
     #
-    # If no block is given, an Enumerator is returned.
+    # When the access mode is <tt>:col</tt>,
+    # calls the block with each column as a 2-element array
+    # containing the header and an \Array of column fields:
+    #   table.by_col! # => #<CSV::Table mode:col row_count:4>
+    #   table.each {|column_data| p column_data }
+    # Output:
+    #   ["Name", ["foo", "bar", "baz"]]
+    #   ["Value", ["0", "1", "2"]]
     #
+    # Returns a new \Enumerator if no block is given:
+    #   table.each # => #<Enumerator: #<CSV::Table mode:col row_count:4>:each>
     def each(&block)
       return enum_for(__method__) { @mode == :col ? headers.size : size } unless block_given?
 
       if @mode == :col
-        headers.each { |header| yield([header, self[header]]) }
+        headers.each.with_index do |header, i|
+          yield([header, @table.map {|row| row[header, i]}])
+        end
       else
         @table.each(&block)
       end
@@ -561,16 +942,40 @@ class CSV
       self # for chaining
     end
 
-    # Returns +true+ if all rows of this table ==() +other+'s rows.
+    # :call-seq:
+    #   table == other_table -> true or false
+    #
+    # Returns +true+ if all each row of +self+ <tt>==</tt>
+    # the corresponding row of +other_table+, otherwise, +false+.
+    #
+    # The access mode does no affect the result.
+    #
+    # Equal tables:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   other_table = CSV.parse(source, headers: true)
+    #   table == other_table # => true
+    #
+    # Different row count:
+    #   other_table.delete(2)
+    #   table == other_table # => false
+    #
+    # Different last row:
+    #   other_table << ['bat', 3]
+    #   table == other_table # => false
     def ==(other)
       return @table == other.table if other.is_a? CSV::Table
       @table == other
     end
 
+    # :call-seq:
+    #   table.to_a -> array_of_arrays
     #
-    # Returns the table as an Array of Arrays. Headers will be the first row,
-    # then all of the field rows will follow.
-    #
+    # Returns the table as an \Array of \Arrays;
+    # the headers are in the first row:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.to_a # => [["Name", "Value"], ["foo", "0"], ["bar", "1"], ["baz", "2"]]
     def to_a
       array = [headers]
       @table.each do |row|
@@ -580,13 +985,20 @@ class CSV
       array
     end
 
+    # :call-seq:
+    #   table.to_csv(**options) -> csv_string
     #
-    # Returns the table as a complete CSV String. Headers will be listed first,
-    # then all of the field rows.
+    # Returns the table as \CSV string.
+    # See {Options for Generating}[../CSV.html#class-CSV-label-Options+for+Generating].
     #
-    # This method assumes you want the Table.headers(), unless you explicitly
-    # pass <tt>:write_headers => false</tt>.
+    # Defaults option +write_headers+ to +true+:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.to_csv # => "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
     #
+    # Omits the headers if option +write_headers+ is given as +false+
+    # (see {Option +write_headers+}[../CSV.html#class-CSV-label-Option+write_headers]):
+    #   table.to_csv(write_headers: false) # => "foo,0\nbar,1\nbaz,2\n"
     def to_csv(write_headers: true, **options)
       array = write_headers ? [headers.to_csv(**options)] : []
       @table.each do |row|
@@ -615,7 +1027,18 @@ class CSV
       end
     end
 
-    # Shows the mode and size of this table in a US-ASCII String.
+    # :call-seq:
+    #   table.inspect => string
+    #
+    # Returns a <tt>US-ASCII</tt>-encoded \String showing table:
+    # - Class: <tt>CSV::Table</tt>.
+    # - Access mode: <tt>:row</tt>, <tt>:col</tt>, or <tt>:col_or_row</tt>.
+    # - Size:  Row count, including the header row.
+    #
+    # Example:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.inspect # => "#<CSV::Table mode:col_or_row row_count:4>"
     def inspect
       "#<#{self.class} mode:#{@mode} row_count:#{to_a.size}>".encode("US-ASCII")
     end