ArrayHandler add next/prev key search

.phive/phars.xml

@@ -4,6 +4,6 @@
   <phar name="phpcs" version="^3.7.2" installed="3.7.2" location="./tools/phpcs" copy="false"/>
   <phar name="phpcbf" version="^3.7.2" installed="3.7.2" location="./tools/phpcbf" copy="false"/>
   <phar name="psalm" version="^5.15.0" installed="5.15.0" location="./tools/psalm" copy="false"/>
-  <phar name="phpstan" version="^1.10.37" installed="1.10.37" location="./tools/phpstan" copy="false"/>
+  <phar name="phpstan" version="^1.10.37" installed="1.10.40" location="./tools/phpstan" copy="false"/>
   <phar name="phan" version="^5.4.2" installed="5.4.2" location="./tools/phan" copy="false"/>
 </phive>

src/Combined/ArrayHandler.php

@@ -236,6 +236,54 @@ class ArrayHandler
 		return $hit_list;
 	}
 
+	/**
+	 * main wrapper function for next/prev key
+	 *
+	 * @param  array<mixed>    $array array to search in
+	 * @param  int|string      $key   key for next/prev
+	 * @param  bool            $next  [=true] if to search next or prev
+	 * @return int|string|null        Next/prev key or null for end/first
+	 */
+	private static function arrayGetKey(array $array, int|string $key, bool $next = true): int|string|null
+	{
+		$keys = array_keys($array);
+		if (($position = array_search($key, $keys, true)) === false) {
+			return null;
+		}
+		$next_position = $next ? $position + 1 : $position - 1;
+
+		if (!isset($keys[$next_position])) {
+			return null;
+		}
+		return $keys[$next_position];
+	}
+
+	/**
+	 * Get previous array key from an array
+	 * null on not found
+	 *
+	 * @param  array<mixed>    $array
+	 * @param  int|string      $key
+	 * @return int|string|null        Next key, or null for not found
+	 */
+	public static function arrayGetPrevKey(array $array, int|string $key): int|string|null
+	{
+		return self::arrayGetKey($array, $key, false);
+	}
+
+	/**
+	 * Get next array key from an array
+	 * null on not found
+	 *
+	 * @param  array<mixed>    $array
+	 * @param  int|string      $key
+	 * @return int|string|null        Next key, or null for not found
+	 */
+	public static function arrayGetNextKey(array $array, int|string $key): int|string|null
+	{
+		return self::arrayGetKey($array, $key, true);
+	}
+
 	/**
 	 * correctly recursive merges as an array as array_merge_recursive
 	 * just glues things together

test/phpunit/Combined/CoreLibsCombinedArrayHandlerTest.php

@@ -1098,16 +1098,109 @@ final class CoreLibsCombinedArrayHandlerTest extends TestCase
 	 * @testdox arrayFlatForKey array $input will be $expected [$_dataName]
 	 *
 	 * @param array $input
+	 * @param string $search
 	 * @param array $expected
 	 * @return void
 	 */
-	public function testArrayFlatForKey(array $input, $search, array $expected): void
+	public function testArrayFlatForKey(array $input, string $search, array $expected): void
 	{
 		$this->assertEquals(
 			$expected,
 			\CoreLibs\Combined\ArrayHandler::arrayFlatForKey($input, $search)
 		);
 	}
+
+	/**
+	 * Undocumented function
+	 *
+	 * @return array
+	 */
+	public function providerArrayGetNextPrevKey(): array
+	{
+		return [
+			'find, ok' => [
+				'input' => [
+					'a' => 'First',
+					'b' => 'Second',
+					'c' => 'Third',
+				],
+				'b',
+				'a',
+				'c'
+			],
+			'find, first' => [
+				'input' => [
+					'a' => 'First',
+					'b' => 'Second',
+					'c' => 'Third',
+				],
+				'a',
+				null,
+				'b'
+			],
+			'find, last' => [
+				'input' => [
+					'a' => 'First',
+					'b' => 'Second',
+					'c' => 'Third',
+				],
+				'c',
+				'b',
+				null
+			],
+			'find, not found' => [
+				'input' => [
+					'a' => 'First',
+					'b' => 'Second',
+					'c' => 'Third',
+				],
+				'z',
+				null,
+				null
+			],
+			'int, index' => [
+				'input' => [
+					'a',
+					'b',
+					'c'
+				],
+				1,
+				0,
+				2
+			]
+		];
+	}
+
+	/**
+	 * Undocumented function
+	 *
+	 * @covers ::arrayGetPrevKey, ::arrayGetNextKey
+	 * @dataProvider providerArrayGetNextPrevKey
+	 * @testdox arrayGetNextPrevKey get next/prev key for $search wtih $expected_prev/$expected_next [$_dataName]
+	 *
+	 * @param  array           $input
+	 * @param  int|string      $search
+	 * @param  int|string|null $expected_prev
+	 * @param  int|string|null $expected_next
+	 * @return void
+	 */
+	public function testArrayGetNextPrevKey(
+		array $input,
+		int|string $search,
+		int|string|null $expected_prev,
+		int|string|null $expected_next
+	): void {
+		$this->assertEquals(
+			$expected_prev,
+			\CoreLibs\Combined\ArrayHandler::arrayGetPrevKey($input, $search),
+			'Find prev key in array'
+		);
+		$this->assertEquals(
+			$expected_next,
+			\CoreLibs\Combined\ArrayHandler::arrayGetNextKey($input, $search),
+			'Find next key in array'
+		);
+	}
 }
 
 // __END__

tools/phpstan

@@ -1 +1 @@
-/home/clemens/.phive/phars/phpstan-1.10.37.phar
+/home/clemens/.phive/phars/phpstan-1.10.40.phar