Refactor README into docs.

Author: markrogoyski

README.md

@@ -0,0 +1,38 @@
+# File Iteration
+
+[Back to main README](../README.md)
+
+Tools for iterating over file contents.
+
+---
+
+### Read CSV
+Iterate the lines of a CSV file.
+
+```File::readCsv(resource $fileHandle, string $separator = ',', string $enclosure = '"', string $escape = '\\')```
+
+```php
+use IterTools\File;
+
+$fileHandle = \fopen('path/to/file.csv', 'r');
+
+foreach (File::readCsv($fileHandle) as $row) {
+    print_r($row);
+}
+// Each column field is an element of the array
+```
+
+### Read Lines
+Iterate the lines of a file.
+
+```File::readLines(resource $fileHandle)```
+
+```php
+use IterTools\File;
+
+$fileHandle = \fopen('path/to/file.txt', 'r');
+
+foreach (File::readLines($fileHandle) as $line) {
+    print($line);
+}
+```

docs/file-iteration.md

@@ -0,0 +1,56 @@
+# Infinite Iteration
+
+[Back to main README](../README.md)
+
+Tools for creating infinite iterators.
+
+---
+
+### Count
+Count sequentially forever.
+
+```Infinite::count(int $start = 1, int $step = 1)```
+
+```php
+use IterTools\Infinite;
+
+$start = 1;
+$step  = 1;
+
+foreach (Infinite::count($start, $step) as $i) {
+    print($i);
+}
+// 1, 2, 3, 4, 5 ...
+```
+
+### Cycle
+Cycle through the elements of a collection sequentially forever.
+
+```Infinite::cycle(iterable $iterable)```
+
+```php
+use IterTools\Infinite;
+
+$hands = ['rock', 'paper', 'scissors'];
+
+foreach (Infinite::cycle($hands) as $hand) {
+    RockPaperScissors::playHand($hand);
+}
+// rock, paper, scissors, rock, paper, scissors, ...
+```
+
+### Repeat (Infinite)
+Repeat an item forever.
+
+```Infinite::repeat(mixed $item)```
+
+```php
+use IterTools\Infinite;
+
+$dialogue = 'Are we there yet?';
+
+foreach (Infinite::repeat($dialogue) as $repeated) {
+    print($repeated);
+}
+// 'Are we there yet?', 'Are we there yet?', 'Are we there yet?', ...
+```

docs/infinite-iteration.md

@@ -0,0 +1,177 @@
+# Math Iteration
+
+[Back to main README](../README.md)
+
+Tools for mathematical iteration operations.
+
+---
+
+### Frequencies
+Returns a frequency distribution of the data.
+
+```Math::frequencies(iterable $data, bool $strict = true): \Generator```
+
+Defaults to [strict type](../README.md#strict-and-coercive-types) comparisons. Set strict to false for type coercion comparisons.
+
+```php
+use IterTools\Math;
+
+$grades = ['A', 'A', 'B', 'B', 'B', 'C'];
+
+foreach (Math::frequencies($grades) as $grade => $frequency) {
+    print("$grade: $frequency" . \PHP_EOL);
+}
+// A: 2, B: 3, C: 1
+```
+
+### Relative Frequencies
+Returns a relative frequency distribution of the data.
+
+```Math::relativeFrequencies(iterable $data, bool $strict = true): \Generator```
+
+Defaults to [strict type](../README.md#strict-and-coercive-types) comparisons. Set strict to false for type coercion comparisons.
+
+```php
+use IterTools\Math;
+
+$grades = ['A', 'A', 'B', 'B', 'B', 'C'];
+
+foreach (Math::relativeFrequencies($grades) as $grade => $frequency) {
+    print("$grade: $frequency" . \PHP_EOL);
+}
+// A: 0.33, B: 0.5, C: 0.166
+```
+
+### Running Average
+Accumulate the running average over a list of numbers.
+
+```Math::runningAverage(iterable $numbers, int|float $initialValue = null)```
+
+```php
+use IterTools\Math;
+
+$grades = [100, 80, 80, 90, 85];
+
+foreach (Math::runningAverage($grades) as $runningAverage) {
+    print($runningAverage);
+}
+// 100, 90, 86.667, 87.5, 87
+```
+
+### Running Difference
+Accumulate the running difference over a list of numbers.
+
+```Math::runningDifference(iterable $numbers, int|float $initialValue = null)```
+
+```php
+use IterTools\Math;
+
+$credits = [1, 2, 3, 4, 5];
+
+foreach (Math::runningDifference($credits) as $runningDifference) {
+    print($runningDifference);
+}
+// -1, -3, -6, -10, -15
+```
+Provide an optional initial value to lead off the running difference.
+```php
+use IterTools\Math;
+
+$dartsScores   = [50, 50, 25, 50];
+$startingScore = 501;
+
+foreach (Math::runningDifference($dartsScores, $startingScore) as $runningScore) {
+    print($runningScore);
+}
+// 501, 451, 401, 376, 326
+```
+
+### Running Max
+Accumulate the running maximum over a list of numbers.
+
+```Math::runningMax(iterable $numbers, int|float $initialValue = null)```
+
+```php
+use IterTools\Math;
+
+$numbers = [1, 2, 1, 3, 5];
+
+foreach (Math::runningMax($numbers) as $runningMax) {
+    print($runningMax);
+}
+// 1, 2, 2, 3, 5
+```
+
+### Running Min
+Accumulate the running minimum over a list of numbers.
+
+```Math::runningMin(iterable $numbers, int|float $initialValue = null)```
+
+```php
+use IterTools\Math;
+
+$numbers = [3, 4, 2, 5, 1];
+
+foreach (Math::runningMin($numbers) as $runningMin) {
+    print($runningMin);
+}
+// 3, 3, 2, 2, 1
+```
+
+### Running Product
+Accumulate the running product over a list of numbers.
+
+```Math::runningProduct(iterable $numbers, int|float $initialValue = null)```
+
+```php
+use IterTools\Math;
+
+$numbers = [1, 2, 3, 4, 5];
+
+foreach (Math::runningProduct($numbers) as $runningProduct) {
+    print($runningProduct);
+}
+// 1, 2, 6, 24, 120
+```
+
+Provide an optional initial value to lead off the running product.
+```php
+use IterTools\Math;
+
+$numbers      = [1, 2, 3, 4, 5];
+$initialValue = 5;
+
+foreach (Math::runningProduct($numbers, $initialValue) as $runningProduct) {
+    print($runningProduct);
+}
+// 5, 5, 10, 30, 120, 600
+```
+
+### Running Total
+Accumulate the running total over a list of numbers.
+
+```Math::runningTotal(iterable $numbers, int|float $initialValue = null)```
+
+```php
+use IterTools\Math;
+
+$prices = [1, 2, 3, 4, 5];
+
+foreach (Math::runningTotal($prices) as $runningTotal) {
+    print($runningTotal);
+}
+// 1, 3, 6, 10, 15
+```
+
+Provide an optional initial value to lead off the running total.
+```php
+use IterTools\Math;
+
+$prices       = [1, 2, 3, 4, 5];
+$initialValue = 5;
+
+foreach (Math::runningTotal($prices, $initialValue) as $runningTotal) {
+    print($runningTotal);
+}
+// 5, 6, 8, 11, 15, 20
+```

docs/math-iteration.md

@@ -0,0 +1,105 @@
+# Multi Iteration
+
+[Back to main README](../README.md)
+
+Tools for iterating multiple collections simultaneously.
+
+---
+
+### Chain
+Chain multiple iterables together into a single continuous sequence.
+
+```Multi::chain(iterable ...$iterables)```
+```php
+use IterTools\Multi;
+
+$prequels  = ['Phantom Menace', 'Attack of the Clones', 'Revenge of the Sith'];
+$originals = ['A New Hope', 'Empire Strikes Back', 'Return of the Jedi'];
+
+foreach (Multi::chain($prequels, $originals) as $movie) {
+    print($movie);
+}
+// 'Phantom Menace', 'Attack of the Clones', 'Revenge of the Sith', 'A New Hope', 'Empire Strikes Back', 'Return of the Jedi'
+```
+
+### Zip
+Iterate multiple iterable collections simultaneously.
+
+```Multi::zip(iterable ...$iterables)```
+```php
+use IterTools\Multi;
+
+$languages = ['PHP', 'Python', 'Java', 'Go'];
+$mascots   = ['elephant', 'snake', 'bean', 'gopher'];
+
+foreach (Multi::zip($languages, $mascots) as [$language, $mascot]) {
+    print("The {$language} language mascot is an {$mascot}.");
+}
+// The PHP language mascot is an elephant.
+// ...
+```
+
+Zip works with multiple iterable inputs--not limited to just two.
+```php
+$names          = ['Ryu', 'Ken', 'Chun Li', 'Guile'];
+$countries      = ['Japan', 'USA', 'China', 'USA'];
+$signatureMoves = ['hadouken', 'shoryuken', 'spinning bird kick', 'sonic boom'];
+
+foreach (Multi::zip($names, $countries, $signatureMoves) as [$name, $country, $signatureMove]) {
+    $streetFighter = new StreetFighter($name, $country, $signatureMove);
+}
+```
+Note: For uneven lengths, iteration stops when the shortest iterable is exhausted.
+
+### ZipEqual
+Iterate multiple iterable collections with equal lengths simultaneously.
+
+Throws `\LengthException` if lengths are not equal, meaning that at least one iterator ends before the others.
+
+```Multi::zipEqual(iterable ...$iterables)```
+
+```php
+use IterTools\Multi;
+
+$letters = ['A', 'B', 'C'];
+$numbers = [1, 2, 3];
+
+foreach (Multi::zipEqual($letters, $numbers) as [$letter, $number]) {
+    // ['A', 1], ['B', 2], ['C', 3]
+}
+```
+
+### ZipFilled
+Iterate multiple iterable collections simultaneously, using a default filler value if lengths are not equal.
+
+```Multi::zipFilled(mixed $filler, iterable ...$iterables)```
+
+```php
+use IterTools\Multi;
+
+$default = '?';
+$letters = ['A', 'B'];
+$numbers = [1, 2, 3];
+
+foreach (Multi::zipFilled($default, $letters, $numbers) as [$letter, $number]) {
+    // ['A', 1], ['B', 2], ['?', 3]
+}
+```
+
+### ZipLongest
+Iterate multiple iterable collections simultaneously.
+
+```Multi::zipLongest(iterable ...$iterables)```
+
+For uneven lengths, the exhausted iterables will produce `null` for the remaining iterations.
+
+```php
+use IterTools\Multi;
+
+$letters = ['A', 'B', 'C'];
+$numbers = [1, 2];
+
+foreach (Multi::zipLongest($letters, $numbers) as [$letter, $number]) {
+    // ['A', 1], ['B', 2], ['C', null]
+}
+```