Skip to content

Add key typehints to iterable functions #102

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
annadamm-check24 wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Add key typehints to iterable functions #102

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3e19d45
add iterable key to type hints
annadamm-check24 May 11, 2026
620879a
fix phpstan not recognizing template parameter types
annadamm-check24 May 11, 2026
e595bcd
add new versions of psalm and phpstan to dev requirements
annadamm-check24 May 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions composer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@
},
"require-dev": {
"phpunit/phpunit": "^7.0 || ^8.0 || ^9.0",
"vimeo/psalm": "^4.18 || ^5.13",
"phpstan/phpstan": "^1.4"
"vimeo/psalm": "^4.18 || ^5.13 || ^6.16",
"phpstan/phpstan": "^1.4 || ^2.1"
},
"autoload": {
"files": [
Expand Down
68 changes: 38 additions & 30 deletions src/iter.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,13 +71,14 @@ function range($start, $end, $step = null): \Iterator {
*
* $column = map(iter\func\index('name'), $iter);
*
* @template T
* @template U
* @template IterableValue
Copy link
Copy Markdown
Owner

@nikic nikic May 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All the other ones use TKey/TValue, why the difference here?

Copy link
Copy Markdown
Author

@annadamm-check24 annadamm-check24 May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because we have 3 variables and it was difficult to understand the key/value of which it should be.
Do you have other suggestions? I have seen UKey, TValue, etc., but I personally find that hard to understand.

Copy link
Copy Markdown
Author

@annadamm-check24 annadamm-check24 May 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nikic should I change it, or do you think this is still okay?

* @template FunctionReturn
* @template IterableKey
*
* @param callable(T):U $function Mapping function
* @param iterable<T> $iterable Iterable to be mapped over
* @param callable(IterableValue):FunctionReturn $function Mapping function
* @param iterable<IterableKey, IterableValue> $iterable Iterable to be mapped over
*
* @return \Iterator<U>
* @return \Iterator<IterableKey, FunctionReturn>
*/
function map(callable $function, iterable $iterable): \Iterator {
foreach ($iterable as $key => $value) {
Expand Down Expand Up @@ -243,12 +244,13 @@ function apply(callable $function, iterable $iterable): void {
*
* iter\filter(iter\func\operator('instanceof', 'SomeClass'), $objects);
*
* @template T
* @template TKey
* @template TValue
*
* @param callable(T):bool $predicate Predicate function
* @param iterable<T> $iterable Iterable to filter
* @param callable(TValue):bool $predicate Predicate function
* @param iterable<TKey, TValue> $iterable Iterable to filter
*
* @return \Iterator<T>
* @return \Iterator<TKey, TValue>
*/
function filter(callable $predicate, iterable $iterable): \Iterator {
foreach ($iterable as $key => $value) {
Expand Down Expand Up @@ -465,11 +467,12 @@ function zipKeyValue(iterable $keys, iterable $values): \Iterator {
* iter\chain(iter\range(0, 5), iter\range(6, 10), iter\range(11, 15))
* => iter(0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15)
*
* @template T
* @template TKey
* @template TValue
*
* @param iterable<T> ...$iterables Iterables to chain
* @param iterable<TKey, TValue> ...$iterables Iterables to chain
*
* @return \Iterator<T>
* @return \Iterator<TKey, TValue>
*/
function chain(iterable ...$iterables): \Iterator {
foreach ($iterables as $iterable) {
Expand All @@ -492,7 +495,7 @@ function chain(iterable ...$iterables): \Iterator {
*
* @param iterable ...$iterables Iterables to combine
*
* @return \Iterator<array>
* @return \Iterator<array, array>
*/
function product(iterable ...$iterables): \Iterator {
$iterators = array_map('iter\\toIter', $iterables);
Expand Down Expand Up @@ -539,14 +542,15 @@ function product(iterable ...$iterables): \Iterator {
* iter\slice([-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5], 5, 3)
* => iter(0, 1, 2, 3)
*
* @template T
* @template TKey
* @template TValue
*
* @param iterable<T> $iterable Iterable to take the slice from
* @param iterable<TKey, TValue> $iterable Iterable to take the slice from
* @param int $start Start offset
* @param int $length Length (if not specified all remaining values from the
* iterable are used)
*
* @return \Iterator<T>
* @return \Iterator<TKey, TValue>
*/
function slice(iterable $iterable, int $start, $length = PHP_INT_MAX): \Iterator {
if ($start < 0) {
Expand Down Expand Up @@ -579,12 +583,13 @@ function slice(iterable $iterable, int $start, $length = PHP_INT_MAX): \Iterator
* iter\take(3, [1, 2, 3, 4, 5])
* => iter(1, 2, 3)
*
* @template T
* @template TKey
* @template TValue
*
* @param int $num Number of elements to take from the start
* @param iterable<T> $iterable Iterable to take the elements from
* @param iterable<TKey, TValue> $iterable Iterable to take the elements from
*
* @return \Iterator<T>
* @return \Iterator<TKey, TValue>
*/
function take(int $num, iterable $iterable): \Iterator {
return slice($iterable, 0, $num);
Expand All @@ -598,12 +603,13 @@ function take(int $num, iterable $iterable): \Iterator {
* iter\drop(3, [1, 2, 3, 4, 5])
* => iter(4, 5)
*
* @template T
* @template TKey
* @template TValue
*
* @param int $num Number of elements to drop from the start
* @param iterable<T> $iterable Iterable to drop the elements from
* @param iterable<TKey, TValue> $iterable Iterable to drop the elements from
*
* @return \Iterator<T>
* @return \Iterator<TKey,TValue>
*/
function drop(int $num, iterable $iterable): \Iterator {
return slice($iterable, $num);
Expand Down Expand Up @@ -782,12 +788,13 @@ function search(callable $predicate, iterable $iterable) {
* iter\takeWhile(iter\func\operator('>', 0), [3, 1, 4, -1, 5])
* => iter(3, 1, 4)
*
* @template T
* @template TKey
* @template TValue
*
* @param callable(T):bool $predicate Predicate function
* @param iterable<T> $iterable Iterable to take values from
* @param callable(TValue):bool $predicate Predicate function
* @param iterable<TKey, TValue> $iterable Iterable to take values from
*
* @return \Iterator<T>
* @return \Iterator<TKey, TValue>
*/
function takeWhile(callable $predicate, iterable $iterable): \Iterator {
foreach ($iterable as $key => $value) {
Expand All @@ -810,12 +817,13 @@ function takeWhile(callable $predicate, iterable $iterable): \Iterator {
* iter\dropWhile(iter\func\operator('>', 0), [3, 1, 4, -1, 5])
* => iter(-1, 5)
*
* @template T
* @template TKey
* @template TValue
*
* @param callable(T):bool $predicate Predicate function
* @param iterable<T> $iterable Iterable to drop values from
* @param callable(TValue):bool $predicate Predicate function
* @param iterable<TKey, TValue> $iterable Iterable to drop values from
*
* @return \Iterator<T>
* @return \Iterator<TKey, TValue>
*/
function dropWhile(callable $predicate, iterable $iterable): \Iterator {
$failed = false;
Expand Down
6 changes: 3 additions & 3 deletions src/iter.rewindable.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,9 @@
* @template TKey
* @template TValue
*
* @param callable(...mixed):\Iterator<TKey,TValue> $function Iterator factory function
* @param callable():\Iterator<TKey,TValue> $function Iterator factory function
*
* @return callable(...mixed):\Iterator<TKey,TValue> Rewindable iterator factory function
* @return callable():\Iterator<TKey,TValue> Rewindable iterator factory function
*/
function makeRewindable(callable $function) {
return function(...$args) use ($function) {
Expand All @@ -43,7 +43,7 @@ function makeRewindable(callable $function) {
* @template TKey
* @template TValue
*
* @param callable(...mixed):\Iterator<TKey,TValue> $function Iterator factory function
* @param callable():\Iterator<TKey,TValue> $function Iterator factory function
* @param mixed ...$args Function arguments
*
* @return \Iterator<TKey,TValue> Rewindable generator result
Expand Down
Loading