-selectRandomArrayElements method added along with tests

Author: coa

README.md

@@ -253,6 +253,17 @@ SimpleArrayLibrary::isSubArray(array(2, 1), array(2)); // true
 SimpleArrayLibrary::isSubArray(array('a' => 1, 'b' => array(1)), array('c' => 1)); // false
 SimpleArrayLibrary::isSubArray(array('a' => 1, 'b' => array(1)), array('a' => 2)); // false
 ```
+selectRandomArrayElements
+------------------------------
+Select sub-array of random elements. Keys association is preserved. If required number of random elements is equal or bigger then number
+of original array members, entire array is returned.
+
+Second parameter must be positive integer or string representation of the positive integer, otherwise exception is thrown.  
+```php
+SimpleArrayLibrary::selectRandomArrayElements(array('foo' => 2), 1); // array('foo' => 2)
+SimpleArrayLibrary::selectRandomArrayElements(array(1, 2), 1); // array(1) OR array(1 => 2)
+SimpleArrayLibrary::selectRandomArrayElements(array('foo' => 2, 'bar'), 3); // array('foo' => 2, 'bar')
+```
 setColumn
 ------------------------------
 Sets values to columns of the multi-dimensional array (is meant for two-dimensional arrays in particular, will work for three or more
@@ -265,4 +276,4 @@ exists
 SimpleArrayLibrary::setColumn(array(array('foo' => 2), array()), 'foo', 1); // array(array('foo' => 1), array('foo' => 1))
 SimpleArrayLibrary::setColumn(array(array('foo' => 2), array()), 'foo', 1, false, false); // array(array('foo' => 2), array())
 SimpleArrayLibrary::setColumn(array(array('foo' => 2), array()), 'foo', 1, true, false); // array(array('foo' => 2), array('foo' => 1))
-```
+```

src/SimpleArrayLibrary.php

@@ -455,6 +455,34 @@ public static function isSubArray(array $array, array $subArray, $strictComparis
         return $return;
     }
 
+    /**
+     * Selects random sub array
+     *
+     * @param array $array
+     * @param int $numberOfRequiredElements
+     *
+     * @return array
+     * @throws InvalidArgumentException
+     */
+    public static function selectRandomArrayElements(array $array, $numberOfRequiredElements)
+    {
+        // validation, must be positive int or 0
+        if (!preg_match('/^[1-9]\d*$/', $numberOfRequiredElements)) {
+            throw new InvalidArgumentException('Number of requested elements parameter must be a positive integer');
+        }
+
+        $selected = $array;
+        if (count($array) > $numberOfRequiredElements) {
+            // select required number of random keys
+            $selectedKeys = array_rand($array, $numberOfRequiredElements);
+            $selectedKeys = $numberOfRequiredElements == 1 ? [$selectedKeys] : $selectedKeys;
+            // select only array members with selected random keys
+            $selected = array_intersect_key($array, array_fill_keys($selectedKeys, null));
+        }
+
+        return $selected;
+    }
+
     /**
      * @param array $matrix
      * @param mixed $column

test/SimpleArrayLibrary/SelectRandomArrayElementsTest.php

@@ -0,0 +1,55 @@
+<?php
+
+use SimpleArrayLibrary\SimpleArrayLibrary;
+
+class SelectRandomArrayElementsTest extends PHPUnit_Framework_TestCase
+{
+    /**
+     * @dataProvider getData
+     */
+    public function testMethod($array, $expected)
+    {
+        // arrange
+        $requestedNumberOfElements = 2;
+
+        // act
+        $result = SimpleArrayLibrary::selectRandomArrayElements($array, $requestedNumberOfElements);
+
+        // assert
+        if (count($expected) > $requestedNumberOfElements) {
+            $this->assertCount(2, $result);
+            $this->assertArraySubset($result, $expected);
+        } else {
+            $this->assertEquals($expected, $result);
+        }
+    }
+
+    /**
+     * @return array
+     */
+    public function getData()
+    {
+        return [
+            // #0 empty array
+            [
+                'array' => [],
+                'expected' => [],
+            ],
+            // #1 fewer elements requested then array contains
+            [
+                'array' => [1],
+                'expected' => [1],
+            ],
+            // #2 same number of elements requested as array contains
+            [
+                'array' => [1, 2],
+                'expected' => [1, 2],
+            ],
+            // #3 more elements requested then array contains
+            [
+                'array' => [1, 2, 3],
+                'expected' => [1, 2, 3],
+            ],
+        ];
+    }
+}

test/SimpleArrayLibrary/SelectRandomArrayElementsXTest.php

@@ -0,0 +1,47 @@
+<?php
+
+use SimpleArrayLibrary\SimpleArrayLibrary;
+
+class SelectRandomArrayElementsXTest extends PHPUnit_Framework_TestCase
+{
+    /**
+     * @dataProvider getData
+     *
+     * @return void
+     */
+    public function test_function(array $data)
+    {
+        // prepare
+        $this->setExpectedException('InvalidArgumentException', 'Number of requested elements parameter must be a positive integer');
+
+        // invoke logic & test
+        SimpleArrayLibrary::selectRandomArrayElements(array(1), $data['numberOfRequiredElements']);
+    }
+
+    /**
+     * @return array
+     */
+    public function getData()
+    {
+        return array(
+            // #0 negative integer
+            array(
+                array(
+                    'numberOfRequiredElements' => -1
+                )
+            ),
+            // #1 zero
+            array(
+                array(
+                    'numberOfRequiredElements' => 0
+                )
+            ),
+            // #2 not an integer
+            array(
+                array(
+                    'numberOfRequiredElements' => 'foo'
+                )
+            )
+        );
+    }
+}