diff --git a/README.md b/README.md index b5fcb72..e6ac28b 100644 --- a/README.md +++ b/README.md @@ -118,6 +118,7 @@ will return: * [filter()](#filter) : Applies a filter to the map elements * [find()](#find) : Returns the first matching element * [first()](#first) : Returns the first element +* [firstKey()](#firstkey) : Returns the first key * [flip()](#flip) : Exchanges keys with their values * [flat()](#flat) : Flattens multi-dimensional elements * [from()](#from) : Creates a new map from passed elements @@ -135,6 +136,7 @@ will return: * [krsort()](#krsort) : Reverse sort elements by keys * [ksort()](#ksort) : Sort elements by keys * [last()](#last) : Returns the last element +* [lastKey()](#lastkey) : Returns the last key * [map()](#map) : Applies a callback to each element and returns the results * [merge()](#merge) : Combines elements overwriting existing ones * [method()](#method) : Registers a custom method @@ -806,6 +808,28 @@ The first example will return 'a' and the second one 'x'. The third example will throw the exception passed if the map contains no elements. +### firstKey() + +Returns the first key from the map. + +```php +public function firstKey() +``` + +* @return mixed First key of map or `NULL` if empty + +**Examples:** + +```php +Map::from( ['a' => 1, 'b' => 2] )->lastKey(); +Map::from( [] )->lastKey(); +``` + +**Results:** + +The first example will return 'a' and the second one `NULL`. + + ### flat() Creates a new map with all sub-array elements added recursively @@ -1312,6 +1336,28 @@ The first example will return 'b' and the second one 'x'. The third example will throw the exception passed if the map contains no elements. +### lastKey() + +Returns the last key from the map. + +```php +public function lastKey() +``` + +* @return mixed Last key of map or `NULL` if empty + +**Examples:** + +```php +Map::from( ['a' => 1, 'b' => 2] )->lastKey(); +Map::from( [] )->lastKey(); +``` + +**Results:** + +The first example will return 'b' and the second one `NULL`. + + ### map() Calls the passed function once for each element and returns a new map for the result. diff --git a/src/Map.php b/src/Map.php index 16af864..81f377f 100644 --- a/src/Map.php +++ b/src/Map.php @@ -659,8 +659,6 @@ public function find( \Closure $callback, bool $last = false ) * will throw the exception passed if the map contains no elements. * * @param mixed $default Default value or exception if the map contains no elements - * - * @param mixed $default Default value if map is empty * @return mixed First value of map or default value */ public function first( $default = null ) @@ -677,6 +675,29 @@ public function first( $default = null ) } + /** + * Returns the first key from the map. + * + * Examples: + * Map::from( ['a' => 1, 'b' => 2] )->firstKey(); + * Map::from( [] )->firstKey(); + * + * Results: + * The first example will return 'a' and the second one NULL. + * + * @return mixed First key of map or NULL if empty + */ + public function firstKey() + { + if( function_exists( 'array_key_first' ) ) { + return array_key_first( $this->list ); + } + + reset( $this->list ); + return key( $this->list); + } + + /** * Creates a new map with all sub-array elements added recursively * @@ -1147,6 +1168,29 @@ public function last( $default = null ) } + /** + * Returns the last key from the map. + * + * Examples: + * Map::from( ['a' => 1, 'b' => 2] )->lastKey(); + * Map::from( [] )->lastKey(); + * + * Results: + * The first example will return 'b' and the second one NULL. + * + * @return mixed Last key of map or NULL if empty + */ + public function lastKey() + { + if( function_exists( 'array_key_last' ) ) { + return array_key_last( $this->list ); + } + + end( $this->list ); + return key( $this->list ); + } + + /** * Calls the passed function once for each element and returns a new map for the result. * diff --git a/tests/MapTest.php b/tests/MapTest.php index 8388e25..7370bb1 100644 --- a/tests/MapTest.php +++ b/tests/MapTest.php @@ -528,6 +528,18 @@ public function testFirstWithException() } + public function testFirstKey() + { + $this->assertEquals( 'a', Map::from( ['a' => 1, 'b' => 2] )->firstKey() ); + } + + + public function testFirstKeyEmpty() + { + $this->assertEquals( null, Map::from( [] )->firstKey() ); + } + + public function testFlat() { $m = Map::from( [[0, 1], [2, 3]] ); @@ -828,6 +840,18 @@ public function testLastWithException() } + public function testLastKey() + { + $this->assertEquals( 'b', Map::from( ['a' => 1, 'b' => 2] )->lastKey() ); + } + + + public function testLastKeyEmpty() + { + $this->assertEquals( null, Map::from( [] )->lastKey() ); + } + + public function testMap() { $m = new Map( ['first' => 'test', 'last' => 'user'] );