====== PHP RFC: array_search_range() ======

  * Version: 0.1 (Draft)
  * Date: 2026-08-11
  * Author: Sepehr Mahmoudi
  * Email: [[mailto:sepehrphpr@gmail.com|sepehrphpr@gmail.com]]
  * Target PHP Version: PHP 8.6
  * Status: Draft
  * Implementation: [[https://github.com/php/php-src/pull/YOUR_PR_NUMBER|PR #YOUR_PR_NUMBER (Pending)]]

===== Introduction =====

This RFC proposes a new core function named ''array_search_range()''.

The function searches for a value within a positional range of an existing array. 
It is intended for cases where an application needs to search only a part of an 
array, without first creating an intermediate array using ''array_slice()''.

===== Proposed Function Signature =====

<code php>
function array_search_range(
    mixed $needle,
    array $haystack,
    int $offset = 0,
    ?int $length = null,
    bool $strict = false,
): int|string|false {}
</code>

===== Summary =====

''array_search_range()'' searches for the first matching value in a selected 
range of an array and returns the original key of that value.

Like ''array_search()'', it returns the actual key of the element. If no value 
matches, it returns ''false''.

===== Motivation =====

Currently, searching a portion of an array requires ''array_slice()'':

<code php>
$range = array_slice($languages, 100, 50, true);
$key = array_search('PHP', $range, true);
</code>

This approach has two main drawbacks:
1. It creates an intermediate array, which consumes additional memory.
2. It requires two function calls instead of one.

The proposed function iterates over the original array directly, avoiding 
unnecessary memory allocation for an intermediate structure.

===== Parameters =====

==== $needle ====
The value to search for.

==== $haystack ====
The array in which the search is performed.

==== $offset ====
The zero-based positional offset at which searching begins. 
  * If $offset is negative, searching begins relative to the end of the array.
  * If $offset is out of bounds (greater than array size), the function returns ''false''.

==== $length ====
The number of elements to inspect. 
  * When ''null'', the function searches from ''$offset'' to the end of the array.
  * If the requested length exceeds the remaining elements, the function searches until the end.
  * If $length is 0, the function returns ''false''.
  * If $length is negative, the search excludes that number of elements from the end.

==== $strict ====
Whether to use strict comparison (''==='' vs ''=='').

===== Detailed Behavior =====

==== Positional Range Versus Array Keys ====
The range is defined by positional order, not by the values of keys. 
<code php>
$array = [100 => 'alpha', 500 => 'target'];
// Search starts at the 2nd element (index 1), even if its key is 500
$key = array_search_range('target', $array, 1, 1, true);
var_dump($key); // int(500)
</code>

==== Mixed Keys Example ====
The function correctly preserves and returns the original keys regardless of whether they are integers or strings.
<code php>
$mixedArray = ['a' => 'val1', 10 => 'val2', 'b' => 'target'];
$key = array_search_range('target', $mixedArray, 0, 3, true);
var_dump($key); // string(1) "b"
</code>

==== Error Handling ====
* If $offset is invalid or outside the array bounds, the function returns ''false''.
* This function does not throw exceptions for valid input ranges, maintaining 
consistency with ''array_slice()''.

===== Examples =====

==== Basic Search ====
<code php>
$languages = ['HTML', 'CSS', 'JavaScript', 'PHP', 'Python'];
$key = array_search_range('PHP', $languages, 0, null, true);
var_dump($key); // int(3)
</code>

==== Search Within a Specific Range ====
<code php>
$items = ['zero', 'one', 'two', 'target', 'four', 'target'];
$key = array_search_range('target', $items, 2, 3, true);
var_dump($key); // int(3)
</code>

==== Persian Associative Array Example ====
<code php>
$users = ['u_101' => 'علی', 'u_103' => 'سپهر'];
$key = array_search_range('سپهر', $users, 0, null, true);
var_dump($key); // string(5) "u_103"
</code>

===== Performance Considerations =====

Compared to ''array_slice()'', this function avoids creating a temporary 
''HashTable''. For an array of 100,000 elements, searching a range avoids 
allocating memory for the temporary slice, reducing GC pressure and 
CPU cycles required for array duplication.

===== Implementation Plan =====

The implementation focuses on direct ''HashTable'' iteration. The code 
will be submitted as a Pull Request to [[https://github.com/php/php-src|php-src]]. 
Full PHPT test coverage for edge cases including negative offsets, 
negative lengths, and mixed key types is included.

===== Proposed PHP Version =====

PHP 8.6.

===== Changelog =====

  * 0.1 — Initial draft by Sepehr Mahmoudi.