From 75b6ef4459a6738bf04940c96333fbdb3de0e4f0 Mon Sep 17 00:00:00 2001
From: Aimeos <aimeos@aimeos.org>
Date: Sat, 30 Nov 2024 18:20:44 +0100
Subject: [PATCH] Added any() method

---
 README.md         | 28 ++++++++++++++++++++++++++++
 src/Map.php       | 36 +++++++++++++++++++++++++++++++++++-
 tests/MapTest.php | 14 ++++++++++++++
 3 files changed, 77 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 736d1b5..8112964 100644
--- a/README.md
+++ b/README.md
@@ -312,6 +312,7 @@ will return:
 * [__call()](#__call) : Calls a custom method
 * [__callStatic()](#__callstatic) : Calls a custom method statically
 * [all()](#all) : Returns the plain array
+* [any()](#any) : Tests if at least one element satisfies the callback function
 * [at()](#at) : Returns the value at the given position
 * [bool()](#bool) : Returns an element by key and casts it to boolean
 * [call()](#call) : Calls the given method on all items
@@ -425,6 +426,7 @@ will return:
 ### Test
 
 * [function is_map()](#is_map-function) : Tests if the variable is a map object
+* [any()](#any) : Tests if at least one element satisfies the callback function
 * [compare()](#compare) : Compares the value against all map elements
 * [contains()](#contains) : Tests if an item exists in the map
 * [each()](#each) : Applies a callback to each element
@@ -727,6 +729,32 @@ Map::from( ['a'] )->all();
 ```
 
 
+### any()
+
+Tests if at least one element satisfies the callback function.
+
+```php
+public function any( \Closure $callback ) : bool
+```
+
+* @param \Closure $callback Anonymous function with (item, key) parameter
+* @return bool TRUE if at least one element satisfies the callback function, FALSE if not
+
+**Examples:**
+
+```php
+Map::from( ['a', 'b'] )->any( function( $item, $key ) {
+    return $item === 'a';
+} );
+// TRUE
+
+Map::from( ['a', 'b'] )->any( function( $item, $key ) {
+    return !is_string( $item );
+} );
+// FALSE
+```
+
+
 ### arsort()
 
 Sorts all elements in reverse order and maintains the key association.
diff --git a/src/Map.php b/src/Map.php
index b4b5238..03fa993 100644
--- a/src/Map.php
+++ b/src/Map.php
@@ -414,6 +414,40 @@ public function all() : array
 	}
 
 
+	/**
+	 * Tests if at least one element satisfies the callback function.
+	 *
+	 * Examples:
+	 *  Map::from( ['a', 'b'] )->any( function( $item, $key ) {
+	 *    return $item === 'a';
+	 *  } );
+	 *  Map::from( ['a', 'b'] )->any( function( $item, $key ) {
+	 *    return !is_string( $item );
+	 *  } );
+	 *
+	 * Results:
+	 * The first example will return TRUE while the last one will return FALSE
+	 *
+	 * @param \Closure $callback Anonymous function with (item, key) parameter
+	 * @return bool TRUE if at least one element satisfies the callback function, FALSE if not
+	 */
+	public function any( \Closure $callback ) : bool
+	{
+		if( function_exists( 'array_any' ) ) {
+			return array_any( $this->list(), $callback );
+		}
+
+		foreach( $this->list() as $key => $item )
+		{
+			if( $callback( $item, $key ) ) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+
 	/**
 	 * Sorts all elements in reverse order and maintains the key association.
 	 *
@@ -4246,7 +4280,7 @@ public function slice( int $offset, ?int $length = null ) : self
 	 *  Map::from( ['a', 'b'] )->some( 'a' );
 	 *  Map::from( ['a', 'b'] )->some( ['a', 'c'] );
 	 *  Map::from( ['a', 'b'] )->some( function( $item, $key ) {
-	 *    return $item === 'a'
+	 *    return $item === 'a';
 	 *  } );
 	 *  Map::from( ['a', 'b'] )->some( ['c', 'd'] );
 	 *  Map::from( ['1', '2'] )->some( [2], true );
diff --git a/tests/MapTest.php b/tests/MapTest.php
index a1057a6..e5fc60c 100644
--- a/tests/MapTest.php
+++ b/tests/MapTest.php
@@ -75,6 +75,20 @@ public function testAll()
 	}
 
 
+	public function testAny()
+	{
+		$result = Map::from( ['a', 'b'] )->any( function( $item, $key ) {
+			return $item === 'a';
+		} );
+		$this->assertTrue( $result );
+
+		$result = Map::from( ['a', 'b'] )->any( function( $item, $key ) {
+			return !is_string( $item );
+		} );
+		$this->assertFalse( $result );
+	}
+
+
 	public function testArsortNummeric()
 	{
 		$m = ( new Map( [1 => -3, 2 => -2, 3 => -4, 4 => -1, 5 => 0, 6 => 4, 7 => 3, 8 => 1, 9 => 2] ) )->arsort();