Add documentation.

docs/pages/api.rst

@@ -4,9 +4,11 @@ API
 append
 ------
 
+Add one or more items to a collection.
+
 Interface: `Appendable`_
 
-Signature: Collection::append(...$items);
+Signature: ``Collection::append(...$items);``
 
 .. code-block:: php
 
@@ -18,31 +20,152 @@ Signature: Collection::append(...$items);
     $this
         ->append('5', '6'); // ['1', '2', '3', '5', '6']
 
-
 apply
 -----
 
+Execute a callback for each element of the collection without
+altering the collection item itself.
+
+If the callback does not return `true` then it stops.
+
+Interface: `Applyable`_
+
+Signature: ``Collection::apply(...$callbacks);``
+
+.. code-block:: php
+
+    $callback = static function ($value, $key): bool
+        {
+            var_dump('Value is: ' . $value . ', key is: ' . $key);
+
+            return true;
+        };
+
+    $collection = Collection::with(['1', '2', '3']);
+
+    $collection
+        ->apply($callback);
+
 chunk
 -----
 
+Chunk a collection of item into chunks of items of a given size.
+
+Interface: `Chunkable`_
+
+Signature: ``Collection::chunk(int $size);``
+
+.. code-block:: php
+
+    $collection = Collection::with(range(0, 10));
+
+    $collection->chunk(2);
+
 collapse
 --------
 
-combine
--------
+Collapse a collection of items into a simple flat collection.
+
+Interface: `Collapseable`_
+
+Signature: ``Collection::collapse();``
+
+.. code-block:: php
+
+    $collection = Collection::with([[1,2], [3, 4]]);
+
+    $collection->collapse();
 
 combinate
 ---------
 
+Get all the combinations of a given length of a collection of items.
+
+Interface: `Combinateable`_
+
+Signature: ``Collection::combinate(?int $length);``
+
+.. code-block:: php
+
+    $collection = Collection::with(['a', 'b', 'c', 'd'])
+        ->combinate(3);
+
+combine
+-------
+
+Combine a collection of items with some other keys.
+
+Interface: `Combineable`_
+
+Signature: ``Collection::combine(...$keys);``
+
+.. code-block:: php
+
+    $collection = Collection::with(['a', 'b', 'c', 'd'])
+        ->combine('w', 'x', 'y', 'z')
+
+cycle
+-----
+
+Cycle around a collection of items.
+
+Interface: `Cycleable`_
+
+Signature: ``Collection::cycle(int $length = 0);``
+
+.. code-block:: php
+
+    $collection = Collection::with(['a', 'b', 'c', 'd'])
+        ->cycle(10)
+
 distinct
 --------
 
+Remove duplicated values from a collection.
+
+Interface: `Distinctable`_
+
+Signature: ``Collection::distinct();``
+
+.. code-block:: php
+
+    $collection = Collection::with(['a', 'b', 'c', 'd', 'a'])
+        ->distinct()
+
 explode
 -------
 
+Explode a collection into subsets based on a given value.
+
+Interface: `Explodeable`_
+
+Signature: ``Collection::explode(...$items);``
+
+.. code-block:: php
+
+    $string = 'I am just a random piece of text.';
+
+    $collection = Collection::with($string)
+        ->explode('o');
+
 filter
 ------
 
+Filter collection items based on one or more callbacks.
+
+Interface: `Filterable`_
+
+Signature: ``Collection::filter(callable ...$callbacks);``
+
+.. code-block:: php
+
+    $callback = static function($value): bool {
+        return 0 === $value % 3;
+    };
+
+    $collection = Collection::with(range(1, 100))
+        ->filter($callback);
+
 flatten
 -------
 
@@ -121,4 +244,13 @@ walk
 zip
 ---
 
-.. _Appendable: https://github.com/loophp/collection/blob/master/src/Contract/Appendable.php
+.. _Appendable: https://github.com/loophp/collection/blob/master/src/Contract/Appendable.php
+.. _Applyable: https://github.com/loophp/collection/blob/master/src/Contract/Applyable.php
+.. _Chunkable: https://github.com/loophp/collection/blob/master/src/Contract/Chunkable.php
+.. _Collapseable: https://github.com/loophp/collection/blob/master/src/Contract/Collapseable.php
+.. _Combinateable: https://github.com/loophp/collection/blob/master/src/Contract/Combinateable.php
+.. _Combineable: https://github.com/loophp/collection/blob/master/src/Contract/Combineable.php
+.. _Cycleable: https://github.com/loophp/collection/blob/master/src/Contract/Cycleable.php
+.. _Distinctable: https://github.com/loophp/collection/blob/master/src/Contract/Distinctable.php
+.. _Explodeable: https://github.com/loophp/collection/blob/master/src/Contract/Explodeable.php
+.. _Filterable: https://github.com/loophp/collection/blob/master/src/Contract/Filterable.php

docs/pages/examples.rst

@@ -53,30 +53,101 @@ Approximate the number Pi
 
     use loophp\collection\Collection;
 
-    $iterations = 100000;
-
-    $monteCarloMethod = static function ($in = 0) {
-        $randomNumber1 = mt_rand() / mt_getrandmax();
-        $randomNumber2 = mt_rand() / mt_getrandmax();
+    $monteCarloMethod = static function ($in = 0, $total = 1) {
+        $randomNumber1 = mt_rand(0, mt_getrandmax() - 1) / mt_getrandmax();
+        $randomNumber2 = mt_rand(0, mt_getrandmax() - 1) / mt_getrandmax();
 
         if (1 >= (($randomNumber1 ** 2) + ($randomNumber2 ** 2))) {
             ++$in;
         }
 
-        return $in;
+        return ['in' => $in, 'total' => ++$total];
+    };
+
+    $precision = new class() {
+
+        /**
+         * @var array
+         */
+        private $state;
+
+        /**
+         * @var float
+         */
+        private $precision;
+
+        /**
+         * @var int
+         */
+        private $row;
+
+        /**
+         * Precision constructor.
+         *
+         * @param float $precision
+         * @param int $row
+         */
+        public function __construct(float $precision = 10 ** -5, int $row = 20)
+        {
+            $this->precision = $precision;
+            $this->row = $row;
+            $this->state = [
+                'prev' => null,
+                'found' => 0,
+            ];
+        }
+
+        /**
+         * @param float $value
+         *
+         * @return bool
+         */
+        public function __invoke(float $value): bool
+        {
+            if (null === $this->state['prev']) {
+                $this->state['prev'] = $value;
+                $this->state['found'] = 0;
+
+                return false;
+            }
+
+            if ($value === $this->state['prev']) {
+                $this->state['found'] = 0;
+
+                return false;
+            }
+
+            if (abs($value - $this->state['prev']) <= $this->precision) {
+                ++$this->state['found'];
+
+                return false;
+            }
+
+            if ($this->state['found'] >= $this->row) {
+                $this->state['found'] = 0;
+
+                return true;
+            }
+
+            $this->state['prev'] = $value;
+            $this->state['found'] = 0;
+
+            return false;
+        }
     };
 
     $pi_approximation = Collection::iterate($monteCarloMethod)
-        ->limit($iterations)
-        ->tail()
         ->map(
-            static function ($value) use ($iterations) {
-                return 4 * $value / $iterations;
+            static function ($value) {
+                return 4 * $value['in'] / $value['total'];
             }
         )
-        ->first();
+        ->nth(50)
+        ->until($precision)
+        ->last();
+
+    print_r($pi_approximation);
 
-    var_dump($pi_approximation); // 3.1416764444444
 
 Find Prime numbers
 ------------------