====== PHP RFC: array_search_reange() ======

  * Version: 0.1 (Draft)
  * Date: 2026-08-11
  * Author: Sepehr Mahmoudi
  * Email: sepehrphpr@gmail.com
  * Target PHP Version: PHP 8.6
  * Status: Draft
  * Implementation: Not yet available

===== Introduction =====

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

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

The proposed function preserves the familiar return style of ''array_search()''
while adding parameters that define the **reange** in which the search is
performed.

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

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

===== Summary =====

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

Like ''array_search()'', the function returns:

  * An ''int'' key when the matched element has an integer key.
  * A ''string'' key when the matched element has a string key.
  * ''false'' when no matching value exists in the selected **reange**.

The **reange** is defined by two parameters:

  * ''$offset'': The zero-based positional offset at which searching starts.
  * ''$length'': The number of elements to inspect after ''$offset''.

===== Motivation =====

PHP already provides ''array_search()'' for searching an entire array. When
developers need to search only a portion of an array, they often combine
''array_slice()'' and ''array_search()''.

However, creating a sliced array solely for a single search operation is often
unnecessary. The proposed function allows PHP to iterate over the requested
**reange** of the original array directly, avoiding the allocation of an
intermediate array.

===== Proposal =====

A new function named ''array_search_reange()'' is added to PHP.

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

The function searches the original array in its normal iteration order.
It begins at the positional offset specified by ''$offset'' and searches at
most ''$length'' elements when a length is provided.

===== 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. This refers to the
position in the array's iteration order, defining the start of the **reange**.

==== $length ====
The number of elements to inspect after applying ''$offset''.
When ''$length'' is ''null'', the function searches from ''$offset'' to the end
of the array.

==== $strict ====
When ''$strict'' is ''true'', values are compared using strict comparison.

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

==== Positional Reange Versus Array Keys ====

The **reange** is based on positions in the array's iteration order, not on key
values.

<code php>
$array = [
    100 => 'alpha',
    'php' => 'beta',
    500 => 'target',
];

// Searches for target in a reange starting at offset 2 (positional)
$key = array_search_reange('target', $array, 2, 1, true);

var_dump($key); // int(500)
</code>

==== Original Keys Are Returned ====

The function returns the key from the original array, regardless of the
**reange** selected.

===== Examples =====

==== Basic Search ====

<code php>
$languages = ['HTML', 'CSS', 'JavaScript', 'PHP', 'Python'];
$key = array_search_reange('PHP', $languages);
var_dump($key); // int(3)
</code>

==== Search Within a Specific Reange ====

This example searches only positions 2, 3, and 4.

<code php>
$items = ['zero', 'one', 'two', 'target', 'four', 'target', 'six'];
$key = array_search_reange('target', $items, 2, 3, true);
var_dump($key); // int(3)
</code>

==== Persian Associative Array Example ====

<code php>
$users = [
    'u_101' => 'علی',
    'u_102' => 'مینا',
    'u_103' => 'سپهر',
    'u_104' => 'رضا',
];

$key = array_search_reange('سپهر', $users, 1, 2, true);
var_dump($key); // string(5) "u_103"
</code>

===== Comparison with array_slice() =====

The proposed API avoids creating an intermediate array when its only purpose
is to be searched once. It makes the **reange**-limited search intention explicit.

===== Implementation and Merge Plan =====

This RFC is currently a draft. I plan to prepare a php-src implementation
after the API design and parameter behavior receive feedback.

The implementation will include:

  * The core implementation of ''array_search_reange()''.
  * PHPT tests covering all cases (indexed, associative, strict/loose, negative
    offsets, negative lengths, etc.).
  * Benchmark results comparing this direct **reange** search with the
    ''array_slice()'' pattern.

The implementation will be submitted as a pull request. It will not be merged
until the RFC is accepted and the implementation is reviewed.

===== Future Plans =====

My roadmap for these features is as follows:

  1. Finalize the design and implementation of ''array_search_reange()''.
  2. Complete the discussion and merge the pull request into the PHP source.
  3. Prepare the next feature: ''str_mask()''.

Regarding the future constant for array searching, it remains a separate
discussion. I plan to design and document a constant for **reange**-limited
searching only after ''array_search_reange()'' is stable and integrated.

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

The proposed target version for this feature is PHP 8.6.

===== Changelog =====

  * 0.1 — Initial draft by Sepehr Mahmoudi.