1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
/// 🔍 Returns the index of the **first** element in the slice that satisfies the predicate.
///
/// # Type Parameters
/// - `T`: The type of elements in the slice.
/// - `M`: A predicate function or closure that takes a reference to an element and returns `true` if it matches.
///
/// # Arguments
/// - `values`: A reference to a slice of elements to be scanned.
/// - `matcher`: A predicate function applied to each element.
///
/// # Returns
/// - `Some(index)` of the first matching element, or
/// - `None` if no element satisfies the predicate.
///
/// # Behavior
/// - Scans elements in order.
/// - Returns immediately on the first match.
/// - If no element matches, returns `None`.
///
/// # Performance
/// - ✅ Best-case: **O(1)** if the first element matches.
/// - ✅ Worst-case: **O(n)** if no elements match or match is last.
/// - 🚫 No allocations or cloning.
///
/// # Examples
/// 🔢 Integers:
/// ```rust
/// use pencil_box::array::find_index::find_index;
///
/// let values = [5, 8, 12, 7];
/// let result = find_index(&values, |x| x % 2 == 0);
/// assert_eq!(result, Some(1));
///
/// let result_none = find_index(&values, |x| *x > 100);
/// assert_eq!(result_none, None);
/// ```
///
/// 🧱 Structs:
/// ```rust
/// struct Task {
/// id: u32,
/// done: bool,
/// }
///
/// let tasks = [
/// Task { id: 1, done: false },
/// Task { id: 2, done: true },
/// ];
///
/// let first_done = find_index(&tasks, |t| t.done);
/// assert_eq!(first_done, Some(1));
/// ```
///
/// 🎭 Enums:
/// ```rust
/// enum Status {
/// Ready,
/// Failed,
/// }
///
/// let statuses = [Status::Ready, Status::Failed, Status::Failed];
/// let result = find_index(&statuses, |s| matches!(s, Status::Failed));
/// assert_eq!(result, Some(1));
/// ```
///
/// # Panic Safety
/// ✅ Guaranteed panic-free for all valid inputs.
///