Implemented unflatten() method

Author: aimeos

README.md

@@ -286,6 +286,7 @@ will return:
 <a href="#uasorted">uasorted</a>
 <a href="#uksort">uksort</a>
 <a href="#uksorted">uksorted</a>
+<a href="#unflatten">unflatten</a>
 <a href="#union">union</a>
 <a href="#unique">unique</a>
 <a href="#unshift">unshift</a>
@@ -498,6 +499,7 @@ will return:
 * [transpose()](#transpose) : Exchanges rows and columns for a two dimensional map
 * [traverse()](#traverse) : Traverses trees of nested items passing each item to the callback
 * [trim()](#trim) : Removes the passed characters from the left/right of all strings
+* [unflatten()](#unflatten) : Unflattens the key path/value pairs into a multi-dimensional array
 * [walk()](#walk) : Applies the given callback to all elements
 * [zip()](#zip) : Merges the values of all arrays at the corresponding index
 
@@ -6965,6 +6967,32 @@ Map::from( ['B' => 'a', 'a' => 'b'] )->uksorted( function( $keyA, $keyB ) {
 * [uksort()](#uksort) - Sorts the map elements by their keys using a callback
 
 
+### unflatten()
+
+Unflattens the key path/value pairs into a multi-dimensional array.
+
+```php
+public function unflatten() : self
+```
+
+* @return **self&#60;string,mixed&#62;** New map with multi-dimensional arrays
+
+**Examples:**
+
+```php
+Map::from( ['a/b/c' => 1, 'a/b/d' => 2, 'b/e' => 3] )->unflatten();
+// ['a' => ['b' => ['c' => 1, 'd' => 2]], 'b' => ['e' => 3]]
+
+Map::from( ['a.b.c' => 1, 'a.b.d' => 2, 'b.e' => 3] )->sep( '.' )->unflatten();
+// ['a' => ['b' => ['c' => 1, 'd' => 2]], 'b' => ['e' => 3]]
+```
+
+**See also:**
+
+* [flat()](#flat) - Flattens multi-dimensional elements without overwriting elements
+* [collapse()](#collapse) - Collapses all sub-array elements recursively to a new map
+
+
 ### union()
 
 Builds a union of the elements and the given elements without returning a new map.

src/Map.php

@@ -4254,7 +4254,7 @@ public function search( $value, $strict = true )
 	 * delimiter() method instead.
 	 *
 	 * Examples:
-	 *  Map::from( ['foo' => ['bar' => 'baz']] )->sep( '/' )->get( 'foo/bar' );
+	 *  Map::from( ['foo' => ['bar' => 'baz']] )->sep( '.' )->get( 'foo.bar' );
 	 *
 	 * Results:
 	 *  'baz'
@@ -5800,6 +5800,38 @@ public function uksorted( callable $callback ) : self
 	}
 
 
+	/**
+	 * Unflattens the key path/value pairs into a multi-dimensional array.
+	 *
+	 * Examples:
+	 *  Map::from( ['a/b/c' => 1, 'a/b/d' => 2, 'b/e' => 3] )->unflatten();
+	 *  Map::from( ['a.b.c' => 1, 'a.b.d' => 2, 'b.e' => 3] )->sep( '.' )->unflatten();
+	 *
+	 * Results:
+	 * ['a' => ['b' => ['c' => 1, 'd' => 2]], 'b' => ['e' => 3]]
+	 *
+	 * @return self<int|string,mixed> New map with multi-dimensional arrays
+	 */
+	public function unflatten() : self
+	{
+		$result = [];
+
+		foreach( $this->list() as $key => $value )
+		{
+			$nested = &$result;
+			$parts = explode( $this->sep, $key );
+
+			while( count( $parts ) > 1 ) {
+				$nested = &$nested[array_shift( $parts )] ?? [];
+			}
+
+			$nested[array_shift( $parts )] = $value;
+		}
+
+		return new static( $result );
+	}
+
+
 	/**
 	 * Builds a union of the elements and the given elements without overwriting existing ones.
 	 * Existing keys in the map will not be overwritten

tests/MapTest.php

@@ -3874,6 +3874,16 @@ public function testUsorted()
 	}
 
 
+	public function testUnflatten()
+	{
+		$flat = ['a/b/c' => 1, 'a/b/d' => 2, 'b/e' => 3];
+		$exp = ['a' => ['b' => ['c' => 1, 'd' => 2]], 'b' => ['e' => 3]];
+
+		$this->assertSame( $exp, Map::from( ['a/b/c' => 1, 'a/b/d' => 2, 'b/e' => 3] )->unflatten()->toArray() );
+		$this->assertSame( $exp, Map::from( ['a.b.c' => 1, 'a.b.d' => 2, 'b.e' => 3] )->sep( '.' )->unflatten()->toArray() );
+	}
+
+
 	public function testUnionArray()
 	{
 		$m = new Map( ['name' => 'Hello'] );