csv 3.1.6 → 3.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 684d334d79d666022640de8b3bfa8d2e6fa879cb0c9e59349e9adf8307147fa0
-  data.tar.gz: 6298def337c705d19acb6d1da52560aa53f0dfeba5660202d8fc0259418d96a1
+  metadata.gz: c834580f6d364830ddcd85b07edcb44fc91520fd594492a835cb57f43f145c94
+  data.tar.gz: 989310760b22148eeb70be9181a39c2d08c8040f7e79fd6a06dc7586409c4e7f
 SHA512:
-  metadata.gz: 42349aa586b53f75c75ea29a5388889c21645b24e1ad8ac8e1752697f94dc9e7564b62f36b2b6219516f34c1a27bbf581566f3f2dafef556f9783b907e932d04
-  data.tar.gz: 69319007e9a35acb7659d73b5c9a38256a572a5a21ef59365b8f4fd0fee9d06c2c0c89ae346bf701e6c0af430fc99868c625323cc75f620340eb80006ce0d036
+  metadata.gz: 75859dd4eff126ab15bf372305da6eeb638ce1927186931f3ea87fe00c0a769c8adb38cb786b8ee3f7fd418de720d26fe01fba9ca28ac565bbd761431057cec8
+  data.tar.gz: 56b5de70961f3e9792296e6b68941fa1ea1e1eaa5ad2811ae47954a775c986d8f9455af50e5e6d25deb797794b697cef0e0c4a87695dc3a42d9fa477008d85dc

data/NEWS.md

@@ -1,5 +1,25 @@
 # News
 
+## 3.1.7 - 2020-08-04
+
+### Improvements
+
+  * Improved document.
+    [GitHub#158][GitHub#160][GitHub#161]
+    [Patch by Burdette Lamar]
+
+  * Updated required Ruby version to 2.5.0 or later.
+    [GitHub#159]
+    [Patch by Gabriel Nagy]
+
+  * Removed stringio 0.1.3 or later dependency.
+
+### Thanks
+
+  * Burdette Lamar
+
+  * Gabriel Nagy
+
 ## 3.1.6 - 2020-07-20
 
 ### Improvements

data/lib/csv.rb

@@ -104,7 +104,7 @@ require_relative "csv/writer"
 using CSV::MatchP if CSV.const_defined?(:MatchP)
 
 # == \CSV
-# \CSV (comma-separated variables) data is a text representation of a table:
+# \CSV (comma-separated values) data is a text representation of a table:
 # - A _row_ _separator_ delimits table rows.
 #   A common row separator is the newline character <tt>"\n"</tt>.
 # - A _column_ _separator_ delimits fields in a row.
@@ -357,35 +357,35 @@ using CSV::MatchP if CSV.const_defined?(:MatchP)
 # - +nil_value+: Specifies the object that is to be substituted for each null (no-text) field.
 # - +empty_value+: Specifies the object that is to be substituted for each empty field.
 #
-# :include: ../doc/options/common/row_sep.rdoc
+# :include: ../doc/csv/options/common/row_sep.rdoc
 #
-# :include: ../doc/options/common/col_sep.rdoc
+# :include: ../doc/csv/options/common/col_sep.rdoc
 #
-# :include: ../doc/options/common/quote_char.rdoc
+# :include: ../doc/csv/options/common/quote_char.rdoc
 #
-# :include: ../doc/options/parsing/field_size_limit.rdoc
+# :include: ../doc/csv/options/parsing/field_size_limit.rdoc
 #
-# :include: ../doc/options/parsing/converters.rdoc
+# :include: ../doc/csv/options/parsing/converters.rdoc
 #
-# :include: ../doc/options/parsing/unconverted_fields.rdoc
+# :include: ../doc/csv/options/parsing/unconverted_fields.rdoc
 #
-# :include: ../doc/options/parsing/headers.rdoc
+# :include: ../doc/csv/options/parsing/headers.rdoc
 #
-# :include: ../doc/options/parsing/return_headers.rdoc
+# :include: ../doc/csv/options/parsing/return_headers.rdoc
 #
-# :include: ../doc/options/parsing/header_converters.rdoc
+# :include: ../doc/csv/options/parsing/header_converters.rdoc
 #
-# :include: ../doc/options/parsing/skip_blanks.rdoc
+# :include: ../doc/csv/options/parsing/skip_blanks.rdoc
 #
-# :include: ../doc/options/parsing/skip_lines.rdoc
+# :include: ../doc/csv/options/parsing/skip_lines.rdoc
 #
-# :include: ../doc/options/parsing/strip.rdoc
+# :include: ../doc/csv/options/parsing/strip.rdoc
 #
-# :include: ../doc/options/parsing/liberal_parsing.rdoc
+# :include: ../doc/csv/options/parsing/liberal_parsing.rdoc
 #
-# :include: ../doc/options/parsing/nil_value.rdoc
+# :include: ../doc/csv/options/parsing/nil_value.rdoc
 #
-# :include: ../doc/options/parsing/empty_value.rdoc
+# :include: ../doc/csv/options/parsing/empty_value.rdoc
 #
 # ==== Options for Generating
 #
@@ -400,23 +400,23 @@ using CSV::MatchP if CSV.const_defined?(:MatchP)
 # - +write_nil_value+: Specifies the object that is to be substituted for each +nil+-valued field.
 # - +write_empty_value+: Specifies the object that is to be substituted for each empty field.
 #
-# :include: ../doc/options/common/row_sep.rdoc
+# :include: ../doc/csv/options/common/row_sep.rdoc
 #
-# :include: ../doc/options/common/col_sep.rdoc
+# :include: ../doc/csv/options/common/col_sep.rdoc
 #
-# :include: ../doc/options/common/quote_char.rdoc
+# :include: ../doc/csv/options/common/quote_char.rdoc
 #
-# :include: ../doc/options/generating/write_headers.rdoc
+# :include: ../doc/csv/options/generating/write_headers.rdoc
 #
-# :include: ../doc/options/generating/force_quotes.rdoc
+# :include: ../doc/csv/options/generating/force_quotes.rdoc
 #
-# :include: ../doc/options/generating/quote_empty.rdoc
+# :include: ../doc/csv/options/generating/quote_empty.rdoc
 #
-# :include: ../doc/options/generating/write_converters.rdoc
+# :include: ../doc/csv/options/generating/write_converters.rdoc
 #
-# :include: ../doc/options/generating/write_nil_value.rdoc
+# :include: ../doc/csv/options/generating/write_nil_value.rdoc
 #
-# :include: ../doc/options/generating/write_empty_value.rdoc
+# :include: ../doc/csv/options/generating/write_empty_value.rdoc
 #
 # === \CSV with Headers
 #
@@ -1075,7 +1075,7 @@ class CSV
     # Calls the block with each row read from source +path+ or +io+.
     #
     # * Argument +path+, if given, must be the path to a file.
-    # :include: ../doc/arguments/io.rdoc
+    # :include: ../doc/csv/arguments/io.rdoc
     # * Argument +mode+, if given, must be a \File mode
     #   See {Open Mode}[IO.html#method-c-new-label-Open+Mode].
     # * Arguments <tt>**options</tt> must be keyword options.
@@ -1322,7 +1322,7 @@ class CSV
     #     :replace => string   # replacement string ("?" or "\uFFFD" if not specified)
     #
     # * Argument +path+, if given, must be the path to a file.
-    # :include: ../doc/arguments/io.rdoc
+    # :include: ../doc/csv/arguments/io.rdoc
     # * Argument +mode+, if given, must be a \File mode
     #   See {Open Mode}[IO.html#method-c-new-label-Open+Mode].
     # * Arguments <tt>**options</tt> must be keyword options.
@@ -1427,7 +1427,7 @@ class CSV
     #
     # - Argument +string+ should be a \String object;
     #   it will be put into a new StringIO object positioned at the beginning.
-    # :include: ../doc/arguments/io.rdoc
+    # :include: ../doc/csv/arguments/io.rdoc
     # - Argument +options+: see {Options for Parsing}[#class-CSV-label-Options+for+Parsing]
     #
     # ====== Without Option +headers+
@@ -1552,7 +1552,7 @@ class CSV
     #
     # - Argument +string+ should be a \String object;
     #   it will be put into a new StringIO object positioned at the beginning.
-    # :include: ../doc/arguments/io.rdoc
+    # :include: ../doc/csv/arguments/io.rdoc
     # - Argument +options+: see {Options for Parsing}[#class-CSV-label-Options+for+Parsing]
     #
     # ====== Without Option +headers+
@@ -1672,7 +1672,7 @@ class CSV
   #
   # - Argument +string+ should be a \String object;
   #   it will be put into a new StringIO object positioned at the beginning.
-  # :include: ../doc/arguments/io.rdoc
+  # :include: ../doc/csv/arguments/io.rdoc
   # - Argument +options+: See:
   #   * {Options for Parsing}[#class-CSV-label-Options+for+Parsing]
   #   * {Options for Generating}[#class-CSV-label-Options+for+Generating]
@@ -2080,7 +2080,7 @@ class CSV
   ### End Delegation ###
 
   # :call-seq:
-  #   csv.<< row
+  #   csv << row -> self
   #
   # Appends a row to +self+.
   #
@@ -2120,7 +2120,7 @@ class CSV
   #     csv << :foo
   #   end
   #
-  # Raises an exception if the output stream is not open for writing:
+  # Raises an exception if the output stream is not opened for writing:
   #   path = 't.csv'
   #   File.write(path, '')
   #   File.open(path) do |file|
@@ -2272,25 +2272,57 @@ class CSV
 
   include Enumerable
 
+  # :call-seq:
+  #   csv.each -> enumerator
+  #   csv.each {|row| ...}
   #
-  # Yields each row of the data source in turn.
+  # Calls the block with each successive row.
+  # The data source must be opened for reading.
   #
-  # Support for Enumerable.
+  # Without headers:
+  #   string = "foo,0\nbar,1\nbaz,2\n"
+  #   csv = CSV.new(string)
+  #   csv.each do |row|
+  #     p row
+  #   end
+  # Output:
+  #   ["foo", "0"]
+  #   ["bar", "1"]
+  #   ["baz", "2"]
   #
-  # The data source must be open for reading.
+  # With headers:
+  #   string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #   csv = CSV.new(string, headers: true)
+  #   csv.each do |row|
+  #     p row
+  #   end
+  # Output:
+  #   <CSV::Row "Name":"foo" "Value":"0">
+  #   <CSV::Row "Name":"bar" "Value":"1">
+  #   <CSV::Row "Name":"baz" "Value":"2">
+  #
+  # ---
   #
+  # Raises an exception if the source is not opened for reading:
+  #   string = "foo,0\nbar,1\nbaz,2\n"
+  #   csv = CSV.new(string)
+  #   csv.close
+  #   # Raises IOError (not opened for reading)
+  #   csv.each do |row|
+  #     p row
+  #   end
   def each(&block)
     parser_enumerator.each(&block)
   end
 
   # :call-seq:
-  #     read
+  #   csv.read -> array or csv_table
   #
   # Forms the remaining rows from +self+ into:
   # - A CSV::Table object, if headers are in use.
-  # - An Array of Arrays, otherwise.
+  # - An \Array of Arrays, otherwise.
   #
-  # The data source must be open for reading.
+  # The data source must be opened for reading.
   #
   # Without headers:
   #   string = "foo,0\nbar,1\nbaz,2\n"
@@ -2305,6 +2337,15 @@ class CSV
   #   File.write(path, string)
   #   csv = CSV.open(path, headers: true)
   #   csv.read # => #<CSV::Table mode:col_or_row row_count:4>
+  #
+  # ---
+  #
+  # Raises an exception if the source is not opened for reading:
+  #   string = "foo,0\nbar,1\nbaz,2\n"
+  #   csv = CSV.new(string)
+  #   csv.close
+  #   # Raises IOError (not opened for reading)
+  #   csv.read
   def read
     rows = to_a
     if parser.use_headers?
@@ -2315,18 +2356,69 @@ class CSV
   end
   alias_method :readlines, :read
 
-  # Returns +true+ if the next row read will be a header row.
+  # :call-seq:
+  #   csv.header_row? -> true or false
+  #
+  # Returns +true+ if the next row to be read is a header row\;
+  # +false+ otherwise.
+  #
+  # Without headers:
+  #   string = "foo,0\nbar,1\nbaz,2\n"
+  #   csv = CSV.new(string)
+  #   csv.header_row? # => false
+  #
+  # With headers:
+  #   string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #   csv = CSV.new(string, headers: true)
+  #   csv.header_row? # => true
+  #   csv.shift # => #<CSV::Row "Name":"foo" "Value":"0">
+  #   csv.header_row? # => false
+  #
+  # ---
+  #
+  # Raises an exception if the source is not opened for reading:
+  #   string = "foo,0\nbar,1\nbaz,2\n"
+  #   csv = CSV.new(string)
+  #   csv.close
+  #   # Raises IOError (not opened for reading)
+  #   csv.header_row?
   def header_row?
     parser.header_row?
   end
 
+  # :call-seq:
+  #   csv.shift -> array, csv_row, or nil
   #
-  # The primary read method for wrapped Strings and IOs, a single row is pulled
-  # from the data source, parsed and returned as an Array of fields (if header
-  # rows are not used) or a CSV::Row (when header rows are used).
+  # Returns the next row of data as:
+  # - An \Array if no headers are used.
+  # - A CSV::Row object if headers are used.
   #
-  # The data source must be open for reading.
+  # The data source must be opened for reading.
   #
+  # Without headers:
+  #   string = "foo,0\nbar,1\nbaz,2\n"
+  #   csv = CSV.new(string)
+  #   csv.shift # => ["foo", "0"]
+  #   csv.shift # => ["bar", "1"]
+  #   csv.shift # => ["baz", "2"]
+  #   csv.shift # => nil
+  #
+  # With headers:
+  #   string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #   csv = CSV.new(string, headers: true)
+  #   csv.shift # => #<CSV::Row "Name":"foo" "Value":"0">
+  #   csv.shift # => #<CSV::Row "Name":"bar" "Value":"1">
+  #   csv.shift # => #<CSV::Row "Name":"baz" "Value":"2">
+  #   csv.shift # => nil
+  #
+  # ---
+  #
+  # Raises an exception if the source is not opened for reading:
+  #   string = "foo,0\nbar,1\nbaz,2\n"
+  #   csv = CSV.new(string)
+  #   csv.close
+  #   # Raises IOError (not opened for reading)
+  #   csv.shift
   def shift
     if @eof_error
       eof_error, @eof_error = @eof_error, nil
@@ -2341,10 +2433,14 @@ class CSV
   alias_method :gets,     :shift
   alias_method :readline, :shift
 
+  # :call-seq:
+  #   csv.inspect -> string
   #
-  # Returns a simplified description of the key CSV attributes in an
-  # ASCII compatible String.
-  #
+  # Returns a \String showing certain properties of +self+:
+  #   string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #   csv = CSV.new(string, headers: true)
+  #   s = csv.inspect
+  #   s # => "#<CSV io_type:StringIO encoding:UTF-8 lineno:0 col_sep:\",\" row_sep:\"\\n\" quote_char:\"\\\"\" headers:true>"
   def inspect
     str = ["#<", self.class.to_s, " io_type:"]
     # show type of wrapped IO

data/lib/csv/table.rb

@@ -3,31 +3,199 @@
 require "forwardable"
 
 class CSV
+  # = \CSV::Table
+  # A \CSV::Table instance is an object representing \CSV data.
+  # (see {class CSV}[../CSV.html]).
   #
-  # A CSV::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.
+  # The instance may have:
+  # - Rows:  each is a Table::Row object.
+  # - Headers:  names for the columns.
   #
-  # All tables returned by CSV will be constructed from this class, if header
-  # row processing is activated.
+  # === Instance Methods
   #
+  # \CSV::Table has three groups of instance methods:
+  # - Its own internally defined instance methods.
+  # - Methods included by module Enumerable.
+  # - Methods delegated to class Array.:
+  #   * Array#empty?
+  #   * Array#length
+  #   * Array#size
+  #
+  # == Creating a \CSV::Table Instance
+  #
+  # Commonly, a new \CSV::Table instance is created by parsing \CSV source
+  # using headers:
+  #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #   table = CSV.parse(source, headers: true)
+  #   table.class # => CSV::Table
+  #
+  # You can also create an instance directly. See ::new.
+  #
+  # == Headers
+  #
+  # If a table has headers, the headers serve as labels for the columns of data.
+  # Each header serves as the label for its column.
+  #
+  # The headers for a \CSV::Table object are stored as an \Array of Strings.
+  #
+  # Commonly, headers are defined in the first row of \CSV source:
+  #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #   table = CSV.parse(source, headers: true)
+  #   table.headers # => ["Name", "Value"]
+  #
+  # If no headers are defined, the \Array is empty:
+  #   table = CSV::Table.new([])
+  #   table.headers # => []
+  #
+  # == Access Modes
+  #
+  # \CSV::Table provides three modes for accessing table data:
+  # - \Row mode.
+  # - Column mode.
+  # - Mixed mode (the default for a new table).
+  #
+  # The access mode for a\CSV::Table instance affects the behavior
+  # of some of its instance methods:
+  # - #[]
+  # - #[]=
+  # - #delete
+  # - #delete_if
+  # - #each
+  # - #values_at
+  #
+  # === \Row Mode
+  #
+  # Set a table to row mode with method #by_row!:
+  #   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>
+  #
+  # Specify a single row by an \Integer index:
+  #   # Get a row.
+  #   table[1] # => #<CSV::Row "Name":"bar" "Value":"1">
+  #   # Set a row, then get it.
+  #   table[1] = CSV::Row.new(['Name', 'Value'], ['bam', 3])
+  #   table[1] # => #<CSV::Row "Name":"bam" "Value":3>
+  #
+  # Specify a sequence of rows by a \Range:
+  #   # Get rows.
+  #   table[1..2] # => [#<CSV::Row "Name":"bam" "Value":3>, #<CSV::Row "Name":"baz" "Value":"2">]
+  #   # Set rows, then get them.
+  #   table[1..2] = [
+  #     CSV::Row.new(['Name', 'Value'], ['bat', 4]),
+  #     CSV::Row.new(['Name', 'Value'], ['bad', 5]),
+  #   ]
+  #   table[1..2] # => [["Name", #<CSV::Row "Name":"bat" "Value":4>], ["Value", #<CSV::Row "Name":"bad" "Value":5>]]
+  #
+  # === Column Mode
+  #
+  # Set a table to column mode with method #by_col!:
+  #   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>
+  #
+  # Specify a column by an \Integer index:
+  #   # Get a column.
+  #   table[0]
+  #   # Set a column, then get it.
+  #   table[0] = ['FOO', 'BAR', 'BAZ']
+  #   table[0] # => ["FOO", "BAR", "BAZ"]
+  #
+  # Specify a column by its \String header:
+  #   # Get a column.
+  #   table['Name'] # => ["FOO", "BAR", "BAZ"]
+  #   # Set a column, then get it.
+  #   table['Name'] = ['Foo', 'Bar', 'Baz']
+  #   table['Name'] # => ["Foo", "Bar", "Baz"]
+  #
+  # === Mixed Mode
+  #
+  # In mixed mode, you can refer to either rows or columns:
+  # - An \Integer index refers to a row.
+  # - A \Range index refers to multiple rows.
+  # - A \String index refers to a column.
+  #
+  # Set a table to mixed mode with method #by_col_or_row!:
+  #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #   table = CSV.parse(source, headers: true)
+  #   table.by_col_or_row! # => #<CSV::Table mode:col_or_row row_count:4>
+  #
+  # Specify a single row by an \Integer index:
+  #   # Get a row.
+  #   table[1] # => #<CSV::Row "Name":"bar" "Value":"1">
+  #   # Set a row, then get it.
+  #   table[1] = CSV::Row.new(['Name', 'Value'], ['bam', 3])
+  #   table[1] # => #<CSV::Row "Name":"bam" "Value":3>
+  #
+  # Specify a sequence of rows by a \Range:
+  #   # Get rows.
+  #   table[1..2] # => [#<CSV::Row "Name":"bam" "Value":3>, #<CSV::Row "Name":"baz" "Value":"2">]
+  #   # Set rows, then get them.
+  #   table[1] = CSV::Row.new(['Name', 'Value'], ['bat', 4])
+  #   table[2] = CSV::Row.new(['Name', 'Value'], ['bad', 5])
+  #   table[1..2] # => [["Name", #<CSV::Row "Name":"bat" "Value":4>], ["Value", #<CSV::Row "Name":"bad" "Value":5>]]
+  #
+  # Specify a column by its \String header:
+  #   # Get a column.
+  #   table['Name'] # => ["foo", "bat", "bad"]
+  #   # Set a column, then get it.
+  #   table['Name'] = ['Foo', 'Bar', 'Baz']
+  #   table['Name'] # => ["Foo", "Bar", "Baz"]
   class Table
-    #
-    # Constructs a new CSV::Table from +array_of_rows+, which are expected
-    # to be CSV::Row objects. All rows are assumed to have the same headers.
-    #
-    # The optional +headers+ parameter can be set to Array of headers.
-    # If headers aren't set, headers are fetched from CSV::Row objects.
-    # Otherwise, headers() method will return headers being set in
-    # headers argument.
-    #
-    # A CSV::Table object supports the following Array methods through
-    # delegation:
-    #
-    # * empty?()
-    # * length()
-    # * size()
-    #
+    # :call-seq:
+    #   CSV::Table.new(array_of_rows, headers = nil)
+    #
+    # Returns a new \CSV::Table object.
+    #
+    # - Argument +array_of_rows+ must be an \Array of CSV::Row objects.
+    # - Argument +headers+, if given, may be an \Array of Strings.
+    #
+    # ---
+    #
+    # Create an empty \CSV::Table object:
+    #   table = CSV::Table.new([])
+    #   table # => #<CSV::Table mode:col_or_row row_count:1>
+    #
+    # Create a non-empty \CSV::Table object:
+    #   rows = [
+    #     CSV::Row.new([], []),
+    #     CSV::Row.new([], []),
+    #     CSV::Row.new([], []),
+    #   ]
+    #   table  = CSV::Table.new(rows)
+    #   table # => #<CSV::Table mode:col_or_row row_count:4>
+    #
+    # ---
+    #
+    # If argument +headers+ is an \Array of Strings,
+    # those Strings become the table's headers:
+    #   table = CSV::Table.new([], headers: ['Name', 'Age'])
+    #   table.headers # => ["Name", "Age"]
+    #
+    # If argument +headers+ is not given and the table has rows,
+    # the headers are taken from the first row:
+    #   rows = [
+    #     CSV::Row.new(['Foo', 'Bar'], []),
+    #     CSV::Row.new(['foo', 'bar'], []),
+    #     CSV::Row.new(['FOO', 'BAR'], []),
+    #   ]
+    #   table  = CSV::Table.new(rows)
+    #   table.headers # => ["Foo", "Bar"]
+    #
+    # If argument +headers+ is not given and the table is empty (has no rows),
+    # the headers are also empty:
+    #   table  = CSV::Table.new([])
+    #   table.headers # => []
+    #
+    # ---
+    #
+    # Raises an exception if argument +array_of_rows+ is not an \Array object:
+    #   # Raises NoMethodError (undefined method `first' for :foo:Symbol):
+    #   CSV::Table.new(:foo)
+    #
+    # Raises an exception if an element of +array_of_rows+ is not a \CSV::Table object:
+    #   # Raises NoMethodError (undefined method `headers' for :foo:Symbol):
+    #   CSV::Table.new([:foo])
     def initialize(array_of_rows, headers: nil)
       @table = array_of_rows
       @headers = headers
@@ -54,88 +222,141 @@ class CSV
     extend Forwardable
     def_delegators :@table, :empty?, :length, :size
 
+    # :call-seq:
+    #   table.by_col
     #
-    # 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.
+    # Returns a duplicate of +self+, in column mode
+    # (see {Column Mode}[#class-CSV::Table-label-Column+Mode]):
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.mode # => :col_or_row
+    #   dup_table = table.by_col
+    #   dup_table.mode # => :col
+    #   dup_table.equal?(table) # => false # It's a dup
     #
-    # This method returns the duplicate table for chaining. Don't chain
-    # destructive methods (like []=()) this way though, since you are working
-    # with a duplicate.
+    # This may be used to chain method calls without changing the mode
+    # (but also will affect performance and memory usage):
+    #   dup_table.by_col['Name']
     #
+    # Also note that changes to the duplicate table will not affect the original.
     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.
-    #
+    # :call-seq:
+    #   table.by_col!
+    #
+    # Sets the mode for +self+ to column mode
+    # (see {Column Mode}[#class-CSV::Table-label-Column+Mode]); returns +self+:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.mode # => :col_or_row
+    #   table1 = table.by_col!
+    #   table.mode # => :col
+    #   table1.equal?(table) # => true # Returned self
     def by_col!
       @mode = :col
 
       self
     end
 
+    # :call-seq:
+    #   table.by_col_or_row
     #
-    # 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.
+    # Returns a duplicate of +self+, in mixed mode
+    # (see {Mixed Mode}[#class-CSV::Table-label-Mixed+Mode]):
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true).by_col!
+    #   table.mode # => :col
+    #   dup_table = table.by_col_or_row
+    #   dup_table.mode # => :col_or_row
+    #   dup_table.equal?(table) # => false # It's a dup
     #
-    # This method returns the duplicate table for chaining.  Don't chain
-    # destructive methods (like []=()) this way though, since you are working
-    # with a duplicate.
+    # This may be used to chain method calls without changing the mode
+    # (but also will affect performance and memory usage):
+    #   dup_table.by_col_or_row['Name']
     #
+    # Also note that changes to the duplicate table will not affect the original.
     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.
-    #
+    # :call-seq:
+    #   table.by_col_or_row!
+    #
+    # Sets the mode for +self+ to mixed mode
+    # (see {Mixed Mode}[#class-CSV::Table-label-Mixed+Mode]); returns +self+:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true).by_col!
+    #   table.mode # => :col
+    #   table1 = table.by_col_or_row!
+    #   table.mode # => :col_or_row
+    #   table1.equal?(table) # => true # Returned self
     def by_col_or_row!
       @mode = :col_or_row
 
       self
     end
 
+    # :call-seq:
+    #   table.by_row
     #
-    # 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.
+    # Returns a duplicate of +self+, in row mode
+    # (see {Row Mode}[#class-CSV::Table-label-Row+Mode]):
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.mode # => :col_or_row
+    #   dup_table = table.by_row
+    #   dup_table.mode # => :row
+    #   dup_table.equal?(table) # => false # It's a dup
     #
-    # This method returns the duplicate table for chaining.  Don't chain
-    # destructive methods (like []=()) this way though, since you are working
-    # with a duplicate.
+    # This may be used to chain method calls without changing the mode
+    # (but also will affect performance and memory usage):
+    #   dup_table.by_row[1]
     #
+    # Also note that changes to the duplicate table will not affect the original.
     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.
-    #
+    # :call-seq:
+    #   table.by_row!
+    #
+    # Sets the mode for +self+ to row mode
+    # (see {Row Mode}[#class-CSV::Table-label-Row+Mode]); returns +self+:
+    #   source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+    #   table = CSV.parse(source, headers: true)
+    #   table.mode # => :col_or_row
+    #   table1 = table.by_row!
+    #   table.mode # => :row
+    #   table1.equal?(table) # => true # Returned self
     def by_row!
       @mode = :row
 
       self
     end
 
-    #
-    # Returns the headers for the first row of this table (assumed to match all
-    # other rows). The headers Array passed to CSV::Table.new is returned for
-    # empty tables.
-    #
+    # :call-seq:
+    #   table.headers
+    #
+    # Returns a new \Array containing the \String headers for the table.
+    #
+    # If the table is not empty, returns the headers from the first row:
+    #   rows = [
+    #     CSV::Row.new(['Foo', 'Bar'], []),
+    #     CSV::Row.new(['FOO', 'BAR'], []),
+    #     CSV::Row.new(['foo', 'bar'], []),
+    #   ]
+    #   table  = CSV::Table.new(rows)
+    #   table.headers # => ["Foo", "Bar"]
+    #   table.delete(0)
+    #   table.headers # => ["FOO", "BAR"]
+    #   table.delete(0)
+    #   table.headers # => ["foo", "bar"]
+    #
+    # If the table is empty, returns a copy of the headers in the table itself:
+    #   table.delete(0)
+    #   table.headers # => ["Foo", "Bar"]
     def headers
       if @table.empty?
         @headers.dup

data/lib/csv/version.rb

@@ -2,5 +2,5 @@
 
 class CSV
   # The version of the installed library.
-  VERSION = "3.1.6"
+  VERSION = "3.1.7"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: csv
 version: !ruby/object:Gem::Version
-  version: 3.1.6
+  version: 3.1.7
 platform: ruby
 authors:
 - James Edward Gray II
@@ -9,22 +9,8 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-07-19 00:00:00.000000000 Z
+date: 2020-08-04 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: stringio
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.1.3
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.1.3
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -97,28 +83,28 @@ files:
 - LICENSE.txt
 - NEWS.md
 - README.md
-- doc/arguments/io.rdoc
-- doc/options/common/col_sep.rdoc
-- doc/options/common/quote_char.rdoc
-- doc/options/common/row_sep.rdoc
-- doc/options/generating/force_quotes.rdoc
-- doc/options/generating/quote_empty.rdoc
-- doc/options/generating/write_converters.rdoc
-- doc/options/generating/write_empty_value.rdoc
-- doc/options/generating/write_headers.rdoc
-- doc/options/generating/write_nil_value.rdoc
-- doc/options/parsing/converters.rdoc
-- doc/options/parsing/empty_value.rdoc
-- doc/options/parsing/field_size_limit.rdoc
-- doc/options/parsing/header_converters.rdoc
-- doc/options/parsing/headers.rdoc
-- doc/options/parsing/liberal_parsing.rdoc
-- doc/options/parsing/nil_value.rdoc
-- doc/options/parsing/return_headers.rdoc
-- doc/options/parsing/skip_blanks.rdoc
-- doc/options/parsing/skip_lines.rdoc
-- doc/options/parsing/strip.rdoc
-- doc/options/parsing/unconverted_fields.rdoc
+- doc/csv/arguments/io.rdoc
+- doc/csv/options/common/col_sep.rdoc
+- doc/csv/options/common/quote_char.rdoc
+- doc/csv/options/common/row_sep.rdoc
+- doc/csv/options/generating/force_quotes.rdoc
+- doc/csv/options/generating/quote_empty.rdoc
+- doc/csv/options/generating/write_converters.rdoc
+- doc/csv/options/generating/write_empty_value.rdoc
+- doc/csv/options/generating/write_headers.rdoc
+- doc/csv/options/generating/write_nil_value.rdoc
+- doc/csv/options/parsing/converters.rdoc
+- doc/csv/options/parsing/empty_value.rdoc
+- doc/csv/options/parsing/field_size_limit.rdoc
+- doc/csv/options/parsing/header_converters.rdoc
+- doc/csv/options/parsing/headers.rdoc
+- doc/csv/options/parsing/liberal_parsing.rdoc
+- doc/csv/options/parsing/nil_value.rdoc
+- doc/csv/options/parsing/return_headers.rdoc
+- doc/csv/options/parsing/skip_blanks.rdoc
+- doc/csv/options/parsing/skip_lines.rdoc
+- doc/csv/options/parsing/strip.rdoc
+- doc/csv/options/parsing/unconverted_fields.rdoc
 - lib/csv.rb
 - lib/csv/core_ext/array.rb
 - lib/csv/core_ext/string.rb
@@ -144,14 +130,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.0.pre1
+rubygems_version: 3.2.0.rc.1
 signing_key: 
 specification_version: 4
 summary: CSV Reading and Writing