Add ary function which ignores arguments over the supplied number

composer.json

@@ -25,6 +25,7 @@
     "autoload": {
         "psr-4": {"Functional\\": "src/Functional"},
         "files": [
+            "src/Functional/Ary.php",
             "src/Functional/Average.php",
             "src/Functional/ButLast.php",
             "src/Functional/Capture.php",

docs/functional-php.md

@@ -356,6 +356,26 @@ $partiallyAppliedSubtractor = partial_right($subtractor, 10);
 $partiallyAppliedSubtractor(20); // -> 10
 ```
 
+## ary()
+
+`Functional\ary` (as in arity) takes a `callable` and a count and calls the `callable` with 
+that many arguments using `take_left` if positive, or `take_right` if negative. 
+Throws if passed 0.
+
+For example:
+
+```php
+use function Functional\ary;
+use function Functional\map;
+
+# This fails because map calls it's callable with the element, 
+# index and the whole collection
+# map($array, 'ucfirst');
+
+# Using `ary`
+map($array, ary('ucfirst', 1')); # Passes only the first argument to `ucfirst`
+```
+
 ## partial_any()
 
 There is a third function in the family called `partial_any`. Unlike its siblings it doesn’t automatically merge but it

src/Functional/Ary.php

@@ -0,0 +1,31 @@
+<?php
+
+/**
+ * @package   Functional-php
+ * @author    Hugo Sales <hugo@fc.up.pt>
+ * @copyright 2020 Hugo Sales
+ * @license   https://opensource.org/licenses/MIT MIT
+ * @link      https://github.com/lstrojny/functional-php
+ */
+
+namespace Functional;
+
+use Functional\Exceptions\InvalidArgumentException;
+use Traversable;
+
+/**
+ * Call $func with only abs($count) arguments, taken either from the
+ * left or right depending on the sign
+ */
+function ary(callable $func, int $count): callable
+{
+    InvalidArgumentException::assertNonZeroInteger($count, __FUNCTION__);
+
+    return function (...$args) use ($func, $count) {
+        if ($count > 0) {
+            return $func(...take_left($args, $count));
+        } else if ($count < 0) {
+            return $func(...take_right($args, -$count));
+        }
+    };
+}

src/Functional/Exceptions/InvalidArgumentException.php

@@ -280,6 +280,13 @@ private static function assertCollectionAlike($collection, $className, $callee,
         }
     }
 
+    public static function assertNonZeroInteger($value, $callee)
+    {
+        if (!\is_int($value) || $value == 0) {
+            throw new static(\sprintf('%s expected parameter %d to be non-zero', $callee, $value));
+        }
+    }
+
     private static function getType($value)
     {
         return \is_object($value) ? \get_class($value) : \gettype($value);

src/Functional/Functional.php

@@ -12,6 +12,12 @@
 
 final class Functional
 {
+
+    /**
+     * @see \Function\ary
+     */
+    const ary = '\Functional\ary';
+
     /**
      * @see \Functional\average
      */

tests/Functional/AryTest.php

@@ -0,0 +1,41 @@
+<?php
+
+/**
+ * @package   Functional-php
+ * @author    Hugo Sales <hugo@fc.up.pt>
+ * @copyright 2020 Hugo Sales
+ * @license   https://opensource.org/licenses/MIT MIT
+ * @link      https://github.com/lstrojny/functional-php
+ */
+
+namespace Functional\Tests;
+
+use function Functional\ary;
+use Functional\Exceptions\InvalidArgumentException;
+
+class AryTest extends AbstractTestCase
+{
+
+    public function test()
+    {
+        $f = function ($a = 0, $b = 0, $c = 0) {
+            return $a + $b + $c;
+        };
+
+        $this->assertSame(5, $f(5));
+        $this->assertSame(5, ary($f, 1)(5));
+        $this->assertSame(5, ary($f, 1)(5));
+        $this->assertSame(6, ary($f, -1)(6));
+        $this->assertSame(7, ary($f, 2)(5, 2));
+    }
+
+    public function testException()
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $f = function ($a = 0, $b = 0, $c = 0) {
+            return $a + $b + $c;
+        };
+
+        ary($f, 0)(5);
+    }
+}