From 677185c7f00cc1a98850ce43be0eeac02344b2be Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@yahoo.com>
Date: Sat, 19 Sep 2020 13:51:09 -0500
Subject: [PATCH 1/3] Recipes for field converters

---
 doc/csv/recipes.rdoc | 49 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/doc/csv/recipes.rdoc b/doc/csv/recipes.rdoc
index 1ba3c443..28caee82 100644
--- a/doc/csv/recipes.rdoc
+++ b/doc/csv/recipes.rdoc
@@ -12,6 +12,10 @@
   - {Parse from IO Stream}[#label-Parse+from+IO+Stream]
     - {Parse from IO Stream Without Headers}[#label-Parse+from+IO+Stream+Without+Headers]
     - {Parse from IO Stream with Headers}[#label-Parse+from+IO+Stream+with+Headers]
+- {Parsing: Field Converters}[#label-Parsing-3A+Field+Converters]
+  - {Convert Fields to Objects}[#label-Convert+Fields+to+Objects]
+    - {Convert Fields to Objects Using Built-In Converters}[#label-Convert+Fields+to+Objects+Using+Built-In+Converters]
+    - {Convert Fields to Objects Using Custom Converters}[#label-Convert+Fields+to+Objects+Using+Custom+Converters]
 - {Generating: Output Formats}[#label-Generating-3A+Output+Formats]
   - {Generate to String}[#label-Generate+to+String]
     - {Generate to String Without Headers}[#label-Generate+to+String+Without+Headers]
@@ -152,6 +156,51 @@ Output:
   #<CSV::Row "Name":"bar" "Value":"1">
   #<CSV::Row "Name":"baz" "Value":"2">
 
+=== Parsing: Field Converters
+
+==== Convert Fields to Objects
+
+Use field converters to change parsed Strings into other, more specific, object.
+
+==== Convert Fields to Objects Using Built-In Converters
+
+Without converters (all fields parsed as Strings):
+  source = "0,1.1,2020-09-19"
+  parsed = CSV.parse(source)
+  parsed # => [["0", "1.1", "2020-09-19"]]
+  parsed.first.each {|field| p field.class }
+Output:
+  String
+  String
+  String
+
+With built-in converters (see {Built-In Field Converters}[../../CSV.html#class-CSV-label-Built-In+Field+Converters]):
+  parsed = CSV.parse(source, converters: :all)
+  parsed # => [[0, 1.1, #<DateTime: 2020-09-19T00:00:00+00:00 ((2459112j,0s,0n),+0s,2299161j)>]]
+  parsed.first.each {|field| p field.class }
+Output:
+  Integer
+  Float
+  DateTime
+
+==== Convert Fields to Objects Using Custom Converters
+
+See {Custom Field Converters}[../../CSV.html#class-CSV-label-Custom+Field+Converters].
+
+Define a custom field converter and add it to the \Converters \Hash:
+  strip_converter = proc {|field| field.strip }
+  CSV::Converters[:strip] = strip_converter
+
+Without the new converter:
+  string = " foo , 0 \n bar , 1 \n baz , 2 \n"
+  array = CSV.parse(string)
+  array # => [[" foo ", " 0 "], [" bar ", " 1 "], [" baz ", " 2 "]]
+
+With the new converter:
+  string = " foo , 0 \n bar , 1 \n baz , 2 \n"
+  array = CSV.parse(string, converters: strip_converter)
+  array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+
 === Generating: Output Formats
 
 ==== Generate to \String Without Headers

From 6550293cc4fb467bcf1d4b8fbf9ee0888fa40592 Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@yahoo.com>
Date: Sun, 20 Sep 2020 09:51:07 -0500
Subject: [PATCH 2/3] Recipes for field converters

---
 doc/csv/recipes.rdoc | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/doc/csv/recipes.rdoc b/doc/csv/recipes.rdoc
index 28caee82..da16bcf3 100644
--- a/doc/csv/recipes.rdoc
+++ b/doc/csv/recipes.rdoc
@@ -1,5 +1,8 @@
 == Recipes
 
+All code snippets on this page assume that the following has been executed:
+  require 'csv'
+
 === Contents
 
 - {Parsing: Source Formats}[#label-Parsing-3A+Source+Formats]
@@ -185,11 +188,8 @@ Output:
 
 ==== Convert Fields to Objects Using Custom Converters
 
-See {Custom Field Converters}[../../CSV.html#class-CSV-label-Custom+Field+Converters].
-
-Define a custom field converter and add it to the \Converters \Hash:
+Define a custom field converter:
   strip_converter = proc {|field| field.strip }
-  CSV::Converters[:strip] = strip_converter
 
 Without the new converter:
   string = " foo , 0 \n bar , 1 \n baz , 2 \n"
@@ -197,10 +197,11 @@ Without the new converter:
   array # => [[" foo ", " 0 "], [" bar ", " 1 "], [" baz ", " 2 "]]
 
 With the new converter:
-  string = " foo , 0 \n bar , 1 \n baz , 2 \n"
   array = CSV.parse(string, converters: strip_converter)
   array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
 
+See {Custom Field Converters}[../../CSV.html#class-CSV-label-Custom+Field+Converters].
+
 === Generating: Output Formats
 
 ==== Generate to \String Without Headers

From ceb889044b8d21e519c39b4efc02e11e34f28a6f Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@yahoo.com>
Date: Sun, 20 Sep 2020 09:56:53 -0500
Subject: [PATCH 3/3] Recipes for field converters

---
 doc/csv/recipes.rdoc | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/doc/csv/recipes.rdoc b/doc/csv/recipes.rdoc
index da16bcf3..20c4c4b6 100644
--- a/doc/csv/recipes.rdoc
+++ b/doc/csv/recipes.rdoc
@@ -200,7 +200,10 @@ With the new converter:
   array = CSV.parse(string, converters: strip_converter)
   array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
 
-See {Custom Field Converters}[../../CSV.html#class-CSV-label-Custom+Field+Converters].
+You can also register a custom field converter, then refer to it by name:
+  CSV::Converters[:strip] = strip_converter
+  array = CSV.parse(string, converters: :strip)
+  array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
 
 === Generating: Output Formats