Add identity function (#80)

* Changed constant function name to identity

* Added the behaviour of real identity function

* Fixed a typo

* Changed identity function description

* Changed identity function example

* Changed identity function description

* Changed identity function description in index

* Improve identity tests

Author: rgomezcasas

docs/docs.md

@@ -22,6 +22,7 @@
  * [get_in](functions/get_in.md): Returns the value in a nested associative structure or a default value in the case it does not exists
  * [group_by](functions/group_by.md): Returns an array with the items grouped by the results of applying a function to each item
  * [key](functions/key.md): Returns the key of an item value in a collection or a default value in the case it does not exists
+ * [identity](functions/identity.md): Returns the same value that is passed as argument
  * [instance_of](functions/instance_of.md): Returns a checker that validated if an element is an instance of a class
  * [last](functions/last.md): Returns the last element of a collection
  * [map](functions/map.md): Apply a function over all the items of a collection and returns an array with the results

docs/functions/identity.md

@@ -0,0 +1,28 @@
+# identity
+
+## Description
+
+Identity function is a function which return the same value that is passed as argument. `f(x) = x`
+
+## Parameters
+
+<dl>
+  <dt>value</dt>
+  <dd>Any type of value that will be returned</dd>
+</dl>
+
+## Examples
+
+Do you want to check if an array of booleans has a at least a true value:
+
+```php
+<?php
+
+use function Lambdish\Phunctional\any;
+
+$values = [false, false, true, false];
+
+any('Lambdish\Phunctional\identity', $values);
+
+// => true
+```

src/_bootstrap.php

@@ -20,6 +20,7 @@
 require __DIR__ . '/get_in.php';
 require __DIR__ . '/group_by.php';
 require __DIR__ . '/key.php';
+require __DIR__ . '/identity.php';
 require __DIR__ . '/instance_of.php';
 require __DIR__ . '/last.php';
 require __DIR__ . '/map.php';

src/identity.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Lambdish\Phunctional;
+
+/**
+ * Identity function is a function which return the same value that is passed as argument. `f(x) = x`
+ *
+ * @since v1.0.9
+ *
+ * @param mixed $argument any type of value
+ *
+ * @return mixed
+ */
+function identity($argument)
+{
+    return $argument;
+}

tests/IdentityTest.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Lambdish\Phunctional\Tests;
+
+use PHPUnit_Framework_TestCase;
+use stdClass;
+use function Lambdish\Phunctional\identity;
+
+final class IdentityTest extends PHPUnit_Framework_TestCase
+{
+    /**
+     * @test
+     * @dataProvider values()
+     */
+    public function it_should_return_a_same_value_is_passed_as_argument($value)
+    {
+        $this->assertSame($value, identity($value));
+    }
+
+    public function values()
+    {
+        return [
+            [1],
+            [9],
+            [0],
+            ['a'],
+            ['b'],
+            ['some text'],
+            [new stdClass()],
+            [[]],
+            [['test', 'array']],
+            [null],
+        ];
+    }
+}