Rename mapKeys() to transform() and extend functionality

README.md

@@ -200,7 +200,6 @@ will return:
 <a href="#lastkey">lastKey</a>
 <a href="#ltrim">ltrim</a>
 <a href="#map">map</a>
-<a href="#mapKeys">mapKeys</a>
 <a href="#max">max</a>
 <a href="#merge">merge</a>
 <a href="#method">method</a>
@@ -264,6 +263,7 @@ will return:
 <a href="#toarray">toArray</a>
 <a href="#tojson">toJson</a>
 <a href="#tourl">toUrl</a>
+<a href="#transform">transform</a>
 <a href="#transpose">transpose</a>
 <a href="#traverse">traverse</a>
 <a href="#tree">tree</a>
@@ -441,7 +441,6 @@ will return:
 * [join()](#join) : Returns concatenated elements as string with separator
 * [ltrim()](#ltrim) : Removes the passed characters from the left of all strings
 * [map()](#map) : Applies a callback to each element and returns the results
-* [mapKeys()](#mapKeys) : Applies a callback to each element which creates new key/value pairs
 * [partition()](#partition) : Breaks the list into the given number of groups
 * [pipe()](#pipe) : Applies a callback to the whole map
 * [pluck()](#pluck) : Creates a key/value mapping
@@ -458,6 +457,7 @@ will return:
 * [suffix()](#suffix) : Adds a suffix to each map entry
 * [toJson()](#tojson) : Returns the elements in JSON format
 * [toUrl()](#tourl) : Creates a HTTP query string
+* [transfrom()](#transfrom) : Applies a callback to each element which creates new key/value pairs
 * [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
@@ -3377,34 +3377,6 @@ Map::from( ['a' => 2, 'b' => 4] )->map( function( $value, $key ) {
 ```
 
 
-### mapKeys()
-
-Creates new key/value pairs using the passed function and returns a new map for the result.
-
-```php
-public function map( callable $mapKeys ) : self
-```
-
-* @param **callable** `$callback` Function with (value, key) parameters and returns computed result
-* @return **self&#60;int&#124;string,mixed&#62;** New map with the new key/value pairs
-
-If a key is returned twice, the first value will be used and the second one will be ignored.
-
-**Examples:**
-
-```php
-Map::from( ['a' => 2, 'b' => 4] )->mapKeys( function( $value, $key ) {
-    return [$key . '-2' => $value * 2];
-} );
-// ['a-2' => 4, 'b-2' => 8]
-
-Map::from( ['la' => 2, 'le' => 4, 'li' => 6] )->mapKeys( function( $value, $key ) {
-    return [$key[0] => $value * 2];
-} );
-// ['l' => 4]
-```
-
-
 ### max()
 
 Returns the maximum value of all elements.
@@ -5418,6 +5390,44 @@ Map::from( ['a' => ['b' => 'abc', 'c' => 'def'], 'd' => 123] )->toUrl();
 ```
 
 
+### transform()
+
+Creates new key/value pairs using the passed function and returns a new map for the result.
+
+```php
+public function transform( \Closure $callback ) : self
+```
+
+* @param **\Closure** `$callback` Function with (value, key) parameters and returns an array of new key/value pair(s)
+* @return **self&#60;int&#124;string,mixed&#62;** New map with the new key/value pairs
+
+If a key is returned twice, the last value will overwrite previous values.
+
+**Examples:**
+
+```php
+Map::from( ['a' => 2, 'b' => 4] )->transform( function( $value, $key ) {
+    return [$key . '-2' => $value * 2];
+} );
+// ['a-2' => 4, 'b-2' => 8]
+
+Map::from( ['a' => 2, 'b' => 4] )->transform( function( $value, $key ) {
+    return [$key => $value * 2, $key . $key => $value * 4];
+} );
+// ['a' => 4, 'aa' => 8, 'b' => 8, 'bb' => 16]
+
+Map::from( ['a' => 2, 'b' => 4] )->transform( function( $value, $key ) {
+    return $key < 'b' ? [$key => $value * 2] : null;
+} );
+// ['a' => 4]
+
+Map::from( ['la' => 2, 'le' => 4, 'li' => 6] )->transform( function( $value, $key ) {
+    return [$key[0] => $value * 2];
+} );
+// ['l' => 12]
+```
+
+
 ### transpose()
 
 Exchanges rows and columns for a two dimensional map.

src/Map.php

@@ -2873,38 +2873,6 @@ public function map( callable $callback ) : self
 	}
 
 
-	/**
-	 * Creates new key/value pairs using the passed function and returns a new map for the result.
-	 *
-	 * Examples:
-	 *  Map::from( ['a' => 2, 'b' => 4] )->mapKeys( function( $value, $key ) {
-	 *      return [$key . '-2' => $value * 2];
-	 *  } );
-	 *  Map::from( ['la' => 2, 'le' => 4, 'li' => 6] )->mapKeys( function( $value, $key ) {
-	 *      return [$key[0] => $value * 2];
-	 *  } );
-	 *
-	 * Results:
-	 *  ['a-2' => 4, 'b-2' => 8]
-	 * 	['l' => 4]
-	 *
-	 * If a key is returned twice, the first value will be used and the second one will be ignored.
-	 *
-	 * @param callable $callback Function with (value, key) parameters and returns new key/value pair
-	 * @return self<int|string,mixed> New map with the new key/value pairs
-	 */
-	public function mapKeys( callable $callback ) : self
-	{
-		$result = [];
-
-		foreach( $this->list() as $key => $value ) {
-			$result += (array) $callback( $value, $key );
-		}
-
-		return new static( $result );
-	}
-
-
 	/**
 	 * Returns the maximum value of all elements.
 	 *
@@ -4937,6 +4905,49 @@ public function toUrl() : string
 	}
 
 
+	/**
+	 * Creates new key/value pairs using the passed function and returns a new map for the result.
+	 *
+	 * Examples:
+	 *  Map::from( ['a' => 2, 'b' => 4] )->transform( function( $value, $key ) {
+	 *      return [$key . '-2' => $value * 2];
+	 *  } );
+	 *  Map::from( ['a' => 2, 'b' => 4] )->transform( function( $value, $key ) {
+	 *      return [$key => $value * 2, $key . $key => $value * 4];
+	 *  } );
+	 *  Map::from( ['a' => 2, 'b' => 4] )->transform( function( $value, $key ) {
+	 *      return $key < 'b' ? [$key => $value * 2] : null;
+	 *  } );
+	 *  Map::from( ['la' => 2, 'le' => 4, 'li' => 6] )->transform( function( $value, $key ) {
+	 *      return [$key[0] => $value * 2];
+	 *  } );
+	 *
+	 * Results:
+	 *  ['a-2' => 4, 'b-2' => 8]
+	 *  ['a' => 4, 'aa' => 8, 'b' => 8, 'bb' => 16]
+	 *  ['a' => 4]
+	 *  ['l' => 12]
+	 *
+	 * If a key is returned twice, the last value will overwrite previous values.
+	 *
+	 * @param \Closure $callback Function with (value, key) parameters and returns an array of new key/value pair(s)
+	 * @return self<int|string,mixed> New map with the new key/value pairs
+	 */
+	public function transform( \Closure $callback ) : self
+	{
+		$result = [];
+
+		foreach( $this->list() as $key => $value )
+		{
+			foreach( (array) $callback( $value, $key ) as $newkey => $newval ) {
+				$result[$newkey] = $newval;
+			}
+		}
+
+		return new static( $result );
+	}
+
+
 	/**
 	 * Exchanges rows and columns for a two dimensional map.
 	 *

tests/MapTest.php

@@ -1984,18 +1984,6 @@ public function testMap()
 	}
 
 
-	public function testMapKeys()
-	{
-		$m = new Map( ['first' => 'test', 'last' => 'user', 'lost' => 'value'] );
-		$m = $m->mapKeys( function( $value, $key ) {
-			return [$key[0] . '-2' => strrev( $value )];
-		} );
-
-		$this->assertInstanceOf( Map::class, $m );
-		$this->assertSame( ['f-2' => 'tset', 'l-2' => 'resu'], $m->toArray() );
-	}
-
-
 	public function testMax()
 	{
 		$this->assertSame( 5, Map::from( [1, 3, 2, 5, 4] )->max() );
@@ -3216,6 +3204,50 @@ public function testTimesObjects()
 	}
 
 
+	public function testTransform()
+	{
+		$m = Map::from( ['a' => 2, 'b' => 4] )->transform( function( $value, $key ) {
+			return [$key . '-2' => $value * 2];
+		} );
+
+		$this->assertInstanceOf( Map::class, $m );
+		$this->assertSame( ['a-2' => 4, 'b-2' => 8], $m->toArray() );
+	}
+
+
+	public function testTransformExtend()
+	{
+		$m = Map::from( ['a' => 2, 'b' => 4] )->transform( function( $value, $key ) {
+			return [$key => $value * 2, $key . $key => $value * 4];
+		} );
+
+		$this->assertInstanceOf( Map::class, $m );
+		$this->assertSame( ['a' => 4, 'aa' => 8, 'b' => 8, 'bb' => 16], $m->toArray() );
+	}
+
+
+	public function testTransformShorten()
+	{
+		$m = Map::from( ['a' => 2, 'b' => 4] )->transform( function( $value, $key ) {
+			return $key < 'b' ? [$key => $value * 2] : null;
+		} );
+
+		$this->assertInstanceOf( Map::class, $m );
+		$this->assertSame( ['a' => 4], $m->toArray() );
+	}
+
+
+	public function testTransformOverwrite()
+	{
+		$m = Map::from( ['la' => 2, 'le' => 4, 'li' => 6] )->transform( function( $value, $key ) {
+			return [$key[0] => $value * 2];
+		} );
+
+		$this->assertInstanceOf( Map::class, $m );
+		$this->assertSame( ['l' => 12], $m->toArray() );
+	}
+
+
 	public function testTranspose()
 	{
 		$m = Map::from( [