Add take_left() and take_right() (#192)

composer.json

@@ -105,6 +105,8 @@
             "src/Functional/Tap.php",
             "src/Functional/Tail.php",
             "src/Functional/TailRecursion.php",
+            "src/Functional/TakeLeft.php",
+            "src/Functional/TakeRight.php",
             "src/Functional/True.php",
             "src/Functional/Truthy.php",
             "src/Functional/Unique.php",

docs/functional-php.md

@@ -17,7 +17,7 @@
   - [truthy() & falsy()](#truthy--falsy)
   - [contains()](#contains)
   - [sort()](#sort)
-  - [Other:](#other)
+  - [Other](#other)
 - [Partial application](#partial-application)
   - [Introduction](#introduction)
   - [partial_left() & partial_right()](#partial_left--partial_right)
@@ -37,6 +37,8 @@
   - [last_index_of()](#last_index_of)
   - [indexes_of()](#indexes_of)
   - [select_keys()](#select_keys)
+  - [take_left()](#take_left)
+  - [take_right()](#take_right)
 - [Function functions](#function-functions)
   - [retry()](#retry)
   - [poll()](#poll)
@@ -267,7 +269,7 @@ sort($collection, function($user1, $user2) {
 ```
 
 
-## Other:
+## Other
 
 `void Functional\each(array|Traversable $collection, callable $callback)`
 Applies a callback to each element
@@ -627,6 +629,29 @@ use function Functional\select_keys;
 $array = select_keys(['foo' => 1, 'bar' => 2', 'baz' => 3], ['foo', 'baz']);
 ```
 
+## take_left()
+
+Creates a slice of `$collection` with `$count` elements taken from the beginning. If the collection has less than `$count` elements, the whole collection will be returned as an array.
+
+``array Functional\take_left(Traversable|array $collection, int $count)``
+
+```php
+Functional\take_left([1, 2, 3], 2); // [1, 2]
+```
+
+## take_right()
+
+Creates a slice of `$collection` with `$count` elements taken from the end. If the collection has less than `$count` elements, the whole collection will be returned as an array.
+
+This function will reorder and reset the integer array indices by default. This behaviour can be changed by setting `$preserveKeys` to `true`. String keys are always preserved, regardless of this parameter.
+
+``array Functional\take_right(Traversable|array $collection, int $count, bool $preserveKeys = false)``
+
+```php
+Functional\take_right([1, 2, 3], 2); // [2, 3]
+Functional\take_right(['a', 'b', 'c'], 2, true); // [1 => 'b', 2 => 'c']
+```
+
 # Function functions
 
 Function functions take a function or functions and return a new, modified version of the function.

src/Functional/Functional.php

@@ -409,6 +409,16 @@ final class Functional
      */
     const tail_recursion = '\Functional\tail_recursion';
 
+    /**
+     * @see \Functional\take_left
+     */
+    const take = '\Functional\take_left';
+
+    /**
+     * @see \Functional\take_right
+     */
+    const take_right = '\Functional\take_right';
+
     /**
      * @see \Functional\tap
      */

src/Functional/TakeLeft.php

@@ -0,0 +1,47 @@
+<?php
+/**
+ * Copyright (C) 2011-2017 by Lars Strojny <lstrojny@php.net>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+namespace Functional;
+
+use Functional\Exceptions\InvalidArgumentException;
+use Traversable;
+
+/**
+ * Creates a slice of $collection with $count elements taken from the beginning. If the collection has less than $count
+ * elements, the whole collection will be returned as an array.
+ *
+ * @param Traversable|array $collection
+ * @param int $count
+ *
+ * @return array
+ */
+function take_left($collection, $count)
+{
+    InvalidArgumentException::assertCollection($collection, __FUNCTION__, 1);
+    InvalidArgumentException::assertPositiveInteger($count, __FUNCTION__, 2);
+
+    return \array_slice(
+        \is_array($collection) ? $collection : \iterator_to_array($collection),
+        0,
+        $count
+    );
+}

src/Functional/TakeRight.php

@@ -0,0 +1,51 @@
+<?php
+/**
+ * Copyright (C) 2011-2017 by Lars Strojny <lstrojny@php.net>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+namespace Functional;
+
+use Functional\Exceptions\InvalidArgumentException;
+use Traversable;
+
+/**
+ * Creates a slice of $collection with $count elements taken from the end. If the collection has less than $count
+ * elements, the whole collection will be returned as an array.
+ * This function will reorder and reset the integer array indices by default. This behaviour can be changed by setting
+ * preserveKeys to TRUE. String keys are always preserved, regardless of this parameter.
+ *
+ * @param Traversable|array $collection
+ * @param int $count
+ * @param bool $preserveKeys
+ *
+ * @return array
+ */
+function take_right($collection, $count, $preserveKeys = false)
+{
+    InvalidArgumentException::assertCollection($collection, __FUNCTION__, 1);
+    InvalidArgumentException::assertPositiveInteger($count, __FUNCTION__, 2);
+
+    return \array_slice(
+        \is_array($collection) ? $collection : \iterator_to_array($collection),
+        0 - $count,
+        $count,
+        $preserveKeys
+    );
+}

tests/Functional/TakeLeftTest.php

@@ -0,0 +1,53 @@
+<?php
+/**
+ * Copyright (C) 2011-2017 by Lars Strojny <lstrojny@php.net>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+namespace Functional\Tests;
+
+use ArrayIterator;
+use function Functional\each;
+use function Functional\take_left;
+
+class TakeLeftTest extends AbstractTestCase
+{
+    public function setUp()
+    {
+        parent::setUp();
+
+        $this->list = ['foo', 'bar', 'baz', 'qux'];
+        $this->listIterator = new ArrayIterator($this->list);
+    }
+
+    public function test()
+    {
+        each([$this->list, $this->listIterator], function ($list) {
+            $this->assertSame(['foo'], take_left($list, 1));
+            $this->assertSame(['foo', 'bar'], take_left($list, 2));
+            $this->assertSame(['foo', 'bar', 'baz', 'qux'], take_left($list, 10));
+            $this->assertSame([], take_left($list, 0));
+
+            $this->expectExceptionMessage(
+                'Functional\take_left() expects parameter 2 to be positive integer, negative integer given'
+            );
+            take_left($list, -1);
+        });
+    }
+}

tests/Functional/TakeRightTest.php

@@ -0,0 +1,65 @@
+<?php
+/**
+ * Copyright (C) 2011-2017 by Lars Strojny <lstrojny@php.net>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+namespace Functional\Tests;
+
+use ArrayIterator;
+use function Functional\each;
+use function Functional\take_right;
+
+class TakeRightTest extends AbstractTestCase
+{
+    public function setUp()
+    {
+        parent::setUp();
+
+        $this->list = ['foo', 'bar', 'baz', 'qux'];
+        $this->listIterator = new ArrayIterator($this->list);
+    }
+
+    public function test()
+    {
+        each([$this->list, $this->listIterator], function ($list) {
+            $this->assertSame(['qux'], take_right($list, 1));
+            $this->assertSame(['baz', 'qux'], take_right($list, 2));
+            $this->assertSame(['foo', 'bar', 'baz', 'qux'], take_right($list, 10));
+            $this->assertSame([], take_right($list, 0));
+
+            $this->expectExceptionMessage(
+                'Functional\take_right() expects parameter 2 to be positive integer, negative integer given'
+            );
+            take_right($list, -1);
+        });
+    }
+
+    public function testPreserveKeys()
+    {
+        each([$this->list, $this->listIterator], function ($list) {
+            $this->assertSame([3 => 'qux'], take_right($list, 1, true));
+            $this->assertSame([2 => 'baz', 3 => 'qux'], take_right($list, 2, true));
+
+            // "special" cases should behave the same as with $preserveKeys = false
+            $this->assertSame(['foo', 'bar', 'baz', 'qux'], take_right($list, 10, true));
+            $this->assertSame([], take_right($list, 0, true));
+        });
+    }
+}