Implemented flatten() method

Author: aimeos

README.md

@@ -165,6 +165,7 @@ will return:
 <a href="#first">first</a>
 <a href="#firstkey">firstKey</a>
 <a href="#flat">flat</a>
+<a href="#flatten">flatten</a>
 <a href="#flip">flip</a>
 <a href="#float">float</a>
 <a href="#from">from</a>
@@ -473,6 +474,7 @@ will return:
 * [collapse()](#collapse) : Collapses multi-dimensional elements overwriting elements
 * [combine()](#combine) : Combines the map elements as keys with the given values
 * [flat()](#flat) : Flattens multi-dimensional elements without overwriting elements
+* [flatten()](#flatten) : Creates a new map with keys joined recursively
 * [flip()](#flip) : Exchanges keys with their values
 * [groupBy()](#groupby) : Groups associative array elements or objects
 * [join()](#join) : Returns concatenated elements as string with separator
@@ -2364,6 +2366,39 @@ Map::from( [[0, 1], Map::from( [[2, 3], 4] )] )->flat();
 * [collapse()](#collapse) - Collapses all sub-array elements recursively to a new map
 
 
+### flatten()
+
+c.
+
+```php
+public function flatten( ?int $depth = null ) : self
+```
+
+* @param **int&#124;null** `$depth` Number of levels to flatten multi-dimensional arrays or NULL for all
+* @return **self&#60;string,mixed&#62;** New map with keys joined recursively, up to the specified depth
+
+To create the original multi-dimensional array again, use the [unflatten()](#unflatten) method.
+
+**Examples:**
+
+```php
+Map::from( ['a' => ['b' => ['c' => 1, 'd' => 2]], 'b' => ['e' => 3]] )->flatten();
+// ['a/b/c' => 1, 'a/b/d' => 2, 'b/e' => 3]
+
+Map::from( ['a' => ['b' => ['c' => 1, 'd' => 2]], 'b' => ['e' => 3]] )->flatten( 1 );
+// ['a/b' => ['c' => 1, 'd' => 2], 'b/e' => 3]
+
+Map::from( ['a' => ['b' => ['c' => 1, 'd' => 2]], 'b' => ['e' => 3]] )->sep( '.' )->flatten();
+// ['a.b.c' => 1, 'a.b.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
+* [unflatten()](#unflatten) - Unflattens the key path/value pairs into a multi-dimensional array
+
+
 ### flip()
 
 Exchanges the keys with their values and vice versa.
@@ -6975,6 +7010,8 @@ Unflattens the key path/value pairs into a multi-dimensional array.
 public function unflatten() : self
 ```
 
+This is the inverse method for [flatten()](#flatten).
+
 * @return **self&#60;string,mixed&#62;** New map with multi-dimensional arrays
 
 **Examples:**
@@ -6989,8 +7026,9 @@ Map::from( ['a.b.c' => 1, 'a.b.d' => 2, 'b.e' => 3] )->sep( '.' )->unflatten();
 
 **See also:**
 
-* [flat()](#flat) - Flattens multi-dimensional elements without overwriting elements
 * [collapse()](#collapse) - Collapses all sub-array elements recursively to a new map
+* [flat()](#flat) - Flattens multi-dimensional elements without overwriting elements
+* [flatten()](#flatten) - Creates a new map with keys joined recursively
 
 
 ### union()

src/Map.php

@@ -1767,7 +1767,7 @@ public function firstKey( $default = null )
 
 
 	/**
-	 * Creates a new map with all sub-array elements added recursively withput overwriting existing keys.
+	 * Creates a new map with all sub-array elements added recursively without overwriting existing keys.
 	 *
 	 * Examples:
 	 *  Map::from( [[0, 1], [2, 3]] )->flat();
@@ -1800,7 +1800,38 @@ public function flat( ?int $depth = null ) : self
 		}
 
 		$result = [];
-		$this->flatten( $this->list(), $result, $depth ?? 0x7fffffff );
+		$this->nflatten( $this->list(), $result, $depth ?? 0x7fffffff );
+		return new static( $result );
+	}
+
+
+	/**
+	 * Creates a new map with keys joined recursively.
+	 *
+	 * Examples:
+	 *  Map::from( ['a' => ['b' => ['c' => 1, 'd' => 2]], 'b' => ['e' => 3]] )->flatten();
+	 *  Map::from( ['a' => ['b' => ['c' => 1, 'd' => 2]], 'b' => ['e' => 3]] )->flatten( 1 );
+	 *  Map::from( ['a' => ['b' => ['c' => 1, 'd' => 2]], 'b' => ['e' => 3]] )->sep( '.' )->flatten();
+	 *
+	 * Results:
+	 *  ['a/b/c' => 1, 'a/b/d' => 2, 'b/e' => 3]
+	 *  ['a/b' => ['c' => 1, 'd' => 2], 'b/e' => 3]
+	 *  ['a.b.c' => 1, 'a.b.d' => 2, 'b.e' => 3]
+	 *
+	 * To create the original multi-dimensional array again, use the unflatten() method.
+	 *
+	 * @param int|null $depth Number of levels to flatten multi-dimensional arrays or NULL for all
+	 * @return self<string,mixed> New map with keys joined recursively, up to the specified depth
+	 * @throws \InvalidArgumentException If depth must be greater or equal than 0 or NULL
+	 */
+	public function flatten( ?int $depth = null ) : self
+	{
+		if( $depth < 0 ) {
+			throw new \InvalidArgumentException( 'Depth must be greater or equal than 0 or NULL' );
+		}
+
+		$result = [];
+		$this->rflatten( $this->list(), $result, $depth ?? 0x7fffffff );
 		return new static( $result );
 	}
 
@@ -5810,6 +5841,8 @@ public function uksorted( callable $callback ) : self
 	 * Results:
 	 * ['a' => ['b' => ['c' => 1, 'd' => 2]], 'b' => ['e' => 3]]
 	 *
+	 * This is the inverse method for flatten().
+	 *
 	 * @return self<int|string,mixed> New map with multi-dimensional arrays
 	 */
 	public function unflatten() : self
@@ -6225,26 +6258,6 @@ protected function array( $elements ) : array
 	}
 
 
-	/**
-	 * Flattens a multi-dimensional array or map into a single level array.
-	 *
-	 * @param iterable<int|string,mixed> $entries Single of multi-level array, map or everything foreach can be used with
-	 * @param array<mixed> &$result Will contain all elements from the multi-dimensional arrays afterwards
-	 * @param int $depth Number of levels to flatten in multi-dimensional arrays
-	 */
-	protected function flatten( iterable $entries, array &$result, int $depth ) : void
-	{
-		foreach( $entries as $entry )
-		{
-			if( is_iterable( $entry ) && $depth > 0 ) {
-				$this->flatten( $entry, $result, $depth - 1 );
-			} else {
-				$result[] = $entry;
-			}
-		}
-	}
-
-
 	/**
 	 * Flattens a multi-dimensional array or map into a single level array.
 	 *
@@ -6300,6 +6313,47 @@ protected function mapper( $key = null ) : \Closure
 	}
 
 
+	/**
+	 * Flattens a multi-dimensional array or map into a single level array.
+	 *
+	 * @param iterable<int|string,mixed> $entries Single of multi-level array, map or everything foreach can be used with
+	 * @param array<mixed> &$result Will contain all elements from the multi-dimensional arrays afterwards
+	 * @param int $depth Number of levels to flatten in multi-dimensional arrays
+	 */
+	protected function nflatten( iterable $entries, array &$result, int $depth ) : void
+	{
+		foreach( $entries as $entry )
+		{
+			if( is_iterable( $entry ) && $depth > 0 ) {
+				$this->nflatten( $entry, $result, $depth - 1 );
+			} else {
+				$result[] = $entry;
+			}
+		}
+	}
+
+
+	/**
+	 * Flattens a multi-dimensional array or map into an array with joined keys.
+	 *
+	 * @param iterable<int|string,mixed> $entries Single of multi-level array, map or everything foreach can be used with
+	 * @param array<int|string,mixed> $result Will contain joined key/value pairs from the multi-dimensional arrays afterwards
+	 * @param int $depth Number of levels to flatten in multi-dimensional arrays
+	 * @param string $path Path prefix of the current key
+	 */
+	protected function rflatten( iterable $entries, array &$result, int $depth, string $path = '' ) : void
+	{
+		foreach( $entries as $key => $entry )
+		{
+			if( is_iterable( $entry ) && $depth > 0 ) {
+				$this->rflatten( $entry, $result, $depth - 1, $path . $key . $this->sep );
+			} else {
+				$result[$path . $key] = $entry;
+			}
+		}
+	}
+
+
 	/**
 	 * Returns the position of the first element that doesn't match the condition
 	 *

tests/MapTest.php

@@ -1211,6 +1211,23 @@ public function testFlatException()
 	}
 
 
+	public function testFlatten()
+	{
+		$a = ['a' => ['b' => ['c' => 1, 'd' => 2]], 'b' => ['e' => 3]];
+
+		$this->assertSame( ['a/b/c' => 1, 'a/b/d' => 2, 'b/e' => 3], Map::from( $a )->flatten()->toArray() );
+		$this->assertSame( ['a/b' => ['c' => 1, 'd' => 2], 'b/e' => 3], Map::from( $a )->flatten( 1 )->toArray() );
+		$this->assertSame( ['a.b.c' => 1, 'a.b.d' => 2, 'b.e' => 3], Map::from( $a )->sep( '.' )->flatten()->toArray() );
+	}
+
+
+	public function testFlattenException()
+	{
+		$this->expectException( \InvalidArgumentException::class );
+		Map::from( [] )->flatten( -1 );
+	}
+
+
 	public function testFlip()
 	{
 		$m = Map::from( ['a' => 'X', 'b' => 'Y'] );