Merge branch 'petemcfarlane-add-transpose-method'

README.md

@@ -1348,6 +1348,26 @@ Collection::from([])->toString(); //''
 toString([1, 'a', 3, null]); //'1a3'
 ```
 
+#### transpose(array|Traversable $collection) : string
+Returns a non-lazy collection by interchanging each row and the corresponding column. The input must be a multi-dimensional collection or an InvalidArgumentException is thrown.
+```php
+$arr = Collection::from([
+    [1, 2, 3],
+    new Collection([4, 5, new Collection(['foo', 'bar'])]),
+    new Collection([7, 8, 9]),
+])->transpose()->toArray();
+
+// $arr =
+// [
+//    new Collection([1, 4, 7]),
+//    new Collection([2, 5, 8]),
+//    new Collection([3, new Collection(['foo', 'bar']), 9]),
+// ]
+```
+```php
+toString([1, 'a', 3, null]); //'1a3'
+```
+
 #### zip(array|Traversable[] ...$collections) : Collection
 Returns a lazy collection of non-lazy collections of items from nth position from this collection and each passed collection. Stops when any of the collections don't have an item at the nth position.
 ```php

src/CollectionTrait.php

@@ -734,6 +734,17 @@ public function transform(callable $transformer)
         return $transformed;
     }
 
+    /**
+     * Transpose each item in a collection, interchanging the row and column indexes.
+     * Can only transpose multi-dimensional arrays or collections. Otherwise an InvalidArgument is raised.
+     *
+     * @return Collection
+     */
+    public function transpose()
+    {
+        return transpose($this->getItems());
+    }
+
     /**
      * Extracts data from collection items by dot separated key path. Supports the * wildcard.  If a key contains \ or
      * it must be escaped using \ character.

src/collection_functions.php

@@ -2,12 +2,13 @@
 
 namespace DusanKasan\Knapsack;
 
+use DusanKasan\Knapsack\Exceptions\InvalidArgument;
 use DusanKasan\Knapsack\Exceptions\ItemNotFound;
 use DusanKasan\Knapsack\Exceptions\NoMoreItems;
 use Traversable;
 
 /**
-     * Converts $collection to array. If there are multiple items with the same key, only the last will be preserved.
+ * Converts $collection to array. If there are multiple items with the same key, only the last will be preserved.
  *
  * @param array|Traversable $collection
  * @return array
@@ -77,11 +78,11 @@ function reverse($collection)
         return map(
             indexBy(
                 array_reverse($array),
-                function($item) {
+                function ($item) {
                     return $item[0];
                 }
             ),
-            function($item) {
+            function ($item) {
                 return $item[1];
             }
         );
@@ -251,9 +252,10 @@ function filter($collection, callable $function = null)
 {
     if (null === $function) {
         $function = function ($value) {
-            return (bool)$value;
+            return (bool) $value;
         };
-    };
+    }
+    ;
 
     $generatorFactory = function () use ($collection, $function) {
         foreach ($collection as $key => $value) {
@@ -414,7 +416,6 @@ function groupBy($collection, callable $function)
     return Collection::from($result);
 }
 
-
 /**
  * Returns a non-lazy collection of items grouped by the value at given key. Ignores non-collection items and items
  * without the given keys
@@ -434,7 +435,7 @@ function ($item) use ($key) {
                     return isCollection($item) && has($item, $key);
                 }
             ),
-            function($value) use ($key) {
+            function ($value) use ($key) {
                 return get($value, $key);
             }
         );
@@ -684,7 +685,7 @@ function reject($collection, callable $function)
 {
     return filter(
         $collection,
-        function($value, $key) use ($function) {
+        function ($value, $key) use ($function) {
             return !$function($value, $key);
         }
     );
@@ -1011,7 +1012,7 @@ function partition($collection, $numberOfItems, $step = -1, $padding = [])
                 yield dereferenceKeyValue($buffer);
 
                 $buffer = array_slice($buffer, $tmpStep);
-                $itemsToSkip =  $tmpStep - $numberOfItems;
+                $itemsToSkip = $tmpStep - $numberOfItems;
             }
 
             if ($itemsToSkip <= 0) {
@@ -1098,7 +1099,7 @@ function range($start = 0, $end = null, $step = 1)
     $generatorFactory = function () use ($start, $end, $step) {
         return iterate(
             $start,
-            function($value) use ($step, $end) {
+            function ($value) use ($step, $end) {
                 $result = $value + $step;
 
                 if ($end !== null && $result > $end) {
@@ -1137,7 +1138,7 @@ function duplicate($input)
         return toArray(
             map(
                 $input,
-                function($i) {
+                function ($i) {
                     return duplicate($i);
                 }
             )
@@ -1197,7 +1198,6 @@ function second($collection)
     return get(values($collection), 1);
 }
 
-
 /**
  * Combines $keys and $values into a lazy collection. The resulting collection has length equal to the size of smaller
  * argument.
@@ -1384,6 +1384,35 @@ function zip(...$collections)
     return new Collection($generatorFactory);
 }
 
+/**
+ * Transpose each item in a collection, interchanging the row and column indexes.
+ * Can only transpose collections of collections. Otherwise an InvalidArgument is raised.
+ *
+ * @param Collection $collection
+ * @return Collection
+ */
+function transpose($collection)
+{
+    if (some($collection, function ($value) {
+        return !($value instanceof Collection);
+    })) {
+        throw new InvalidArgument('Can only transpose collections of collections.');
+    }
+    return Collection::from(
+        array_map(
+            function (...$items) {
+                return new Collection($items);
+            },
+            ...toArray(
+                map(
+                    $collection,
+                    'DusanKasan\Knapsack\toArray'
+                )
+            )
+        )
+    );
+}
+
 /**
  * Returns a lazy collection of data extracted from $collection items by dot separated key path. Supports the *
  * wildcard. If a key contains \ or * it must be escaped using \ character.
@@ -1418,7 +1447,6 @@ function extract($collection, $keyPath)
         }
     };
 
-
     return new Collection($generatorFactory);
 }