From 870a52308ccf8ec4b292175a3ba05329a7d79ff5 Mon Sep 17 00:00:00 2001 From: Aimeos Date: Fri, 2 Aug 2024 12:38:25 +0200 Subject: [PATCH 01/15] Minor improvement --- README.md | 2 +- tests/MapTest.php | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e6fbcd8..3093773 100644 --- a/README.md +++ b/README.md @@ -5211,7 +5211,7 @@ Map::from( [['p' => 30], ['p' => 50], ['p' => 10]] )->sum( 'p' ); Map::from( [['i' => ['p' => 30]], ['i' => ['p' => 50]]] )->sum( 'i/p' ); // 80 -Map::from( [30, 50, 10] )->sum( fn( $val, $key ) => $val < 50 ? $val : 0 ); +Map::from( [30, 50, 10] )->sum( fn( $val, $key ) => $val < 50 ); // 40 ``` diff --git a/tests/MapTest.php b/tests/MapTest.php index 21fd452..a19fc66 100644 --- a/tests/MapTest.php +++ b/tests/MapTest.php @@ -3122,8 +3122,8 @@ public function testSum() public function testSumClosure() { - $this->assertSame( 40.0, Map::from( [30, 50, 10] )->sum( function( $val ) { return $val < 50 ? $val : 0; } ) ); - $this->assertSame( 60.0, Map::from( [30, 50, 10] )->sum( function( $val, $key ) { return $key > 0 ? $val : 0; } ) ); + $this->assertSame( 40.0, Map::from( [30, 50, 10] )->sum( function( $val ) { return $val < 50; } ) ); + $this->assertSame( 60.0, Map::from( [30, 50, 10] )->sum( function( $val, $key ) { return $key > 0; } ) ); } From f0fae381b8621a9c58f8a4902c6e9b4ec5186978 Mon Sep 17 00:00:00 2001 From: Aimeos Date: Fri, 2 Aug 2024 12:41:17 +0200 Subject: [PATCH 02/15] Documentation fixes --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3093773..1803287 100644 --- a/README.md +++ b/README.md @@ -2456,7 +2456,7 @@ a void return type and must/will always return something. Details about [PHP arrow functions](https://www.php.net/manual/en/functions.arrow.php) -# implements() +### implements() Tests if all entries in the map are objects implementing the given interface. @@ -2521,7 +2521,7 @@ Map::from( ['1', '2'] )->in( 2, true ); ``` -## includes() +### includes() Tests if the passed element or elements are part of the map. @@ -5625,7 +5625,7 @@ Map::from( ['a' => 'B', 'b' => 'a'] )->uasort( function( $itemA, $itemB ) { ``` -## uksort() +### uksort() Sorts the map elements by their keys using a callback. From 0003fcc9c488d0a055b41971f23dfdb2d0b3882d Mon Sep 17 00:00:00 2001 From: Aimeos Date: Thu, 10 Oct 2024 13:39:53 +0200 Subject: [PATCH 03/15] Added mapKeys() method --- README.md | 32 +++++++++++++++++++++++++++++++- src/Map.php | 34 +++++++++++++++++++++++++++++++++- tests/MapTest.php | 12 ++++++++++++ 3 files changed, 76 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1803287..36b0494 100644 --- a/README.md +++ b/README.md @@ -200,6 +200,7 @@ will return: lastKey ltrim map +mapKeys max merge method @@ -440,6 +441,7 @@ 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 @@ -3354,7 +3356,7 @@ Map::from( ["a b c", "cbxa"] )->ltrim( 'abc' ); ### map() -Calls the passed function once for each element and returns a new map for the result. +Maps new values to the existing keys using the passed function and returns a new map for the result. ```php public function map( callable $callback ) : self @@ -3375,6 +3377,34 @@ 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<int|string,mixed>** 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. diff --git a/src/Map.php b/src/Map.php index f7a7d56..b81f426 100644 --- a/src/Map.php +++ b/src/Map.php @@ -2848,7 +2848,7 @@ public function ltrim( string $chars = " \n\r\t\v\x00" ) : self /** - * Calls the passed function once for each element and returns a new map for the result. + * Maps new values to the existing keys using the passed function and returns a new map for the result. * * Examples: * Map::from( ['a' => 2, 'b' => 4] )->map( function( $value, $key ) { @@ -2873,6 +2873,38 @@ 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 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. * diff --git a/tests/MapTest.php b/tests/MapTest.php index a19fc66..b627f6a 100644 --- a/tests/MapTest.php +++ b/tests/MapTest.php @@ -1984,6 +1984,18 @@ 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() ); From 55706e4ee65815988a4a077478b30dac5e2f7ef9 Mon Sep 17 00:00:00 2001 From: Aimeos Date: Fri, 18 Oct 2024 08:20:13 +0200 Subject: [PATCH 04/15] Rename mapKeys() to transform() and extend functionality --- README.md | 70 ++++++++++++++++++++++++------------------- src/Map.php | 75 +++++++++++++++++++++++++++-------------------- tests/MapTest.php | 56 +++++++++++++++++++++++++++-------- 3 files changed, 127 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index 36b0494..3471a46 100644 --- a/README.md +++ b/README.md @@ -200,7 +200,6 @@ will return: lastKey ltrim map -mapKeys max merge method @@ -264,6 +263,7 @@ will return: toArray toJson toUrl +transform transpose traverse tree @@ -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<int|string,mixed>** 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<int|string,mixed>** 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. diff --git a/src/Map.php b/src/Map.php index b81f426..6b17f6e 100644 --- a/src/Map.php +++ b/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 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 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. * diff --git a/tests/MapTest.php b/tests/MapTest.php index b627f6a..74dc80f 100644 --- a/tests/MapTest.php +++ b/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( [ From e35fd37430882aa77d0ace54c5dd242c35b8e35b Mon Sep 17 00:00:00 2001 From: Aimeos Date: Wed, 23 Oct 2024 12:32:48 +0200 Subject: [PATCH 05/15] Clone object directly instead of calling copy() --- src/Map.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Map.php b/src/Map.php index 6b17f6e..2e2485b 100644 --- a/src/Map.php +++ b/src/Map.php @@ -1394,7 +1394,7 @@ public function every( \Closure $callback ) : bool */ public function except( $keys ) : self { - return $this->copy()->remove( $keys ); + return ( clone $this )->remove( $keys ); } @@ -5524,7 +5524,7 @@ public function where( string $key, string $op, $value ) : self */ public function with( $key, $value ) : self { - return $this->copy()->set( $key, $value ); + return ( clone $this )->set( $key, $value ); } From eba1d044f933365eb7a167729fa7a269ff648e0c Mon Sep 17 00:00:00 2001 From: Aimeos Date: Wed, 23 Oct 2024 12:36:00 +0200 Subject: [PATCH 06/15] Added sorted() method --- README.md | 42 ++++++++++++++++++++++++++++++++++++++++-- src/Map.php | 37 +++++++++++++++++++++++++++++++++++-- tests/MapTest.php | 11 +++++++++++ 3 files changed, 86 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3471a46..2ea85be 100644 --- a/README.md +++ b/README.md @@ -365,7 +365,8 @@ will return: * [reverse()](#reverse) : Reverses the array order preserving keys * [rsort()](#rsort) : Reverse sort elements using new keys * [shuffle()](#shuffle) : Randomizes the element order -* [sort()](#sort) : Sorts the elements assigning new keys +* [sort()](#sort) : Sorts the elements in-place assigning new keys +* [sorted()](#sorted) : Sorts the elements in a copy of the map using new keys * [uasort()](#uasort) : Sorts elements preserving keys using callback * [uksort()](#uksort) : Sorts elements by keys using callback * [usort()](#usort) : Sorts elements using callback assigning new keys @@ -4526,7 +4527,7 @@ Sorts all elements without maintaining the key association. public function sort( int $options = SORT_REGULAR ) : self ``` -* @param **int** `$options` Sort options for `sort()` +* @param **int** `$options` Sort options for PHP `sort()` * @return **self<int|string,mixed>** Updated map for fluid interface The parameter modifies how the values are compared. Possible parameter values are: @@ -4550,6 +4551,43 @@ Map::from( [0 => 'b', 1 => 'a'] )->sort(); ``` +### sorted() + +Sorts the elements in a copy of the map using new keys. + +```php +public function sorted( int $options = SORT_REGULAR ) : self +``` + +* @param **int** `$options` Sort options for PHP `sort()` +* @return **self<int|string,mixed>** New map with a sorted copy of the elements + +The parameter modifies how the values are compared. Possible parameter values are: +- SORT_REGULAR : compare elements normally (don't change types) +- SORT_NUMERIC : compare elements numerically +- SORT_STRING : compare elements as strings +- SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by `setlocale()` +- SORT_NATURAL : compare elements as strings using "natural ordering" like `natsort()` +- SORT_FLAG_CASE : use SORT_STRING|SORT_FLAG_CASE and SORT_NATURAL|SORT_FLAG_CASE to sort strings case-insensitively + +The keys aren't preserved and elements get a new index and a new map is created before sorting the elements. +Thus, [sort()](#sort) should be preferred for performance reasons if possible. + +**Examples:** + +```php +Map::from( ['a' => 1, 'b' => 0] )->sorted(); +// [0 => 0, 1 => 1] + +Map::from( [0 => 'b', 1 => 'a'] )->sorted(); +// [0 => 'a', 1 => 'b'] +``` + +**See also:** + +* [sort()](#sort) - Sorts elements in-place in the original map + + ### splice() Removes a portion of the map and replace it with the given replacement, then return the updated map. diff --git a/src/Map.php b/src/Map.php index 2e2485b..ab107e3 100644 --- a/src/Map.php +++ b/src/Map.php @@ -4084,7 +4084,7 @@ public function some( $values, bool $strict = false ) : bool /** - * Sorts all elements using new keys. + * Sorts all elements in-place using new keys. * * Examples: * Map::from( ['a' => 1, 'b' => 0] )->sort(); @@ -4104,8 +4104,9 @@ public function some( $values, bool $strict = false ) : bool * * The keys aren't preserved and elements get a new index. No new map is created. * - * @param int $options Sort options for sort() + * @param int $options Sort options for PHP sort() * @return self Updated map for fluid interface + * @see sorted() - Sorts elements in a copy of the map */ public function sort( int $options = SORT_REGULAR ) : self { @@ -4114,6 +4115,38 @@ public function sort( int $options = SORT_REGULAR ) : self } + /** + * Sorts the elements in a copy of the map using new keys. + * + * Examples: + * Map::from( ['a' => 1, 'b' => 0] )->sorted(); + * Map::from( [0 => 'b', 1 => 'a'] )->sorted(); + * + * Results: + * [0 => 0, 1 => 1] + * [0 => 'a', 1 => 'b'] + * + * The parameter modifies how the values are compared. Possible parameter values are: + * - SORT_REGULAR : compare elements normally (don't change types) + * - SORT_NUMERIC : compare elements numerically + * - SORT_STRING : compare elements as strings + * - SORT_LOCALE_STRING : compare elements as strings, based on the current locale or changed by setlocale() + * - SORT_NATURAL : compare elements as strings using "natural ordering" like natsort() + * - SORT_FLAG_CASE : use SORT_STRING|SORT_FLAG_CASE and SORT_NATURALSORT_FLAG_CASE to sort strings case-insensitively + * + * The keys aren't preserved and elements get a new index and a new map is created before sorting the elements. + * Thus, sort() should be preferred for performance reasons if possible. + * + * @param int $options Sort options for PHP sort() + * @return self New map with a sorted copy of the elements + * @see sort() - Sorts elements in-place in the original map + */ + public function sorted( int $options = SORT_REGULAR ) : self + { + return ( clone $this )->sort( $options ); + } + + /** * Removes a portion of the map and replace it with the given replacement, then return the updated map. * diff --git a/tests/MapTest.php b/tests/MapTest.php index 74dc80f..2cc3c0e 100644 --- a/tests/MapTest.php +++ b/tests/MapTest.php @@ -2835,6 +2835,17 @@ public function testSomeCallback() } + public function testSorted() + { + $m = new Map( [-1, -3, -2, -4, -5, 0, 5, 3, 1, 2, 4] ); + $n = $m->sorted(); + + $this->assertNotSame( $n, $m ); + $this->assertInstanceOf( Map::class, $n ); + $this->assertSame( [-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5], $n->toArray() ); + } + + public function testSortNummeric() { $m = ( new Map( [-1, -3, -2, -4, -5, 0, 5, 3, 1, 2, 4] ) )->sort(); From d32d40ea8791a6de7e5fd63d5dfcd0e934c3e167 Mon Sep 17 00:00:00 2001 From: Aimeos Date: Wed, 23 Oct 2024 12:41:01 +0200 Subject: [PATCH 07/15] Streamlined documentation for alias methods --- README.md | 64 ++++++++++++++++++----------------------------------- src/Map.php | 21 ++++-------------- 2 files changed, 25 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 2ea85be..fbd8032 100644 --- a/README.md +++ b/README.md @@ -331,9 +331,9 @@ will return: * [insertBefore()](#insertbefore) : Inserts the value before the given element * [merge()](#merge) : Combines elements overwriting existing ones * [pad()](#pad) : Fill up to the specified length with the given value -* [prepend()](#prepend) : Adds an element at the beginning +* [prepend()](#prepend) : Adds an element at the beginning (alias) * [push()](#push) : Adds an element to the end -* [put()](#put) : Sets the given key and value in the map +* [put()](#put) : Sets the given key and value in the map (alias) * [set()](#set) : Overwrites or adds an element * [union()](#union) : Adds the elements without overwriting existing ones * [unshift()](#unshift) : Adds an element at the beginning @@ -367,6 +367,7 @@ will return: * [shuffle()](#shuffle) : Randomizes the element order * [sort()](#sort) : Sorts the elements in-place assigning new keys * [sorted()](#sorted) : Sorts the elements in a copy of the map using new keys +* [toSorted()](#toSorted) : Sorts the elements in a copy of the map using new keys (alias) * [uasort()](#uasort) : Sorts elements preserving keys using callback * [uksort()](#uksort) : Sorts elements by keys using callback * [usort()](#usort) : Sorts elements using callback assigning new keys @@ -444,7 +445,7 @@ will return: * [map()](#map) : Applies a callback to each element and returns the results * [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 +* [pluck()](#pluck) : Creates a key/value mapping (alias) * [prefix()](#prefix) : Adds a prefix to each map entry * [reduce()](#reduce) : Computes a single value from the map content * [rekey()](#rekey) : Changes the keys according to the passed function @@ -2526,7 +2527,7 @@ Map::from( ['1', '2'] )->in( 2, true ); ### includes() -Tests if the passed element or elements are part of the map. +Tests if the passed element or elements are part of the map (alias). ```php public function includes( $element, bool $strict = false ) : bool @@ -2539,24 +2540,9 @@ public function includes( $element, bool $strict = false ) : bool This method is an alias for [in()](#in). For performance reasons, `in()` should be preferred because it uses one method call less than `includes()`. -**Examples:** - -```php -Map::from( ['a', 'b'] )->includes( 'a' ); -// true - -Map::from( ['a', 'b'] )->includes( ['a', 'b'] ); -// true - -Map::from( ['a', 'b'] )->includes( 'x' ); -// false - -Map::from( ['a', 'b'] )->includes( ['a', 'x'] ); -// false +**See also:** -Map::from( ['1', '2'] )->includes( 2, true ); -// false -``` +* [in()](#in) - Underlying method with same parameters and return value but better performance ### index() @@ -3864,7 +3850,7 @@ Map::from( ['a', 'b'] )->pipe( function( $map ) { ### pluck() -Returns the values of a single column/property from an array of arrays or list of elements in a new map. +Returns the values of a single column/property from an array of arrays or list of elements in a new map (alias). ```php public function pluck( string $valuecol = null, string $indexcol = null ) : self @@ -3877,6 +3863,9 @@ public function pluck( string $valuecol = null, string $indexcol = null ) : self This method is an alias for [col()](#col). For performance reasons, `col()` should be preferred because it uses one method call less than `pluck()`. +**See also:** + +* [col()](#col) - Underlying method with same parameters and return value but better performance ### pop() @@ -3959,7 +3948,7 @@ Map::from( ['a', 'b'] )->prefix( function( $item, $key ) { ### prepend() -Pushes an element onto the beginning of the map without returning a new map. +Pushes an element onto the beginning of the map without returning a new map (alias). ```php public function prepend( $value, $key = null ) : self @@ -3969,17 +3958,12 @@ public function prepend( $value, $key = null ) : self * @param **int|string|null** `$key` Key for the item or NULL to reindex all numerical keys * @return **self<int|string,mixed>** Updated map for fluid interface -This method is an alias for the [unshift()](#unshift) method. - -**Examples:** +This method is an alias for the [unshift()](#unshift) method. For performance reasons, `unshift()` should +be preferred because it uses one method call less than `prepend()`. -```php -Map::from( ['a', 'b'] )->prepend( 'd' ); -// ['d', 'a', 'b'] +**See also:** -Map::from( ['a', 'b'] )->prepend( 'd', 'first' ); -// ['first' => 'd', 0 => 'a', 1 => 'b'] -``` +* [unshift()](#unshift) - Underlying method with same parameters and return value but better performance ### pull() @@ -4026,28 +4010,22 @@ Map::from( ['a', 'b'] )->push( 'aa' ); ### put() -Sets the given key and value in the map without returning a new map. +Sets the given key and value in the map without returning a new map (alias). ```php public function put( $key, $value ) : self ``` -This method is an alias for `set()`. For performance reasons, `set()` should be -preferred because it uses one method call less than `put()`. - * @param **int|string** `$key` Key to set the new value for * @param **mixed** `$value` New element that should be set * @return **self<int|string,mixed>** Updated map for fluid interface -**Examples:** +This method is an alias for [set()](#set). For performance reasons, `set()` should be +preferred because it uses one method call less than `put()`. -```php -Map::from( ['a'] )->put( 1, 'b' ); -// [0 => 'a', 1 => 'b'] +**See also:** -Map::from( ['a'] )->put( 0, 'b' ); -// [0 => 'b'] -``` +* [set()](#set) - Underlying method with same parameters and return value but better performance ### random() diff --git a/src/Map.php b/src/Map.php index ab107e3..15d15ba 100644 --- a/src/Map.php +++ b/src/Map.php @@ -2071,22 +2071,13 @@ public function in( $element, bool $strict = false ) : bool /** * Tests if the passed element or elements are part of the map. * - * Examples: - * Map::from( ['a', 'b'] )->includes( 'a' ); - * Map::from( ['a', 'b'] )->includes( ['a', 'b'] ); - * Map::from( ['a', 'b'] )->includes( 'x' ); - * Map::from( ['a', 'b'] )->includes( ['a', 'x'] ); - * Map::from( ['1', '2'] )->includes( 2, true ); - * - * Results: - * The first and second example will return TRUE while the other ones will return FALSE - * * This method is an alias for in(). For performance reasons, in() should be * preferred because it uses one method call less than includes(). * * @param mixed|array $element Element or elements to search for in the map * @param bool $strict TRUE to check the type too, using FALSE '1' and 1 will be the same * @return bool TRUE if all elements are available in map, FALSE if not + * @see in() - Underlying method with same parameters and return value but better performance */ public function includes( $element, bool $strict = false ) : bool { @@ -3352,6 +3343,7 @@ public function pipe( \Closure $callback ) * @param string|null $valuecol Name or path of the value property * @param string|null $indexcol Name or path of the index property * @return self New map with mapped entries + * @see col() - Underlying method with same parameters and return value but better performance */ public function pluck( string $valuecol = null, string $indexcol = null ) : self { @@ -3476,6 +3468,7 @@ public function prefix( $prefix, int $depth = null ) : self * @param mixed $value Item to add at the beginning * @param int|string|null $key Key for the item or NULL to reindex all numerical keys * @return self Updated map for fluid interface + * @see unshift() - Underlying method with same parameters and return value but better performance */ public function prepend( $value, $key = null ) : self { @@ -3534,19 +3527,13 @@ public function push( $value ) : self /** * Sets the given key and value in the map without returning a new map. * - * Examples: - * Map::from( ['a'] )->put( 1, 'b' ); - * Map::from( ['a'] )->put( 0, 'b' ); - * - * Results: - * The first example results in ['a', 'b'] while the second one produces ['b'] - * * This method is an alias for set(). For performance reasons, set() should be * preferred because it uses one method call less than put(). * * @param int|string $key Key to set the new value for * @param mixed $value New element that should be set * @return self Updated map for fluid interface + * @see set() - Underlying method with same parameters and return value but better performance */ public function put( $key, $value ) : self { From bab88f9d8bc683025979534e3d1656b14a305e9f Mon Sep 17 00:00:00 2001 From: Aimeos Date: Wed, 23 Oct 2024 12:59:08 +0200 Subject: [PATCH 08/15] Added toSorted() method --- README.md | 21 +++++++++++++++++++++ src/Map.php | 16 ++++++++++++++++ tests/MapTest.php | 11 +++++++++++ 3 files changed, 48 insertions(+) diff --git a/README.md b/README.md index fbd8032..8a7c78b 100644 --- a/README.md +++ b/README.md @@ -242,6 +242,7 @@ will return: slice some sort +sorted splice split strAfter @@ -262,6 +263,7 @@ will return: times toArray toJson +toSorted toUrl transform transpose @@ -5385,6 +5387,25 @@ Map::from( ['a', 'b'] )->toJson( JSON_FORCE_OBJECT ); ``` +### toSorted() + +Sorts the elements in a copy of the map using new keys (alias). + +```php +public function toSorted( int $options = SORT_REGULAR ) : self +``` + +* @param **int** `$options` Sort options for PHP `sort()` +* @return **self<int|string,mixed>** New map with a sorted copy of the elements + +This method is an alias for [sorted()](#sorted). For performance reasons, sorted() should be +preferred because it uses one method call less than toSorted(). + +**See also:** + +* [sorted()](#sorted) - Underlying method with same parameters and return value but better performance + + ### toUrl() Creates a HTTP query string from the map elements. diff --git a/src/Map.php b/src/Map.php index 15d15ba..bc72c99 100644 --- a/src/Map.php +++ b/src/Map.php @@ -4906,6 +4906,22 @@ public function toJson( int $options = 0 ) : ?string } + /** + * Sorts the elements in a copy of the map using new keys. + * + * This method is an alias for sorted(). For performance reasons, sorted() should be + * preferred because it uses one method call less than toSorted(). + * + * @param int $options Sort options for PHP sort() + * @return self New map with a sorted copy of the elements + * @see sorted() - Underlying method with same parameters and return value but better performance + */ + public function toSorted( int $options = SORT_REGULAR ) : self + { + return $this->sorted( $options ); + } + + /** * Creates a HTTP query string from the map elements. * diff --git a/tests/MapTest.php b/tests/MapTest.php index 2cc3c0e..47969fb 100644 --- a/tests/MapTest.php +++ b/tests/MapTest.php @@ -3215,6 +3215,17 @@ public function testTimesObjects() } + public function testToSorted() + { + $m = new Map( [-1, -3, -2, -4, -5, 0, 5, 3, 1, 2, 4] ); + $n = $m->toSorted(); + + $this->assertNotSame( $n, $m ); + $this->assertInstanceOf( Map::class, $n ); + $this->assertSame( [-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5], $n->toArray() ); + } + + public function testTransform() { $m = Map::from( ['a' => 2, 'b' => 4] )->transform( function( $value, $key ) { From b4ec41c4aad6e3f5f881ed893a7b81c8c45a9292 Mon Sep 17 00:00:00 2001 From: Aimeos Date: Thu, 24 Oct 2024 11:12:24 +0200 Subject: [PATCH 09/15] Added reversed() method --- README.md | 34 ++++++++++++++++++++++++++++++++++ src/Map.php | 24 ++++++++++++++++++++++++ tests/MapTest.php | 11 +++++++++++ 3 files changed, 69 insertions(+) diff --git a/README.md b/README.md index 8a7c78b..457e3d7 100644 --- a/README.md +++ b/README.md @@ -231,6 +231,7 @@ will return: remove replace reverse +reversed rsort rtrim search @@ -365,6 +366,7 @@ will return: * [ksort()](#ksort) : Sort elements by keys * [order()](#order) : Orders elements by the passed keys * [reverse()](#reverse) : Reverses the array order preserving keys +* [reversed()](#reversed) : Reverses the element order in a copy of the map * [rsort()](#rsort) : Reverse sort elements using new keys * [shuffle()](#shuffle) : Randomizes the element order * [sort()](#sort) : Sorts the elements in-place assigning new keys @@ -4211,6 +4213,38 @@ Map::from( ['name' => 'test', 'last' => 'user'] )->reverse(); // ['last' => 'user', 'name' => 'test'] ``` +**See also:** + +* [reversed()](#reversed) - Reverses the element order in a copy of the map + + +### reversed() + +Reverses the element order in a copy of the map. + +```php +public function reversed() : self +``` + +* @return **self<int|string,mixed>** New map with a reversed copy of the elements + +The keys are preserved using this method and a new map is created before reversing the elements. +Thus, [reverse()](#reverse) should be preferred for performance reasons if possible. + +**Examples:** + +```php +Map::from( ['a', 'b'] )->reversed(); +// ['b', 'a'] + +Map::from( ['name' => 'test', 'last' => 'user'] )->reversed(); +// ['last' => 'user', 'name' => 'test'] +``` + +**See also:** + +* [reverse()](#reverse) - Reverses the element order without returning a new map + ### rsort() diff --git a/src/Map.php b/src/Map.php index bc72c99..c35166a 100644 --- a/src/Map.php +++ b/src/Map.php @@ -3734,6 +3734,7 @@ public function replace( iterable $elements, bool $recursive = true ) : self * The keys are preserved using this method. * * @return self Updated map for fluid interface + * @see reversed() - Reverses the element order in a copy of the map */ public function reverse() : self { @@ -3742,6 +3743,29 @@ public function reverse() : self } + /** + * Reverses the element order in a copy of the map. + * + * Examples: + * Map::from( ['a', 'b'] )->reversed(); + * Map::from( ['name' => 'test', 'last' => 'user'] )->reversed(); + * + * Results: + * ['b', 'a'] + * ['last' => 'user', 'name' => 'test'] + * + * The keys are preserved using this method and a new map is created before reversing the elements. + * Thus, reverse() should be preferred for performance reasons if possible. + * + * @return self New map with a reversed copy of the elements + * @see reverse() - Reverses the element order with keys without returning a new map + */ + public function reversed() : self + { + return ( clone $this )->reverse(); + } + + /** * Sorts all elements in reverse order using new keys. * diff --git a/tests/MapTest.php b/tests/MapTest.php index 47969fb..6cc8d50 100644 --- a/tests/MapTest.php +++ b/tests/MapTest.php @@ -2606,6 +2606,17 @@ public function testReverseKeys() } + public function testReversed() + { + $m = new Map( ['hello', 'world'] ); + $r = $m->reversed(); + + $this->assertNotSame( $r, $m ); + $this->assertInstanceOf( Map::class, $r ); + $this->assertSame( [1 => 'world', 0 => 'hello'], $r->toArray() ); + } + + public function testRsortNummeric() { $m = ( new Map( [-1, -3, -2, -4, -5, 0, 5, 3, 1, 2, 4] ) )->rsort(); From 7e4ffd65cb15221d95cf4f09d1d090a9fca2fe01 Mon Sep 17 00:00:00 2001 From: Aimeos Date: Thu, 24 Oct 2024 11:21:34 +0200 Subject: [PATCH 10/15] Added toReversed() method --- README.md | 22 +++++++++++++++++++++- src/Map.php | 17 ++++++++++++++++- tests/MapTest.php | 11 +++++++++++ 3 files changed, 48 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 457e3d7..877b7d1 100644 --- a/README.md +++ b/README.md @@ -264,6 +264,7 @@ will return: times toArray toJson +toReversed toSorted toUrl transform @@ -367,11 +368,12 @@ will return: * [order()](#order) : Orders elements by the passed keys * [reverse()](#reverse) : Reverses the array order preserving keys * [reversed()](#reversed) : Reverses the element order in a copy of the map +* [toReversed()](#toreversed) : Reverses the element order in a copy of the map (alias) * [rsort()](#rsort) : Reverse sort elements using new keys * [shuffle()](#shuffle) : Randomizes the element order * [sort()](#sort) : Sorts the elements in-place assigning new keys * [sorted()](#sorted) : Sorts the elements in a copy of the map using new keys -* [toSorted()](#toSorted) : Sorts the elements in a copy of the map using new keys (alias) +* [toSorted()](#tosorted) : Sorts the elements in a copy of the map using new keys (alias) * [uasort()](#uasort) : Sorts elements preserving keys using callback * [uksort()](#uksort) : Sorts elements by keys using callback * [usort()](#usort) : Sorts elements using callback assigning new keys @@ -5421,6 +5423,24 @@ Map::from( ['a', 'b'] )->toJson( JSON_FORCE_OBJECT ); ``` +### toReversed() + +Reverses the element order in a copy of the map (alias). + +```php +public function toReversed() : self +``` + +* @return **self<int|string,mixed>** New map with a reversed copy of the elements + +This method is an alias for [reversed()](#reversed). For performance reasons, reversed() should be +preferred because it uses one method call less than toReversed(). + +**See also:** + +* [reversed()](#reversed) - Underlying method with same parameters and return value but better performance + + ### toSorted() Sorts the elements in a copy of the map using new keys (alias). diff --git a/src/Map.php b/src/Map.php index c35166a..04adaec 100644 --- a/src/Map.php +++ b/src/Map.php @@ -4931,7 +4931,22 @@ public function toJson( int $options = 0 ) : ?string /** - * Sorts the elements in a copy of the map using new keys. + * Reverses the element order in a copy of the map (alias). + * + * This method is an alias for reversed(). For performance reasons, reversed() should be + * preferred because it uses one method call less than toReversed(). + * + * @return self New map with a reversed copy of the elements + * @see reversed() - Underlying method with same parameters and return value but better performance + */ + public function toReversed() : self + { + return $this->reversed(); + } + + + /** + * Sorts the elements in a copy of the map using new keys (alias). * * This method is an alias for sorted(). For performance reasons, sorted() should be * preferred because it uses one method call less than toSorted(). diff --git a/tests/MapTest.php b/tests/MapTest.php index 6cc8d50..1ff994b 100644 --- a/tests/MapTest.php +++ b/tests/MapTest.php @@ -3226,6 +3226,17 @@ public function testTimesObjects() } + public function testToReversed() + { + $m = new Map( ['hello', 'world'] ); + $r = $m->toReversed(); + + $this->assertNotSame( $r, $m ); + $this->assertInstanceOf( Map::class, $r ); + $this->assertSame( [1 => 'world', 0 => 'hello'], $r->toArray() ); + } + + public function testToSorted() { $m = new Map( [-1, -3, -2, -4, -5, 0, 5, 3, 1, 2, 4] ); From 3434897e931ccd471f20fef3960e0617b8171b0a Mon Sep 17 00:00:00 2001 From: Aimeos Date: Thu, 24 Oct 2024 11:35:35 +0200 Subject: [PATCH 11/15] Added shuffled() method --- README.md | 32 ++++++++++++++++++++++++++++++++ src/Map.php | 24 +++++++++++++++++++++++- tests/MapTest.php | 11 +++++++++++ 3 files changed, 66 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 877b7d1..cbd892d 100644 --- a/README.md +++ b/README.md @@ -239,6 +239,7 @@ will return: set shift shuffle +shuffled skip slice some @@ -371,6 +372,7 @@ will return: * [toReversed()](#toreversed) : Reverses the element order in a copy of the map (alias) * [rsort()](#rsort) : Reverse sort elements using new keys * [shuffle()](#shuffle) : Randomizes the element order +* [shuffled()](#shuffled) : Randomizes the element order in a copy of the map * [sort()](#sort) : Sorts the elements in-place assigning new keys * [sorted()](#sorted) : Sorts the elements in a copy of the map using new keys * [toSorted()](#tosorted) : Sorts the elements in a copy of the map using new keys (alias) @@ -4436,6 +4438,36 @@ Map::from( [2 => 'a', 4 => 'b'] )->shuffle( true ); // [2 => 'a', 4 => 'b'] in random order with keys preserved ``` +**See also:** + +* [shuffled()](#shuffled) - Shuffles the elements in a copy of the map. + + +### shuffled() + +Shuffles the elements in a copy of the map. + +```php +public function shuffled( bool $assoc = false ) : self +``` + +* @param **bool** `$assoc` True to preserve keys, false to assign new keys +* @return **self<int|string,mixed>** New map with a shuffled copy of the elements + +**Examples:** + +```php +Map::from( [2 => 'a', 4 => 'b'] )->shuffled(); +// ['a', 'b'] in random order with new keys + +Map::from( [2 => 'a', 4 => 'b'] )->shuffled( true ); +// [2 => 'a', 4 => 'b'] in random order with keys preserved +``` + +**See also:** + +* [shuffle()](#shuffle) - Shuffles the elements in the map without returning a new map + ### skip() diff --git a/src/Map.php b/src/Map.php index 04adaec..7b8dad5 100644 --- a/src/Map.php +++ b/src/Map.php @@ -3936,6 +3936,7 @@ public function shift() * * @param bool $assoc True to preserve keys, false to assign new keys * @return self Updated map for fluid interface + * @see shuffled() - Shuffles the elements in a copy of the map */ public function shuffle( bool $assoc = false ) : self { @@ -3957,11 +3958,32 @@ public function shuffle( bool $assoc = false ) : self shuffle( $this->list() ); } - return $this; } + /** + * Shuffles the elements in a copy of the map. + * + * Examples: + * Map::from( [2 => 'a', 4 => 'b'] )->shuffled(); + * Map::from( [2 => 'a', 4 => 'b'] )->shuffled( true ); + * + * Results: + * The map in the first example will contain "a" and "b" in random order and + * with new keys assigned. The second call will also return all values in + * random order but preserves the keys of the original list. + * + * @param bool $assoc True to preserve keys, false to assign new keys + * @return self New map with a shuffled copy of the elements + * @see shuffle() - Shuffles the elements in the map without returning a new map + */ + public function shuffled( bool $assoc = false ) : self + { + return ( clone $this )->shuffle( $assoc ); + } + + /** * Returns a new map with the given number of items skipped. * diff --git a/tests/MapTest.php b/tests/MapTest.php index 1ff994b..0fedfea 100644 --- a/tests/MapTest.php +++ b/tests/MapTest.php @@ -2730,6 +2730,17 @@ public function testShuffleAssoc() } + public function testShuffled() + { + $m = new Map( range( 0, 100, 10 ) ); + $r = $m->shuffled(); + + $this->assertNotSame( $r, $m ); + $this->assertInstanceOf( Map::class, $r ); + $this->assertNotEquals( $r->toArray(), $m->toArray() ); + } + + public function testSkip() { $this->assertSame( [2 => 3, 3 => 4], Map::from( [1, 2, 3, 4] )->skip( 2 )->toArray() ); From 331a134628ee489da24f65f68067b389294f1853 Mon Sep 17 00:00:00 2001 From: Aimeos Date: Thu, 24 Oct 2024 11:43:05 +0200 Subject: [PATCH 12/15] Added "see also" sections for map()/rekey()/transform() --- README.md | 15 +++++++++++++++ src/Map.php | 6 ++++++ 2 files changed, 21 insertions(+) diff --git a/README.md b/README.md index cbd892d..00345e5 100644 --- a/README.md +++ b/README.md @@ -549,6 +549,11 @@ map( function() { } ); ``` +**See also:** + +* [rekey()](#rekey) - Changes the keys according to the passed function +* [transform()](#transform) - Creates new key/value pairs using the passed function and returns a new map for the result + ### __construct() @@ -4144,6 +4149,11 @@ Map::from( ['a' => 2, 'b' => 4] )->rekey( function( $value, $key ) { // ['key-a' => 2, 'key-b' => 4] ``` +**See also:** + +* [map()](#map) - Maps new values to the existing keys using the passed function and returns a new map for the result +* [transform()](#transform) - Creates new key/value pairs using the passed function and returns a new map for the result + ### remove() @@ -5550,6 +5560,11 @@ Map::from( ['la' => 2, 'le' => 4, 'li' => 6] )->transform( function( $value, $ke // ['l' => 12] ``` +**See also:** + +* [map()](#map) - Maps new values to the existing keys using the passed function and returns a new map for the result +* [rekey()](#rekey) - Changes the keys according to the passed function + ### transpose() diff --git a/src/Map.php b/src/Map.php index 7b8dad5..0e4dfdc 100644 --- a/src/Map.php +++ b/src/Map.php @@ -2853,6 +2853,8 @@ public function ltrim( string $chars = " \n\r\t\v\x00" ) : self * * @param callable $callback Function with (value, key) parameters and returns computed result * @return self New map with the original keys and the computed values + * @see rekey() - Changes the keys according to the passed function + * @see transform() - Creates new key/value pairs using the passed function and returns a new map for the result */ public function map( callable $callback ) : self { @@ -3653,6 +3655,8 @@ public function reject( $callback = true ) : self * * @param callable $callback Function with (value, key) parameters and returns new key * @return self New map with new keys and original values + * @see map() - Maps new values to the existing keys using the passed function and returns a new map for the result + * @see transform() - Creates new key/value pairs using the passed function and returns a new map for the result */ public function rekey( callable $callback ) : self { @@ -5029,6 +5033,8 @@ public function toUrl() : string * * @param \Closure $callback Function with (value, key) parameters and returns an array of new key/value pair(s) * @return self New map with the new key/value pairs + * @see map() - Maps new values to the existing keys using the passed function and returns a new map for the result + * @see rekey() - Changes the keys according to the passed function */ public function transform( \Closure $callback ) : self { From 95392b67192f1cfba23ac3f67368053392c92358 Mon Sep 17 00:00:00 2001 From: Aimeos Date: Tue, 29 Oct 2024 09:46:11 +0100 Subject: [PATCH 13/15] Minor wording --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 00345e5..741e16b 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Supported PHP versions: * [Add](#add) * [Aggregate](#aggregate) * [Debug](#debug) - * [Order](#orderby) + * [Order](#order-by) * [Shorten](#shorten) * [Test](#test) * [Transform](#transform) @@ -360,7 +360,7 @@ will return: * [dump()](#dump) : Prints the map content * [tap()](#tap) : Passes a clone of the map to the given callback -### OrderBy +### Order By * [arsort()](#arsort) : Reverse sort elements preserving keys * [asort()](#asort) : Sort elements preserving keys From 4e98b889dbe493a8b00405ca5c6a81c0806cb4a8 Mon Sep 17 00:00:00 2001 From: Aimeos Date: Wed, 6 Nov 2024 12:08:50 +0100 Subject: [PATCH 14/15] Fixed PHP 8.4 deprecations --- src/Map.php | 52 ++++++++++++++++++++++++++-------------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/src/Map.php b/src/Map.php index 0e4dfdc..6009b84 100644 --- a/src/Map.php +++ b/src/Map.php @@ -317,7 +317,7 @@ public static function fromJson( string $json, int $options = JSON_BIGINT_AS_STR * @param \Closure|null $fcn Anonymous function or NULL to return the closure if available * @return \Closure|null Registered anonymous function or NULL if none has been registered */ - public static function method( string $method, \Closure $fcn = null ) : ?\Closure + public static function method( string $method, ?\Closure $fcn = null ) : ?\Closure { if( $fcn ) { self::$methods[$method] = $fcn; @@ -808,7 +808,7 @@ public function clone() : self * @param string|null $indexcol Name or path of the index property * @return self New map with mapped entries */ - public function col( string $valuecol = null, string $indexcol = null ) : self + public function col( ?string $valuecol = null, ?string $indexcol = null ) : self { $vparts = explode( $this->sep, (string) $valuecol ); $iparts = explode( $this->sep, (string) $indexcol ); @@ -862,7 +862,7 @@ public function col( string $valuecol = null, string $indexcol = null ) : self * @return self New map with all sub-array elements added into it recursively, up to the specified depth * @throws \InvalidArgumentException If depth must be greater or equal than 0 or NULL */ - public function collapse( int $depth = null ) : self + public function collapse( ?int $depth = null ) : self { if( $depth < 0 ) { throw new \InvalidArgumentException( 'Depth must be greater or equal than 0 or NULL' ); @@ -982,7 +982,7 @@ public function concat( iterable $elements ) : self * @param mixed $value Value used for comparison * @return bool TRUE if at least one element is available in map, FALSE if the map contains none of them */ - public function contains( $key, string $operator = null, $value = null ) : bool + public function contains( $key, ?string $operator = null, $value = null ) : bool { if( $operator === null ) { return $this->some( $key ); @@ -1044,7 +1044,7 @@ public function count() : int * @param callable|null $callback Function with (value, key) parameters which returns the value to use for counting * @return self New map with values as keys and their count as value */ - public function countBy( callable $callback = null ) : self + public function countBy( ?callable $callback = null ) : self { $callback = $callback ?: function( $value ) { return (string) $value; @@ -1073,7 +1073,7 @@ public function countBy( callable $callback = null ) : self * * @param callable|null $callback Function receiving the map elements as parameter (optional) */ - public function dd( callable $callback = null ) : void + public function dd( ?callable $callback = null ) : void { $this->dump( $callback ); exit( 1 ); @@ -1109,7 +1109,7 @@ public function dd( callable $callback = null ) : void * @param callable|null $callback Function with (valueA, valueB) parameters and returns -1 (<), 0 (=) and 1 (>) * @return self New map */ - public function diff( iterable $elements, callable $callback = null ) : self + public function diff( iterable $elements, ?callable $callback = null ) : self { if( $callback ) { return new static( array_udiff( $this->list(), $this->array( $elements ), $callback ) ); @@ -1150,7 +1150,7 @@ public function diff( iterable $elements, callable $callback = null ) : self * @param callable|null $callback Function with (valueA, valueB) parameters and returns -1 (<), 0 (=) and 1 (>) * @return self New map */ - public function diffAssoc( iterable $elements, callable $callback = null ) : self + public function diffAssoc( iterable $elements, ?callable $callback = null ) : self { if( $callback ) { return new static( array_diff_uassoc( $this->list(), $this->array( $elements ), $callback ) ); @@ -1190,7 +1190,7 @@ public function diffAssoc( iterable $elements, callable $callback = null ) : sel * @param callable|null $callback Function with (keyA, keyB) parameters and returns -1 (<), 0 (=) and 1 (>) * @return self New map */ - public function diffKeys( iterable $elements, callable $callback = null ) : self + public function diffKeys( iterable $elements, ?callable $callback = null ) : self { if( $callback ) { return new static( array_diff_ukey( $this->list(), $this->array( $elements ), $callback ) ); @@ -1225,7 +1225,7 @@ public function diffKeys( iterable $elements, callable $callback = null ) : self * @param callable|null $callback Function receiving the map elements as parameter (optional) * @return self Same map for fluid interface */ - public function dump( callable $callback = null ) : self + public function dump( ?callable $callback = null ) : self { $callback ? $callback( $this->list() ) : print_r( $this->list() ); return $this; @@ -1258,7 +1258,7 @@ public function dump( callable $callback = null ) : self * @param string|null $key Key or path of the nested array or object to check for * @return self New map */ - public function duplicates( string $key = null ) : self + public function duplicates( ?string $key = null ) : self { $list = $this->list(); $items = ( $key !== null ? $this->col( $key )->toArray() : $list ); @@ -1420,7 +1420,7 @@ public function except( $keys ) : self * @param callable|null $callback Function with (item, key) parameters and returns TRUE/FALSE * @return self New map */ - public function filter( callable $callback = null ) : self + public function filter( ?callable $callback = null ) : self { if( $callback ) { return new static( array_filter( $this->list(), $callback, ARRAY_FILTER_USE_BOTH ) ); @@ -1561,7 +1561,7 @@ public function firstKey() * @return self New map with all sub-array elements added into it recursively, up to the specified depth * @throws \InvalidArgumentException If depth must be greater or equal than 0 or NULL */ - public function flat( int $depth = null ) : self + public function flat( ?int $depth = null ) : self { if( $depth < 0 ) { throw new \InvalidArgumentException( 'Depth must be greater or equal than 0 or NULL' ); @@ -1897,7 +1897,7 @@ public function has( $key ) : bool * @param \Closure|null $else Function with (map, condition) parameter (optional) * @return self New map */ - public function if( $condition, \Closure $then = null, \Closure $else = null ) : self + public function if( $condition, ?\Closure $then = null, ?\Closure $else = null ) : self { if( $condition instanceof \Closure ) { $condition = $condition( $this ); @@ -1950,7 +1950,7 @@ public function if( $condition, \Closure $then = null, \Closure $else = null ) : * @param \Closure|null $else Function with (map, condition) parameter (optional) * @return self New map */ - public function ifAny( \Closure $then = null, \Closure $else = null ) : self + public function ifAny( ?\Closure $then = null, ?\Closure $else = null ) : self { return $this->if( !empty( $this->list() ), $then, $else ); } @@ -1988,7 +1988,7 @@ public function ifAny( \Closure $then = null, \Closure $else = null ) : self * @param \Closure|null $else Function with (map, condition) parameter (optional) * @return self New map */ - public function ifEmpty( \Closure $then = null, \Closure $else = null ) : self + public function ifEmpty( ?\Closure $then = null, ?\Closure $else = null ) : self { return $this->if( empty( $this->list() ), $then, $else ); } @@ -2344,7 +2344,7 @@ public function int( $key, $default = 0 ) : int * @param callable|null $callback Function with (valueA, valueB) parameters and returns -1 (<), 0 (=) and 1 (>) * @return self New map */ - public function intersect( iterable $elements, callable $callback = null ) : self + public function intersect( iterable $elements, ?callable $callback = null ) : self { $list = $this->list(); $elements = $this->array( $elements ); @@ -2390,7 +2390,7 @@ public function intersect( iterable $elements, callable $callback = null ) : sel * @param callable|null $callback Function with (valueA, valueB) parameters and returns -1 (<), 0 (=) and 1 (>) * @return self New map */ - public function intersectAssoc( iterable $elements, callable $callback = null ) : self + public function intersectAssoc( iterable $elements, ?callable $callback = null ) : self { $elements = $this->array( $elements ); @@ -2433,7 +2433,7 @@ public function intersectAssoc( iterable $elements, callable $callback = null ) * @param callable|null $callback Function with (keyA, keyB) parameters and returns -1 (<), 0 (=) and 1 (>) * @return self New map */ - public function intersectKeys( iterable $elements, callable $callback = null ) : self + public function intersectKeys( iterable $elements, ?callable $callback = null ) : self { $list = $this->list(); $elements = $this->array( $elements ); @@ -3347,7 +3347,7 @@ public function pipe( \Closure $callback ) * @return self New map with mapped entries * @see col() - Underlying method with same parameters and return value but better performance */ - public function pluck( string $valuecol = null, string $indexcol = null ) : self + public function pluck( ?string $valuecol = null, ?string $indexcol = null ) : self { return $this->col( $valuecol, $indexcol ); } @@ -3441,7 +3441,7 @@ public function pos( $value ) : ?int * @param int|null $depth Maximum depth to dive into multi-dimensional arrays starting from "1" * @return self Updated map for fluid interface */ - public function prefix( $prefix, int $depth = null ) : self + public function prefix( $prefix, ?int $depth = null ) : self { $fcn = function( array $list, $prefix, int $depth ) use ( &$fcn ) { @@ -4062,7 +4062,7 @@ public function skip( $offset ) : self * @param int|null $length Number of elements to return or NULL for no limit * @return self New map */ - public function slice( int $offset, int $length = null ) : self + public function slice( int $offset, ?int $length = null ) : self { return new static( array_slice( $this->list(), $offset, $length, true ) ); } @@ -4214,7 +4214,7 @@ public function sorted( int $options = SORT_REGULAR ) : self * @param mixed $replacement List of elements to insert * @return self New map */ - public function splice( int $offset, int $length = null, $replacement = [] ) : self + public function splice( int $offset, ?int $length = null, $replacement = [] ) : self { if( $length === null ) { $length = count( $this->list() ); @@ -4784,7 +4784,7 @@ public function strUpper( string $encoding = 'UTF-8' ) :self * @param int|null $depth Maximum depth to dive into multi-dimensional arrays starting from "1" * @return self Updated map for fluid interface */ - public function suffix( $suffix, int $depth = null ) : self + public function suffix( $suffix, ?int $depth = null ) : self { $fcn = function( $list, $suffix, $depth ) use ( &$fcn ) { @@ -5160,7 +5160,7 @@ public function transpose() : self * @param string $nestKey Key to the children of each item * @return self New map with all items as flat list */ - public function traverse( \Closure $callback = null, string $nestKey = 'children' ) : self + public function traverse( ?\Closure $callback = null, string $nestKey = 'children' ) : self { $result = []; $this->visit( $this->list(), $result, 0, $callback, $nestKey ); @@ -5375,7 +5375,7 @@ public function union( iterable $elements ) : self * @param string|null $key Key or path of the nested array or object to check for * @return self New map */ - public function unique( string $key = null ) : self + public function unique( ?string $key = null ) : self { if( $key !== null ) { return $this->col( null, $key )->values(); From f813bc1aa0f23761ef9967d453d25e1083611d40 Mon Sep 17 00:00:00 2001 From: Aimeos Date: Wed, 6 Nov 2024 12:09:14 +0100 Subject: [PATCH 15/15] Allow PHPUnit 10 and 11 for testing --- composer.json | 2 +- tests/MapTest.php | 20 +++++++------------- 2 files changed, 8 insertions(+), 14 deletions(-) diff --git a/composer.json b/composer.json index ac52558..b5a66d5 100644 --- a/composer.json +++ b/composer.json @@ -11,7 +11,7 @@ "require-dev": { "squizlabs/php_codesniffer": "^3.5", "php-coveralls/php-coveralls": "~2.0", - "phpunit/phpunit": "~7.0||~8.0||~9.0" + "phpunit/phpunit": "~7.0||~8.0||~9.0||~10.0||~11.0" }, "autoload": { "psr-4": { diff --git a/tests/MapTest.php b/tests/MapTest.php index 0fedfea..1bc6fc6 100644 --- a/tests/MapTest.php +++ b/tests/MapTest.php @@ -1247,20 +1247,14 @@ public function testGrepException() { set_error_handler( function( $errno, $str, $file, $line ) { return true; } ); - $this->expectException( \RuntimeException::class ); - Map::from( [] )->grep( 'b' ); - } - - - public function testGrepWarning() - { - if( method_exists( $this, 'expectWarning' ) ) { - $this->expectWarning(); // PHPUnit 8+ - } else { - $this->expectException( \PHPUnit\Framework\Error\Warning::class ); // PHP 7.1 + try { + Map::from( [] )->grep( 'b' ); + $this->fail( 'An expected RuntimeException has not been raised' ); + } catch( \RuntimeException $e ) { + $this->assertStringContainsString( 'Regular expression error', $e->getMessage() ); + } finally { + restore_error_handler(); } - - Map::from( [] )->grep( 'b' ); }