From c492612b74fb5a241b37258a04d11b391e141033 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bronis=C5=82aw=20Bia=C5=82ek?= <after89@gmail.com>
Date: Mon, 7 Jan 2019 10:33:27 +0100
Subject: [PATCH] Add IterableValue examples (#15)

---
 README.md                                     |  29 +
 docs/examples.md                              | 524 +++++++++++++++++-
 examples/example/IterableValue-chunk.php      |   7 +
 examples/example/IterableValue-each.php       |   8 +
 examples/example/IterableValue-filter.php     |  16 +
 .../example/IterableValue-filterEmpty.php     |   8 +
 examples/example/IterableValue-first.php      |  13 +
 examples/example/IterableValue-join.php       |  14 +
 examples/example/IterableValue-map.php        |  10 +
 examples/example/IterableValue-reduce.php     |  19 +
 examples/example/IterableValue-slice.php      |  21 +
 make-examples.php                             |   2 +
 12 files changed, 670 insertions(+), 1 deletion(-)
 create mode 100644 examples/example/IterableValue-chunk.php
 create mode 100644 examples/example/IterableValue-each.php
 create mode 100644 examples/example/IterableValue-filter.php
 create mode 100644 examples/example/IterableValue-filterEmpty.php
 create mode 100644 examples/example/IterableValue-first.php
 create mode 100644 examples/example/IterableValue-join.php
 create mode 100644 examples/example/IterableValue-map.php
 create mode 100644 examples/example/IterableValue-reduce.php
 create mode 100644 examples/example/IterableValue-slice.php

diff --git a/README.md b/README.md
index 7d4ed75..410e71e 100644
--- a/README.md
+++ b/README.md
@@ -180,6 +180,35 @@ $stringsArray = Wrap::stringsArray(['one', '  two ', '<b>three</b>'])
     });
 ```
 
+### `IterableValue`
+
+Object wrapping iterable. 
+
+```php
+<?php
+
+use \GW\Value\Wrap;
+
+$range = function (int $start, int $end) {
+    for ($i = $start; $i <= $end; $i++) {
+        yield $i;
+    }
+};
+
+$stringsArray = Wrap::iterable($range(0, 10))
+    ->join(Wrap::iterable($range(400, 440000)))
+    ->slice(10, 20)
+    ->filter(function (int $value): bool {
+        return $value % 2 === 0;
+    })
+    ->map(function (int $value): int {
+        return $value + 2;
+    })
+    ->each(function (int $value): void {
+        echo $value . "\n";
+    });
+```
+
 ## Documentation
 
 For full methods reference and more examples see [here](./docs/examples.md).
diff --git a/docs/examples.md b/docs/examples.md
index 86a9d70..2cad8e5 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -472,7 +472,7 @@ echo $words->shuffle()->implode(' ')->toString();
 ```
 
 ```
-no there not is try do or do
+no do or there not do try is
 ```
 
 ### ArrayValue::reverse
@@ -3327,4 +3327,526 @@ public function __toString(): string;
 ```
 
 
+## IterableValue
+
+### IterableValue::each
+
+```php
+<?php
+/**
+ * @param callable $callback function(mixed $value): void
+ * @return IterableValue
+ */
+public function each(callable $callback);
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$array = Wrap::iterable(['a', 'b', 'c']);
+$mapped = $array->each(function (string $letter): void {
+    echo $letter;
+});
+```
+
+```
+abc
+```
+
+### IterableValue::filter
+
+```php
+<?php
+/**
+ * @param callable $filter function(mixed $value): bool { ... }
+ * @return IterableValue
+ */
+public function filter(callable $filter);
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$range = function (int $start, int $end) {
+    for ($i = $start; $i <= $end; $i++) {
+        yield $i;
+    }
+};
+
+$array = Wrap::iterable($range(1, 4));
+$even = $array->filter(function (int $number): bool {
+    return $number % 2 === 0;
+});
+
+var_export($even->toArray());
+```
+
+```
+array (
+  0 => 2,
+  1 => 4,
+)
+```
+
+### IterableValue::filterEmpty
+
+```php
+<?php
+/**
+ * @return IterableValue
+ */
+public function filterEmpty();
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$array = Wrap::iterable(['a', '', 'b', 'c']);
+$notEmpty = $array->filterEmpty();
+
+var_export($notEmpty->toArray());
+```
+
+```
+array (
+  0 => 'a',
+  1 => 'b',
+  2 => 'c',
+)
+```
+
+### IterableValue::map
+
+```php
+<?php
+/**
+ * @param callable $transformer function(mixed $value): mixed { ... }
+ * @return IterableValue
+ */
+public function map(callable $transformer);
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$array = Wrap::iterable(['a', 'b', 'c']);
+$mapped = $array->map(function (string $letter): string {
+    return 'new ' . $letter;
+});
+
+var_export($mapped->toArray());
+```
+
+```
+array (
+  0 => 'new a',
+  1 => 'new b',
+  2 => 'new c',
+)
+```
+
+### IterableValue::flatMap
+
+```php
+<?php
+/**
+ * @param callable $transformer function(mixed $value): iterable { ... }
+ * @return IterableValue
+ */
+public function flatMap(callable $transformer);
+```
+
+### IterableValue::join
+
+```php
+<?php
+/**
+ * @return IterableValue
+ */
+public function join(IterableValue $other);
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$range = function (int $start, int $end) {
+    for ($i = $start; $i <= $end; $i++) {
+        yield $i;
+    }
+};
+
+$one = Wrap::iterable($range(1, 3));
+$two = Wrap::iterable($range(8, 10));
+
+var_export($one->join($two)->toArray());
+```
+
+```
+array (
+  0 => 1,
+  1 => 2,
+  2 => 3,
+  3 => 8,
+  4 => 9,
+  5 => 10,
+)
+```
+
+### IterableValue::slice
+
+```php
+<?php
+/**
+ * @return IterableValue
+ */
+public function slice(int $offset, int $length);
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$range = function (int $start, int $end) {
+    for ($i = $start; $i <= $end; $i++) {
+        yield $i;
+    }
+};
+
+var_export(Wrap::iterable($range(0, PHP_INT_MAX))->slice(2, 4)->toArray());
+echo PHP_EOL;
+
+var_export(Wrap::iterable($range(0, PHP_INT_MAX))->slice(-1, 1)->toArray());
+echo PHP_EOL;
+
+var_export(Wrap::iterable($range(0, PHP_INT_MAX))->slice(0, 3)->toArray());
+echo PHP_EOL;
+
+var_export(Wrap::iterable($range(0, PHP_INT_MAX))->slice(5000, 2)->toArray());
+echo PHP_EOL;
+```
+
+```
+array (
+  0 => 2,
+  1 => 3,
+  2 => 4,
+  3 => 5,
+)
+array (
+  0 => 0,
+)
+array (
+  0 => 0,
+  1 => 1,
+  2 => 2,
+)
+array (
+  0 => 5000,
+  1 => 5001,
+)
+```
+
+### IterableValue::unique
+
+```php
+<?php
+/**
+ * @param callable|null $comparator function(mixed $valueA, mixed $valueB): int{-1, 0, 1}
+ * @return IterableValue
+ */
+public function unique(?callable $comparator = null);
+```
+
+### IterableValue::reduce
+
+```php
+<?php
+/**
+ * @param callable $transformer function(mixed $reduced, mixed $value): mixed
+ * @param mixed $start
+ * @return mixed
+ */
+public function reduce(callable $transformer, $start);
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$prices = Wrap::iterable([10, 20, 50, 120]);
+
+$summarize = function(int $sum, int $price): int {
+    return $sum + $price;
+};
+
+echo 'Sum: ' . $prices->reduce($summarize, 0);
+echo PHP_EOL;
+
+$list = function(string $list, int $price): string {
+    return $list . " €{$price},-";
+};
+
+echo 'Prices: ' . $prices->reduce($list, '');
+echo PHP_EOL;
+```
+
+```
+Sum: 200
+Prices:  €10,- €20,- €50,- €120,-
+```
+
+### IterableValue::notEmpty
+
+```php
+<?php
+/**
+ * @return IterableValue
+ */
+public function notEmpty();
+```
+
+### IterableValue::unshift
+
+```php
+<?php
+/**
+ * @param mixed $value
+ * @return IterableValue
+ */
+public function unshift($value);
+```
+
+### IterableValue::push
+
+```php
+<?php
+/**
+ * @param mixed $value
+ * @return IterableValue
+ */
+public function push($value);
+```
+
+### IterableValue::diff
+
+```php
+<?php
+/**
+ * @param callable|null $comparator function(mixed $valueA, mixed $valueB): int{-1, 0, 1}
+ * @return IterableValue
+ */
+public function diff(ArrayValue $other, ?callable $comparator = null);
+```
+
+### IterableValue::intersect
+
+```php
+<?php
+/**
+ * @param callable|null $comparator function(mixed $valueA, mixed $valueB): int{-1, 0, 1}
+ * @return IterableValue
+ */
+public function intersect(ArrayValue $other, ?callable $comparator = null);
+```
+
+### IterableValue::first
+
+```php
+<?php
+/**
+ * @return mixed
+ */
+public function first();
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$range = function (int $start, int $end) {
+    for ($i = $start; $i <= $end; $i++) {
+        yield $i;
+    }
+};
+
+$array = Wrap::iterable($range(1, PHP_INT_MAX));
+
+echo 'first: ' . $array->first();
+```
+
+```
+first: 1
+```
+
+### IterableValue::last
+
+```php
+<?php
+/**
+ * @return mixed
+ */
+public function last();
+```
+
+### IterableValue::toArrayValue
+
+```php
+<?php
+
+public function toArrayValue(): ArrayValue;
+```
+
+### IterableValue::toArray
+
+```php
+<?php
+/**
+ * @return mixed[]
+ */
+public function toArray(): array;
+```
+
+### IterableValue::use
+
+```php
+<?php
+
+public function use(iterable $iterable): IterableValue;
+```
+
+### IterableValue::chunk
+
+```php
+<?php
+/**
+ * @return IterableValue
+ */
+public function chunk(int $size);
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$array = Wrap::iterable([1, 2, 3, 4, 3, 4, 5, 6, 7, 8, 9]);
+
+var_export($array->chunk(3)->toArray());
+```
+
+```
+array (
+  0 => 
+  array (
+    0 => 1,
+    1 => 2,
+    2 => 3,
+  ),
+  1 => 
+  array (
+    0 => 4,
+    1 => 3,
+    2 => 4,
+  ),
+  2 => 
+  array (
+    0 => 5,
+    1 => 6,
+    2 => 7,
+  ),
+  3 => 
+  array (
+    0 => 8,
+    1 => 9,
+  ),
+)
+```
+
+### IterableValue::flatten
+
+```php
+<?php
+/**
+ * @return IterableValue
+ */
+public function flatten();
+```
+
+### IterableValue::any
+
+```php
+<?php
+/**
+ * @param callable $filter function(mixed $value): bool
+ */
+public function any(callable $filter): bool;
+```
+
+### IterableValue::every
+
+```php
+<?php
+/**
+ * @param callable $filter function(mixed $value): bool
+ */
+public function every(callable $filter): bool;
+```
+
+### IterableValue::find
+
+```php
+<?php
+/**
+ * @param callable $filter function(mixed $value): bool
+ * @return mixed
+ */
+public function find(callable $filter);
+```
+
+### IterableValue::findLast
+
+```php
+<?php
+/**
+ * @param callable $filter function(mixed $value): bool
+ * @return mixed
+ */
+public function findLast(callable $filter);
+```
+
+### IterableValue::getIterator
+
+*(definition not available)*
+
 
diff --git a/examples/example/IterableValue-chunk.php b/examples/example/IterableValue-chunk.php
new file mode 100644
index 0000000..086649f
--- /dev/null
+++ b/examples/example/IterableValue-chunk.php
@@ -0,0 +1,7 @@
+<?php
+
+use GW\Value\Wrap;
+
+$array = Wrap::iterable([1, 2, 3, 4, 3, 4, 5, 6, 7, 8, 9]);
+
+var_export($array->chunk(3)->toArray());
diff --git a/examples/example/IterableValue-each.php b/examples/example/IterableValue-each.php
new file mode 100644
index 0000000..c2b4803
--- /dev/null
+++ b/examples/example/IterableValue-each.php
@@ -0,0 +1,8 @@
+<?php
+
+use GW\Value\Wrap;
+
+$array = Wrap::iterable(['a', 'b', 'c']);
+$mapped = $array->each(function (string $letter): void {
+    echo $letter;
+});
diff --git a/examples/example/IterableValue-filter.php b/examples/example/IterableValue-filter.php
new file mode 100644
index 0000000..ac08246
--- /dev/null
+++ b/examples/example/IterableValue-filter.php
@@ -0,0 +1,16 @@
+<?php
+
+use GW\Value\Wrap;
+
+$range = function (int $start, int $end) {
+    for ($i = $start; $i <= $end; $i++) {
+        yield $i;
+    }
+};
+
+$array = Wrap::iterable($range(1, 4));
+$even = $array->filter(function (int $number): bool {
+    return $number % 2 === 0;
+});
+
+var_export($even->toArray());
diff --git a/examples/example/IterableValue-filterEmpty.php b/examples/example/IterableValue-filterEmpty.php
new file mode 100644
index 0000000..09be67b
--- /dev/null
+++ b/examples/example/IterableValue-filterEmpty.php
@@ -0,0 +1,8 @@
+<?php
+
+use GW\Value\Wrap;
+
+$array = Wrap::iterable(['a', '', 'b', 'c']);
+$notEmpty = $array->filterEmpty();
+
+var_export($notEmpty->toArray());
diff --git a/examples/example/IterableValue-first.php b/examples/example/IterableValue-first.php
new file mode 100644
index 0000000..83c6639
--- /dev/null
+++ b/examples/example/IterableValue-first.php
@@ -0,0 +1,13 @@
+<?php
+
+use GW\Value\Wrap;
+
+$range = function (int $start, int $end) {
+    for ($i = $start; $i <= $end; $i++) {
+        yield $i;
+    }
+};
+
+$array = Wrap::iterable($range(1, PHP_INT_MAX));
+
+echo 'first: ' . $array->first();
diff --git a/examples/example/IterableValue-join.php b/examples/example/IterableValue-join.php
new file mode 100644
index 0000000..9ac52fd
--- /dev/null
+++ b/examples/example/IterableValue-join.php
@@ -0,0 +1,14 @@
+<?php
+
+use GW\Value\Wrap;
+
+$range = function (int $start, int $end) {
+    for ($i = $start; $i <= $end; $i++) {
+        yield $i;
+    }
+};
+
+$one = Wrap::iterable($range(1, 3));
+$two = Wrap::iterable($range(8, 10));
+
+var_export($one->join($two)->toArray());
diff --git a/examples/example/IterableValue-map.php b/examples/example/IterableValue-map.php
new file mode 100644
index 0000000..2c581ac
--- /dev/null
+++ b/examples/example/IterableValue-map.php
@@ -0,0 +1,10 @@
+<?php
+
+use GW\Value\Wrap;
+
+$array = Wrap::iterable(['a', 'b', 'c']);
+$mapped = $array->map(function (string $letter): string {
+    return 'new ' . $letter;
+});
+
+var_export($mapped->toArray());
diff --git a/examples/example/IterableValue-reduce.php b/examples/example/IterableValue-reduce.php
new file mode 100644
index 0000000..8ffbc08
--- /dev/null
+++ b/examples/example/IterableValue-reduce.php
@@ -0,0 +1,19 @@
+<?php
+
+use GW\Value\Wrap;
+
+$prices = Wrap::iterable([10, 20, 50, 120]);
+
+$summarize = function(int $sum, int $price): int {
+    return $sum + $price;
+};
+
+echo 'Sum: ' . $prices->reduce($summarize, 0);
+echo PHP_EOL;
+
+$list = function(string $list, int $price): string {
+    return $list . " €{$price},-";
+};
+
+echo 'Prices: ' . $prices->reduce($list, '');
+echo PHP_EOL;
diff --git a/examples/example/IterableValue-slice.php b/examples/example/IterableValue-slice.php
new file mode 100644
index 0000000..9979cf9
--- /dev/null
+++ b/examples/example/IterableValue-slice.php
@@ -0,0 +1,21 @@
+<?php
+
+use GW\Value\Wrap;
+
+$range = function (int $start, int $end) {
+    for ($i = $start; $i <= $end; $i++) {
+        yield $i;
+    }
+};
+
+var_export(Wrap::iterable($range(0, PHP_INT_MAX))->slice(2, 4)->toArray());
+echo PHP_EOL;
+
+var_export(Wrap::iterable($range(0, PHP_INT_MAX))->slice(-1, 1)->toArray());
+echo PHP_EOL;
+
+var_export(Wrap::iterable($range(0, PHP_INT_MAX))->slice(0, 3)->toArray());
+echo PHP_EOL;
+
+var_export(Wrap::iterable($range(0, PHP_INT_MAX))->slice(5000, 2)->toArray());
+echo PHP_EOL;
diff --git a/make-examples.php b/make-examples.php
index 31ed7f3..d599276 100644
--- a/make-examples.php
+++ b/make-examples.php
@@ -3,6 +3,7 @@
 use doc\GW\Value\ReadmeWriter;
 use GW\Value\ArrayValue;
 use GW\Value\AssocValue;
+use GW\Value\IterableValue;
 use GW\Value\StringsArray;
 use GW\Value\StringValue;
 
@@ -13,6 +14,7 @@
     AssocValue::class,
     StringValue::class,
     StringsArray::class,
+    IterableValue::class,
 ]);
 
 file_put_contents('docs/examples.md', $markdown->toString());