From 60ea563773f1c50162a948c44901c93b9a0aee56 Mon Sep 17 00:00:00 2001
From: Ignace Nyamagana Butera <nyamsprod@gmail.com>
Date: Fri, 18 Aug 2017 12:21:39 +0200
Subject: [PATCH] prepare 9.9.0 release

---
 CHANGELOG.md                |  2 +-
 docs/_data/project.yml      | 23 +++++++++++------------
 docs/_layouts/homepage.html |  2 +-
 docs/upgrading/9.0.md       |  2 +-
 src/AbstractCsv.php         |  1 -
 src/ByteSequence.php        |  1 -
 src/CannotInsertRecord.php  |  1 -
 src/CharsetConverter.php    |  2 +-
 src/ColumnConsistency.php   |  3 +--
 src/Exception.php           |  3 +--
 src/HTMLConverter.php       |  4 ++--
 src/MapIterator.php         |  1 -
 src/RFC4180Field.php        |  2 ++
 src/Reader.php              | 33 +++++++++++++++++----------------
 src/ResultSet.php           | 19 +++++++++----------
 src/Statement.php           | 27 +++++++++++++++++----------
 src/Stream.php              | 20 +++++++-------------
 src/Writer.php              | 19 ++++++++++---------
 src/XMLConverter.php        |  2 +-
 src/functions.php           |  6 +++---
 20 files changed, 85 insertions(+), 88 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 34269921..ea510d4c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,7 +2,7 @@
 
 All Notable changes to `Csv` will be documented in this file
 
-## 9.0.0 - TBD
+## 9.0.0 - 2017-08-18
 
 ### Added
 
diff --git a/docs/_data/project.yml b/docs/_data/project.yml
index 318c9a8f..82be52ce 100644
--- a/docs/_data/project.yml
+++ b/docs/_data/project.yml
@@ -6,25 +6,24 @@ google_analytics_tracking_id: UA-46050814-6
 # Github repository
 repository: 'csv'
 releases:
-  next:
+#  next:
+#    version: '10.0'
+#    requires: 'PHP >= 5.5.0'
+#    latest: '8.2.1 - 2017-02-03'
+#    supported_until: 'TBD'
+#    documentation_link: '/8.0/'
+  current:
     version: '9.0'
     requires: 'PHP >= 7.0.10'
-    latest: 'TBD'
+    latest: '9.0.0 - 2017-08-18'
     supported_until: 'TBD'
     documentation_link: '/9.0/'
-  current:
+  previous:
     version: '8.0'
     requires: 'PHP >= 5.5.0'
-    latest: '8.2.1 - 2017-02-03'
-    supported_until: 'TBD'
+    latest: '8.2.2 - 2017-07-12'
+    supported_until: '2018-02-18'
     documentation_link: '/8.0/'
-# Uncomment if needed
-#   previous:
-#    version: '8.0'
-#    requires: 'PHP >= 5.5.0'
-#    latest: '8.2.1 - 2017-02-03'
-#    supported_until: 'TBD'
-#    documentation_link: '/8.0/'
   legacy:
     version: '7.0'
     requires: 'PHP >= 5.4.0'
diff --git a/docs/_layouts/homepage.html b/docs/_layouts/homepage.html
index 0f78ecf6..a8a363a2 100644
--- a/docs/_layouts/homepage.html
+++ b/docs/_layouts/homepage.html
@@ -77,7 +77,7 @@ <h2>Current Stable</h2>
 {% endif %}
 {% if site.data.project.releases.previous %}
       <div class="version previous">
-        <h2>Unsupported</h2>
+        <h2>Old Stable Release</h2>
         <div class="content">
           <p><code>league/{{ site.data.project.title | downcase }}:^{{ site.data.project.releases.previous.version }}</code></p>
           <ul>
diff --git a/docs/upgrading/9.0.md b/docs/upgrading/9.0.md
index e07d715e..ec33c2e2 100644
--- a/docs/upgrading/9.0.md
+++ b/docs/upgrading/9.0.md
@@ -3,7 +3,7 @@ layout: default
 title: Upgrading from 8.x to 9.x
 ---
 
-<p class="message-notice">This is the documentation for the upcoming <code>version 9.0</code>. This is a work in progress.</p>
+<!--p class="message-notice">This is the documentation for the upcoming <code>version 9.0</code>. This is a work in progress.</p-->
 
 # Upgrading from 8.x to 9.x
 
diff --git a/src/AbstractCsv.php b/src/AbstractCsv.php
index e8b0cc52..23ddf45b 100644
--- a/src/AbstractCsv.php
+++ b/src/AbstractCsv.php
@@ -24,7 +24,6 @@
  * @package League.csv
  * @since   4.0.0
  * @author  Ignace Nyamagana Butera <nyamsprod@gmail.com>
- *
  */
 abstract class AbstractCsv implements ByteSequence
 {
diff --git a/src/ByteSequence.php b/src/ByteSequence.php
index 5991163b..2f77a84f 100644
--- a/src/ByteSequence.php
+++ b/src/ByteSequence.php
@@ -20,7 +20,6 @@
  * @package League.csv
  * @since   9.0.0
  * @author  Ignace Nyamagana Butera <nyamsprod@gmail.com>
- *
  */
 interface ByteSequence
 {
diff --git a/src/CannotInsertRecord.php b/src/CannotInsertRecord.php
index 80dde1d5..2877b022 100644
--- a/src/CannotInsertRecord.php
+++ b/src/CannotInsertRecord.php
@@ -20,7 +20,6 @@
  * @package League.csv
  * @since   9.0.0
  * @author  Ignace Nyamagana Butera <nyamsprod@gmail.com>
- *
  */
 class CannotInsertRecord extends Exception
 {
diff --git a/src/CharsetConverter.php b/src/CharsetConverter.php
index 1bc665e5..b36c1c2f 100644
--- a/src/CharsetConverter.php
+++ b/src/CharsetConverter.php
@@ -20,7 +20,7 @@
 use TypeError;
 
 /**
- * A class to convert your CSV records collection charset
+ * A class to convert resource stream or tabular data content charset
  *
  * @package League.csv
  * @since   9.0.0
diff --git a/src/ColumnConsistency.php b/src/ColumnConsistency.php
index 4f8cd1cc..1446c6d2 100644
--- a/src/ColumnConsistency.php
+++ b/src/ColumnConsistency.php
@@ -15,12 +15,11 @@
 namespace League\Csv;
 
 /**
- * A class to manage column consistency on data insertion into a CSV
+ * A class to validate column consistency when inserting records into a CSV document
  *
  * @package League.csv
  * @since   7.0.0
  * @author  Ignace Nyamagana Butera <nyamsprod@gmail.com>
- *
  */
 class ColumnConsistency
 {
diff --git a/src/Exception.php b/src/Exception.php
index 91635215..ab3ee03e 100644
--- a/src/Exception.php
+++ b/src/Exception.php
@@ -15,12 +15,11 @@
 namespace League\Csv;
 
 /**
- *  League Csv Base Exception
+ * League Csv Base Exception
  *
  * @package League.csv
  * @since   9.0.0
  * @author  Ignace Nyamagana Butera <nyamsprod@gmail.com>
- *
  */
 class Exception extends \Exception
 {
diff --git a/src/HTMLConverter.php b/src/HTMLConverter.php
index b82b9bf4..7d4bc2ef 100644
--- a/src/HTMLConverter.php
+++ b/src/HTMLConverter.php
@@ -18,7 +18,7 @@
 use Traversable;
 
 /**
- * A class to convert CSV records into an HTML Table string
+ * A class to convert tabular data into an HTML Table string
  *
  * @package League.csv
  * @since   9.0.0
@@ -60,7 +60,7 @@ public function __construct()
     /**
      * Convert an Record collection into a DOMDocument
      *
-     * @param array|Traversable $records the CSV records collection
+     * @param array|Traversable $records the tabular data collection
      *
      * @return string
      */
diff --git a/src/MapIterator.php b/src/MapIterator.php
index c780283b..43dd9b93 100644
--- a/src/MapIterator.php
+++ b/src/MapIterator.php
@@ -24,7 +24,6 @@
  * @since    3.3.0
  * @author   Ignace Nyamagana Butera <nyamsprod@gmail.com>
  * @internal used internally to modify CSV content
- *
  */
 class MapIterator extends IteratorIterator
 {
diff --git a/src/RFC4180Field.php b/src/RFC4180Field.php
index bfefa905..18520ee8 100644
--- a/src/RFC4180Field.php
+++ b/src/RFC4180Field.php
@@ -19,6 +19,8 @@
 /**
  * A stream filter to conform the CSV field to RFC4180
  *
+ * @see https://tools.ietf.org/html/rfc4180#section-2
+ *
  * @package League.csv
  * @since   9.0.0
  * @author  Ignace Nyamagana Butera <nyamsprod@gmail.com>
diff --git a/src/Reader.php b/src/Reader.php
index 8934ba5f..a70e75ae 100644
--- a/src/Reader.php
+++ b/src/Reader.php
@@ -24,7 +24,7 @@
 use TypeError;
 
 /**
- * A class to manage records selection from a CSV document
+ * A class to select records from a CSV document
  *
  * @package League.csv
  * @since  3.0.0
@@ -36,21 +36,21 @@
 class Reader extends AbstractCsv implements Countable, IteratorAggregate, JsonSerializable
 {
     /**
-     * CSV Document header offset
+     * header offset
      *
      * @var int|null
      */
     protected $header_offset;
 
     /**
-     * CSV Document Header record
+     * header record
      *
      * @var string[]
      */
     protected $header = [];
 
     /**
-     * Records count
+     * records count
      *
      * @var int
      */
@@ -62,9 +62,9 @@ class Reader extends AbstractCsv implements Countable, IteratorAggregate, JsonSe
     protected $stream_filter_mode = STREAM_FILTER_READ;
 
     /**
-     * Returns the record offset used as header
+     * Returns the header offset
      *
-     * If no CSV record is used this method MUST return null
+     * If no CSV header offset is set this method MUST return null
      *
      * @return int|null
      */
@@ -74,7 +74,7 @@ public function getHeaderOffset()
     }
 
     /**
-     * Returns the CSV record header
+     * Returns the CSV record used as header
      *
      * The returned header is represented as an array of string values
      *
@@ -100,8 +100,7 @@ public function getHeader(): array
      *
      * @param int $offset
      *
-     * @throws Exception If the header offset is an integer and the corresponding record is missing
-     *                   or is an empty array
+     * @throws Exception If the header offset is set and no record is found or is the empty array
      *
      * @return string[]
      */
@@ -151,7 +150,7 @@ protected function removeBOM(array $record, int $bom_length, string $enclosure):
      */
     public function __call($method, array $arguments)
     {
-        $whitelisted = ['fetchColumn' => 1, 'fetchOne' => 1, 'fetchPairs' => 1];
+        static $whitelisted = ['fetchColumn' => 1, 'fetchOne' => 1, 'fetchPairs' => 1];
         if (isset($whitelisted[$method])) {
             return (new ResultSet($this->getRecords(), $this->getHeader()))->$method(...$arguments);
         }
@@ -188,12 +187,12 @@ public function jsonSerialize(): array
     }
 
     /**
-     * Returns the CSV records in an iterator object.
+     * Returns the CSV records as an iterator object.
      *
-     * Each CSV record is represented as a simple array of string or null values.
+     * Each CSV record is represented as a simple array containig strings or null values.
      *
      * If the CSV document has a header record then each record is combined
-     * to each header record and the header record is removed from the iterator.
+     * to the header record and the header record is removed from the iterator.
      *
      * If the CSV document is inconsistent. Missing record fields are
      * filled with null values while extra record fields are strip from
@@ -246,7 +245,7 @@ protected function computeHeader(array $header)
     }
 
     /**
-     * Add the CSV header if present and valid
+     * Combine the CSV header to each record if present
      *
      * @param Iterator $iterator
      * @param string[] $header
@@ -272,7 +271,7 @@ protected function combineHeader(Iterator $iterator, array $header): Iterator
     }
 
     /**
-     * Strip the BOM sequence if present
+     * Strip the BOM sequence from the returned records if necessary
      *
      * @param Iterator $iterator
      * @param string   $bom
@@ -300,11 +299,13 @@ protected function stripBOM(Iterator $iterator, string $bom): Iterator
     /**
      * Selects the record to be used as the CSV header
      *
-     * Because of the header is represented as an array, to be valid
+     * Because the header is represented as an array, to be valid
      * a header MUST contain only unique string value.
      *
      * @param int|null $offset the header record offset
      *
+     * @throws Exception if the offset is a negative integer
+     *
      * @return static
      */
     public function setHeaderOffset($offset): self
diff --git a/src/ResultSet.php b/src/ResultSet.php
index 5305ffef..39c5ae46 100644
--- a/src/ResultSet.php
+++ b/src/ResultSet.php
@@ -28,7 +28,6 @@
  * @package League.csv
  * @since   9.0.0
  * @author  Ignace Nyamagana Butera <nyamsprod@gmail.com>
- *
  */
 class ResultSet implements Countable, IteratorAggregate, JsonSerializable
 {
@@ -40,7 +39,7 @@ class ResultSet implements Countable, IteratorAggregate, JsonSerializable
     protected $records;
 
     /**
-     * The CSV records collection column names
+     * The CSV records collection header
      *
      * @var array
      */
@@ -67,7 +66,7 @@ public function __destruct()
     }
 
     /**
-     * Returns the column names associated with the ResultSet
+     * Returns the header associated with the result set
      *
      * @return string[]
      */
@@ -111,7 +110,7 @@ public function jsonSerialize(): array
     }
 
     /**
-     * Returns a the nth record from the resultset
+     * Returns the nth record from the result set
      *
      * By default if no index is provided the first record of the resultet is returned
      *
@@ -134,9 +133,9 @@ public function fetchOne(int $nth_record = 0): array
     }
 
     /**
-     * Returns the next value from a single CSV record field
+     * Returns a single column from the next record of the result set
      *
-     * By default if no column index is provided the first column of the CSV is selected
+     * By default if no value is supplied the first column is fetch
      *
      * @param string|int $index CSV column index
      *
@@ -160,7 +159,7 @@ public function fetchColumn($index = 0): Generator
     }
 
     /**
-     * Filter a column name against the CSV header if any
+     * Filter a column name against the header if any
      *
      * @param string|int $field         the field name or the field index
      * @param string     $error_message the associated error message
@@ -222,12 +221,12 @@ protected function getColumnIndexByKey(int $index, string $error_message)
     }
 
     /**
-     * Fetches the next key-value pairs from a result set (first
+     * Returns the next key-value pairs from a result set (first
      * column is the key, second column is the value).
      *
      * By default if no column index is provided:
-     * - the first CSV column is used to provide the keys
-     * - the second CSV column is used to provide the value
+     * - the first column is used to provide the keys
+     * - the second column is used to provide the value
      *
      * @param string|int $offset_index The column index to serve as offset
      * @param string|int $value_index  The column index to serve as value
diff --git a/src/Statement.php b/src/Statement.php
index df5fa6be..5ddf97b1 100644
--- a/src/Statement.php
+++ b/src/Statement.php
@@ -20,12 +20,11 @@
 use LimitIterator;
 
 /**
- * A trait to manage filtering a CSV
+ * A Prepared statement to be executed on a {@link Reader} object
  *
  * @package League.csv
  * @since   9.0.0
  * @author  Ignace Nyamagana Butera <nyamsprod@gmail.com>
- *
  */
 class Statement
 {
@@ -138,7 +137,7 @@ public function limit(int $limit): self
     }
 
     /**
-     * Returns the inner CSV Document Iterator object
+     * Execute the prepared Statement on the {@link Reader} object
      *
      * @param Reader   $csv
      * @param string[] $header an optional header to use instead of the CSV document header
@@ -151,15 +150,23 @@ public function process(Reader $csv, array $header = []): ResultSet
             $header = $csv->getHeader();
         }
 
-        $reducer = function (Iterator $iterator, callable $callable): Iterator {
-            return new CallbackFilterIterator($iterator, $callable);
-        };
-
-        $iterator = array_reduce($this->where, $reducer, $csv->getRecords($header));
+        $iterator = array_reduce($this->where, [$this, 'filter'], $csv->getRecords($header));
         $iterator = $this->buildOrderBy($iterator);
-        $iterator = new LimitIterator($iterator, $this->offset, $this->limit);
 
-        return new ResultSet($iterator, $header);
+        return new ResultSet(new LimitIterator($iterator, $this->offset, $this->limit), $header);
+    }
+
+    /**
+     * Filters elements of an Iterator using a callback function
+     *
+     * @param Iterator $iterator
+     * @param callable $callable
+     *
+     * @return CallbackFilterIterator
+     */
+    protected function filter(Iterator $iterator, callable $callable): CallbackFilterIterator
+    {
+        return new CallbackFilterIterator($iterator, $callable);
     }
 
     /**
diff --git a/src/Stream.php b/src/Stream.php
index 4e6602d9..01f7e64a 100644
--- a/src/Stream.php
+++ b/src/Stream.php
@@ -26,7 +26,6 @@
  * @since    8.2.0
  * @author   Ignace Nyamagana Butera <nyamsprod@gmail.com>
  * @internal used internally to iterate over a stream resource
- *
  */
 class Stream implements SeekableIterator
 {
@@ -245,7 +244,7 @@ public function setCsvControl(string $delimiter = ',', string $enclosure = '"',
      * @param string $delimiter CSV delimiter character
      * @param string $enclosure CSV enclosure character
      * @param string $escape    CSV escape character
-     * @param string $caller    public API method calling the method
+     * @param string $caller    caller
      *
      * @throws Exception If the Csv control character is not one character only.
      *
@@ -253,19 +252,14 @@ public function setCsvControl(string $delimiter = ',', string $enclosure = '"',
      */
     protected function filterControl(string $delimiter, string $enclosure, string $escape, string $caller): array
     {
-        if (1 !== strlen($delimiter)) {
-            throw new Exception(sprintf('%s() expects delimiter to be a single character', $caller));
-        }
-
-        if (1 !== strlen($enclosure)) {
-            throw new Exception(sprintf('%s() expects enclosure to be a single character', $caller));
-        }
-
-        if (1 !== strlen($escape)) {
-            throw new Exception(sprintf('%s() expects escape to be a single character', $caller));
+        $controls = ['delimiter' => $delimiter, 'enclosure' => $enclosure, 'escape' => $escape];
+        foreach ($controls as $type => $control) {
+            if (1 !== strlen($control)) {
+                throw new Exception(sprintf('%s() expects %s to be a single character', $caller, $type));
+            }
         }
 
-        return [$delimiter, $enclosure, $escape];
+        return array_values($controls);
     }
 
     /**
diff --git a/src/Writer.php b/src/Writer.php
index ae5c5f0d..62ff8649 100644
--- a/src/Writer.php
+++ b/src/Writer.php
@@ -18,12 +18,11 @@
 use TypeError;
 
 /**
- * A class to manage records insertion into a CSV Document
+ * A class to insert records into a CSV Document
  *
  * @package League.csv
  * @since   4.0.0
  * @author  Ignace Nyamagana Butera <nyamsprod@gmail.com>
- *
  */
 class Writer extends AbstractCsv
 {
@@ -88,7 +87,7 @@ public function getFlushThreshold()
     }
 
     /**
-     * Adds multiple lines to the CSV document
+     * Adds multiple records to the CSV document
      *
      * a simple wrapper method around insertOne
      *
@@ -114,7 +113,7 @@ public function insertAll($records): int
     }
 
     /**
-     * Adds a single line to a CSV document
+     * Adds a single record to a CSV document
      *
      * @param string[] $record an array
      *
@@ -135,7 +134,7 @@ public function insertOne(array $record): int
     }
 
     /**
-     * Format the given record
+     * Format a record
      *
      * @param string[] $record
      * @param callable $formatter
@@ -190,7 +189,7 @@ protected function consolidate(): int
     }
 
     /**
-     * add a formatter to the collection
+     * Adds a record formatter
      *
      * @param callable $formatter
      *
@@ -204,7 +203,7 @@ public function addFormatter(callable $formatter): self
     }
 
     /**
-     * add a Validator to the collection
+     * Adds a record validator
      *
      * @param callable $validator
      * @param string   $validator_name the validator name
@@ -219,7 +218,7 @@ public function addValidator(callable $validator, string $validator_name): self
     }
 
     /**
-     * Sets the newline sequence characters
+     * Sets the newline sequence
      *
      * @param string $newline
      *
@@ -233,10 +232,12 @@ public function setNewline(string $newline): self
     }
 
     /**
-     * Set the automatic flush threshold on write
+     * Set the flush threshold
      *
      * @param int|null $threshold
      *
+     * @throws Exception if the threshold is a integer lesser than 1
+     *
      * @return static
      */
     public function setFlushThreshold($threshold): self
diff --git a/src/XMLConverter.php b/src/XMLConverter.php
index 8668d87a..75ef880f 100644
--- a/src/XMLConverter.php
+++ b/src/XMLConverter.php
@@ -22,7 +22,7 @@
 use TypeError;
 
 /**
- * A class to convert CSV records into a DOMDOcument object
+ * A class to convert tabular data into a DOMDOcument object
  *
  * @package League.csv
  * @since   9.0.0
diff --git a/src/functions.php b/src/functions.php
index a50cb96e..53d84a84 100644
--- a/src/functions.php
+++ b/src/functions.php
@@ -42,15 +42,15 @@ function bom_match(string $str): string
 }
 
 /**
- * Detect Delimiters usage in a CSV object
+ * Detect Delimiters usage in a {@link Reader} object
  *
  * Returns a associative array where each key represents
  * a submitted delimiter and each value the number CSV fields found
  * when processing at most $limit CSV records with the given delimiter
  *
  * @param Reader   $csv        the CSV object
- * @param string[] $delimiters the delimiters to consider
- * @param int      $limit      Detection is made using up to $limit CSV records
+ * @param string[] $delimiters list of delimiters to consider
+ * @param int      $limit      Detection is made using up to $limit records
  *
  * @return int[]
  */