Debian Codegraph @

vendor/ipl/stdlib/src/Seq.php

raw
1 <?php
2
3 namespace ipl\Stdlib;
4
5 use Closure;
6 use Generator;
7 use SplObjectStorage;
8
9 /**
10 * Collection of utilities for traversables
11 */
12 class Seq
13 {
14 /**
15 * Check if the traversable contains the given needle
16 *
17 * @param iterable $traversable
18 * @param mixed $needle Might also be a closure
19 * @param bool $caseSensitive Whether strings should be compared case-sensitive
20 *
21 * @return bool
22 */
23 public static function contains(iterable $traversable, mixed $needle, bool $caseSensitive = true): bool
24 {
25 return self::find($traversable, $needle, $caseSensitive)[0] !== null;
26 }
27
28 /**
29 * Search in the traversable for the given needle and return its key and value
30 *
31 * @param iterable $traversable
32 * @param mixed $needle Might also be a closure
33 * @param bool $caseSensitive Whether strings should be compared case-sensitive
34 *
35 * @return array{0: mixed, 1: mixed} The found key and value, or [null, null] if nothing is found
36 */
37 public static function find(iterable $traversable, mixed $needle, bool $caseSensitive = true): array
38 {
39 $usesCallback = $needle instanceof Closure;
40 if (! $usesCallback && $caseSensitive && is_array($traversable)) {
41 $result = array_search($needle, $traversable, true);
42
43 return match ($result) {
44 false => [null, null],
45 default => [$result, $needle]
46 };
47 }
48
49 if (! $caseSensitive && is_string($needle) && ! $usesCallback) {
50 $needle = strtolower($needle);
51 }
52
53 foreach ($traversable as $key => $item) {
54 $originalItem = $item;
55 if (! $caseSensitive && is_string($item)) {
56 $item = strtolower($item);
57 }
58
59 if ($usesCallback) {
60 /** @var Closure $needle */
61 if ($needle($item)) {
62 return [$key, $originalItem];
63 }
64 } elseif ($item === $needle) {
65 return [$key, $originalItem];
66 }
67 }
68
69 return [null, null];
70 }
71
72 /**
73 * Search in the traversable for the given needle and return its key
74 *
75 * @param iterable $traversable
76 * @param mixed $needle Might also be a closure
77 * @param bool $caseSensitive Whether strings should be compared case-sensitive
78 *
79 * @return mixed|null Null if nothing is found
80 */
81 public static function findKey(iterable $traversable, mixed $needle, bool $caseSensitive = true): mixed
82 {
83 return self::find($traversable, $needle, $caseSensitive)[0];
84 }
85
86 /**
87 * Search in the traversable for the given needle and return its value
88 *
89 * @param iterable $traversable
90 * @param mixed $needle Might also be a closure
91 * @param bool $caseSensitive Whether strings should be compared case-sensitive
92 *
93 * @return mixed|null Null if nothing is found
94 */
95 public static function findValue(iterable $traversable, mixed $needle, bool $caseSensitive = true): mixed
96 {
97 $usesCallback = $needle instanceof Closure;
98 if (! $usesCallback && $caseSensitive && is_array($traversable)) {
99 return $traversable[$needle] ?? null;
100 }
101
102 if (! $caseSensitive && is_string($needle) && ! $usesCallback) {
103 $needle = strtolower($needle);
104 }
105
106 foreach ($traversable as $key => $item) {
107 if (! $caseSensitive && is_string($key)) {
108 $key = strtolower($key);
109 }
110
111 if ($usesCallback) {
112 /** @var Closure $needle */
113 if ($needle($key)) {
114 return $item;
115 }
116 } elseif ($key === $needle) {
117 return $item;
118 }
119 }
120
121 return null;
122 }
123
124 /**
125 * Apply the callback to all elements of the given traversable, while preserving keys
126 *
127 * @param iterable $traversable
128 * @param callable $callback
129 *
130 * @return Generator
131 */
132 public static function map(iterable $traversable, callable $callback): Generator
133 {
134 foreach ($traversable as $key => $value) {
135 yield $key => $callback($value);
136 }
137 }
138
139 /**
140 * Yield every unique value of the given traversable with its original key
141 *
142 * Values are compared type-sensitively. Objects are compared by instance
143 * identity. Arrays are compared using strict equality, so the same key/value pairs
144 * in a different order are treated as different values. Case-insensitive
145 * comparison applies only to direct string values, not to strings nested
146 * inside arrays.
147 *
148 * @param iterable<mixed, mixed> $traversable
149 * @param bool $caseSensitive
150 *
151 * @return Generator
152 */
153 public static function unique(iterable $traversable, bool $caseSensitive = true): Generator
154 {
155 $seenObjects = new SplObjectStorage();
156 $seenValues = [];
157
158 foreach ($traversable as $key => $value) {
159 if (is_object($value)) {
160 if ($seenObjects->offsetExists($value)) {
161 continue;
162 }
163
164 $seenObjects->offsetSet($value);
165 yield $key => $value;
166 continue;
167 }
168
169 $seenValue = ! $caseSensitive && is_string($value) ? strtolower($value) : $value;
170 if (in_array($seenValue, $seenValues, true)) {
171 continue;
172 }
173
174 $seenValues[] = $seenValue;
175 yield $key => $value;
176 }
177 }
178 }