Add Arrays::pad

README.md

@@ -75,6 +75,15 @@ $value = \TraderInteractive\Filter\Arrays::flatten([[1, 2], [3, [4, 5]]]);
 assert($value === [1, 2, 3, 4, 5]);
 ```
 
+#### Arrays::pad
+
+This filter pads an array to the specified length with a value. Padding optionally to the front or end of the array.
+
+```php
+$value = \TraderInteractive\Filter\Arrays::pad([1, 2], 5, 0, \TraderInteractive\Filter\Arrays::ARRAY_PAD_FRONT);
+assert($value === [0, 0, 0, 1, 2]);
+```
+
 ## Project Build
 
 With a checkout of the code get [Composer](http://getcomposer.org) in your PATH and run:

src/Arrays.php

@@ -2,13 +2,24 @@
 
 namespace TraderInteractive\Filter;
 
+use InvalidArgumentException;
 use TraderInteractive\Exceptions\FilterException;
 
 /**
  * A collection of filters for arrays.
  */
 final class Arrays
 {
+    /**
+     * @var int
+     */
+    const ARRAY_PAD_END = 1;
+
+    /**
+     * @var int
+     */
+    const ARRAY_PAD_FRONT = 2;
+
     /**
      * Filter an array by throwing if not an array or count not in the min/max range.
      *
@@ -149,4 +160,33 @@ public static function copy(array $source, array $keyMap) : array
 
         return $result;
     }
+
+    /**
+     * Pad array to the specified length with a value. Padding optionally to the front or end of the array.
+     *
+     * @param array $input    Initial array of values to pad.
+     * @param int   $size     The new size of the array.
+     * @param mixed $padValue Value to pad if $input is less than $size.
+     * @param int   $padType  Optional argument to specify which end of the array to pad.
+     *
+     * @return array Returns a copy of the $input array padded to size specified by $size with value $padValue
+     *
+     * @throws InvalidArgumentException Thrown if $padType is invalid.
+     */
+    public static function pad(array $input, int $size, $padValue = null, int $padType = self::ARRAY_PAD_END) : array
+    {
+        if ($padType === self::ARRAY_PAD_END) {
+            return array_pad($input, $size, $padValue);
+        }
+
+        if ($padType !== self::ARRAY_PAD_FRONT) {
+            throw new InvalidArgumentException('Invalid $padType value provided');
+        }
+
+        while (count($input) < $size) {
+            array_unshift($input, $padValue);
+        }
+
+        return $input;
+    }
 }

tests/ArraysTest.php

@@ -2,6 +2,7 @@
 
 namespace TraderInteractive\Filter;
 
+use InvalidArgumentException;
 use PHPUnit\Framework\TestCase;
 use TraderInteractive\Exceptions\FilterException;
 
@@ -198,4 +199,45 @@ public function copyEach()
             $result
         );
     }
+
+    /**
+     * @test
+     * @covers ::pad
+     */
+    public function pad()
+    {
+        $result = Arrays::pad([12, 10, 9], 5, 0);
+        $this->assertSame([12, 10, 9, 0, 0], $result);
+    }
+
+    /**
+     * @test
+     * @covers ::pad
+     */
+    public function padArrayLengthGreaterThanSize()
+    {
+        $result = Arrays::pad(['a', 'b', 'c'], 2, 0);
+        $this->assertSame(['a', 'b', 'c'], $result);
+    }
+
+    /**
+     * @test
+     * @covers ::pad
+     */
+    public function padFront()
+    {
+        $result = Arrays::pad(['a', 'b', 'c'], 5, null, Arrays::ARRAY_PAD_FRONT);
+        $this->assertSame([null, null, 'a', 'b', 'c'], $result);
+    }
+
+    /**
+     * @test
+     * @covers ::pad
+     */
+    public function padInvalidPadType()
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Invalid $padType value provided');
+        Arrays::pad(['a', 'b', 'c'], 5, null, 0);
+    }
 }