Add constant function (#72)

* Added constant function

* Changed constant function description

* Fixed a typo in tests

* Changed constant function name to identity

* Revert "Changed constant function name to identity"

This reverts commit e2bfdb2.

* Fixed wrong description on constant function documentation

* Some coding style fixes

* Update docs/functions/constant.md

Co-Authored-By: fnandot <5954976+fnandot@users.noreply.github.com>

* Update docs/functions/constant.md

Co-Authored-By: fnandot <5954976+fnandot@users.noreply.github.com>

docs/docs.md

@@ -9,6 +9,7 @@
  * [butlast](functions/butlast.md):  Returns all the elements of a collection except the last preserving the keys
  * [complement](functions/complement.md): Returns another function that takes the same arguments and has the opposite truth value.
  * [compose](functions/compose.md): Combine multiple function calls in one function
+ * [constant](functions/constant.md): It wraps a value into a Closure, which return the same value whenever is called
  * [dissoc](functions/dissoc.md): Dissociate a value of a key in a collection
  * [do_if](functions/do_if.md): Returns a callable that will call the given function if the result of applying the callable arguments to the predicates is true for all of them
  * [each](functions/each.md): Apply a function over all the items of a collection

docs/functions/constant.md

@@ -0,0 +1,29 @@
+# constant
+
+## Description
+
+It wraps a value into a closure, which return the same value that is passed as argument whenever is called.
+
+## Parameters
+
+<dl>
+  <dt>value</dt>
+  <dd>Any type of value that will be returned</dd>
+</dl>
+
+## Examples
+
+Fill an existing array with zeros:
+
+```php
+<?php
+
+use function Lambdish\Phunctional\map;
+use function Lambdish\Phunctional\constant;
+
+$numbers = [1, 2, 3, 4, 5];
+
+map(constant(0), $numbers);
+
+// => [0, 0, 0, 0, 0]
+```

src/_bootstrap.php

@@ -7,6 +7,7 @@
 require __DIR__ . '/butlast.php';
 require __DIR__ . '/complement.php';
 require __DIR__ . '/compose.php';
+require __DIR__ . '/constant.php';
 require __DIR__ . '/dissoc.php';
 require __DIR__ . '/do_if.php';
 require __DIR__ . '/each.php';

src/constant.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Lambdish\Phunctional;
+
+/**
+ * It wraps a value into a Closure, which return the same value whenever is called
+ *
+ * @since v1.0.7
+ *
+ * @param mixed $value any type of value
+ *
+ * @return \Closure
+ */
+function constant($value)
+{
+    return function () use ($value) {
+        return $value;
+    };
+}

tests/ConstantTest.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Lambdish\Phunctional\Tests;
+
+use PHPUnit_Framework_TestCase;
+use function Lambdish\Phunctional\constant;
+
+final class ConstantTest extends PHPUnit_Framework_TestCase
+{
+    /** @test */
+    public function it_should_return_a_value()
+    {
+        $value           = 5;
+        $constantClosure = constant($value);
+
+        $this->assertSame($value, $constantClosure());
+    }
+
+    /** @test */
+    public function it_should_return_same_value_if_called_twice()
+    {
+        $value           = 5;
+        $constantClosure = constant($value);
+
+        $constantClosure();
+
+        $this->assertSame($value, $constantClosure());
+    }
+}