ArrayLookup

Introduction

ArrayLookup is a fast lookup library that helps you verify and search array and Traversable data.

Features

Verify at least times: once(), twice(), times()
Verify at most times: once(), twice(), times()
Verify exact times: once(), twice(), times()
Verify in interval range: isInclusiveOf(), isExclusiveOf()
Verify all or none match: match(), none()
Search data: first(), last(), nth(), rows(), partition()
Collect data with filter and transform

Installation

Require this library uses composer.

composer require samsonasik/array-lookup

Usage

A. AtLeast

1. `AtLeast::once()`

It verify that data has filtered found item at least once.

useArrayLookup\AtLeast;
$data = [1, 2, 3];
$filter = staticfn($datum): bool => $datum === 1;
var_dump(AtLeast::once($data, $filter)) // true$data = [1, 2, 3];
$filter = staticfn($datum): bool => $datum === 4;
var_dump(AtLeast::once($data, $filter)) // false// WITH key array included, pass $key variable as 2nd arg on filter to be used in filter$data = [1, 2, 3];
$filter = staticfn($datum, $key): bool => $datum === 1 && $key >= 0;
var_dump(AtLeast::once($data, $filter)) // true$data = [1, 2, 3];
$filter = staticfn($datum, $key): bool => $datum === 4 && $key >= 0;
var_dump(AtLeast::once($data, $filter)) // false

2. `AtLeast::twice()`

It verify that data has filtered found items at least twice.

useArrayLookup\AtLeast;
$data = [1, "1", 3];
$filter = staticfn($datum): bool => $datum == 1;
var_dump(AtLeast::twice($data, $filter)) // true$data = [1, "1", 3];
$filter = staticfn($datum): bool => $datum === 1;
var_dump(AtLeast::twice($data, $filter)) // false// WITH key array included, pass $key variable as 2nd arg on filter to be used in filter$data = [1, "1", 3];
$filter = staticfn($datum, $key): bool => $datum == 1 && $key >= 0;
var_dump(AtLeast::twice($data, $filter)) // true$data = [1, "1", 3];
$filter = staticfn($datum, $key): bool => $datum === 1 && $key >= 0;
var_dump(AtLeast::twice($data, $filter)) // false

3. `AtLeast::times()`

It verify that data has filtered found items at least times passed in 3rd arg.

useArrayLookup\AtLeast;
$data = [false, null, 0];
$filter = staticfn($datum): bool => ! $datum;
$times = 3;
var_dump(AtLeast::times($data, $filter, $times)) // true$data = [1, null, 0];
$filter = staticfn($datum): bool => ! $datum;
$times = 3;
var_dump(AtLeast::times($data, $filter, $times)) // false// WITH key array included, pass $key variable as 2nd arg on filter to be used in filter$data = [false, null, 0];
$filter = staticfn($datum, $key): bool => ! $datum && $key >= 0;
$times = 3;
var_dump(AtLeast::times($data, $filter, $times)) // true$data = [1, null, 0];
$filter = staticfn($datum, $key): bool => ! $datum && $key >= 0;
$times = 3;
var_dump(AtLeast::times($data, $filter, $times)) // false

B. AtMost

1. `AtMost::once()`

It verify that data has filtered found item at most once.

useArrayLookup\AtMost;
$data = [1, 2, 3];
$filter = staticfn($datum): bool => $datum === 1;
var_dump(AtMost::once($data, $filter)) // true$data = [1, "1", 3];
$filter = staticfn($datum): bool => $datum == 1;
var_dump(AtMost::once($data, $filter)) // false// WITH key array included, pass $key variable as 2nd arg on filter to be used in filter$data = ['abc', 'def', 'some test'];
$filter = staticfn(string$datum, int$key): bool => $datum === 'def' && $key === 1;
var_dump(AtMost::once($data, $filter)) // true$data = ['abc', 'def', 'some test'];
$filter = staticfn(string$datum, int$key): bool => $key > 0;
var_dump(AtMost::once($data, $filter)) // false

2. `AtMost::twice()`

It verify that data has filtered found items at most twice.

useArrayLookup\AtMost;
$data = [1, "1", 2];
$filter = staticfn($datum): bool => $datum == 1;
var_dump(AtMost::twice($data, $filter)) // true$data = [1, "1", 2, 1];
$filter = staticfn($datum): bool => $datum == 1;
var_dump(AtMost::twice($data, $filter)) // false

3. `AtMost::times()`

It verify that data has filtered found items at most times passed in 3rd arg.

useArrayLookup\AtMost;
$data = [false, null, 0];
$filter = staticfn($datum): bool => ! $datum;
$times = 3;
var_dump(AtMost::times($data, $filter, $times)) // true$data = [false, null, 0, 0];
$filter = staticfn($datum): bool => ! $datum;
$times = 3;
var_dump(AtMost::times($data, $filter, $times)) // false

C. Only

1. `Only::once()`

It verify that data has filtered found item exactly found only once.

useArrayLookup\Only;
$data = [1, 2, 3];
$filter = staticfn($datum): bool => $datum === 1;
var_dump(Only::once($data, $filter)) // true$data = [1, "1", 3]
$filter = staticfn($datum): bool => $datum == 1;
var_dump(Only::once($data, $filter)) // false// WITH key array included, pass $key variable as 2nd arg on filter to be used in filter$data = [1, 2, 3];
$filter = staticfn($datum, $key): bool => $datum === 1 && $key >= 0;
var_dump(Only::once($data, $filter)) // true$data = [1, "1", 3]
$filter = staticfn($datum, $key): bool => $datum == 1 && $key >= 0;
var_dump(Only::once($data, $filter)) // false

2. `Only::twice()`

It verify that data has filtered found items exactly found only twice.

useArrayLookup\Only;
$data = [1, "1", 3];
$filter = staticfn($datum): bool => $datum == 1;
var_dump(Only::twice($data, $filter)) // true$data = [true, 1, newstdClass()];
$filter = staticfn($datum): bool => (bool) $datum;
var_dump(Only::twice($data, $filter)) // false// WITH key array included, pass $key variable as 2nd arg on filter to be used in filter$data = [1, "1", 3];
$filter = staticfn($datum, $key): bool => $datum == 1 && $key >= 0;
var_dump(Only::twice($data, $filter)) // true$data = [true, 1, newstdClass()];
$filter = staticfn($datum, $key): bool => (bool) $datum && $key >= 0;
var_dump(Only::twice($data, $filter)) // false

3. `Only::times()`

It verify that data has filtered found items exactly found only same with times passed in 3rd arg.

useArrayLookup\Only;
$data = [false, null, 1];
$filter = staticfn($datum): bool => ! $datum;
$times = 2;
var_dump(Only::times($data, $filter, $times)) // true$data = [false, null, 0];
$filter = staticfn($datum): bool => ! $datum;
$times = 2;
var_dump(Only::times($data, $filter, $times)) // false// WITH key array included, pass $key variable as 2nd arg on filter to be used in filter$data = [false, null, 1];
$filter = staticfn($datum, $key): bool => ! $datum && $key >= 0;
$times = 2;
var_dump(Only::times($data, $filter, $times)) // true$data = [false, null, 0];
$filter = staticfn($datum, $key): bool => ! $datum && $key >= 0;
$times = 2;
var_dump(Only::times($data, $filter, $times)) // false

D. Interval

1. `Interval::isInclusiveOf()`

It verify that data has filtered found items within min and max (inclusive).

useArrayLookup\Interval;
$orders = [
['status' => 'paid'],
['status' => 'paid'],
['status' => 'pending'],
['status' => 'paid'],
];
$filter = staticfn(array$order): bool => $order['status'] === 'paid';
// inclusive means min and max boundaries are allowedvar_dump(Interval::isInclusiveOf($orders, $filter, 3, 5)) // truevar_dump(Interval::isInclusiveOf($orders, $filter, 2, 5)) // true

2. `Interval::isExclusiveOf()`

It verify that data has filtered found items between min and max (exclusive).

useArrayLookup\Interval;
$orders = [
['status' => 'paid'],
['status' => 'paid'],
['status' => 'pending'],
['status' => 'paid'],
];
$filter = staticfn(array$order): bool => $order['status'] === 'paid';
// exclusive means strictly between min and maxvar_dump(Interval::isExclusiveOf($orders, $filter, 3, 5)) // falsevar_dump(Interval::isExclusiveOf($orders, $filter, 2, 5)) // true

E. All

1. `All::match()`

It verify that all items match the filter and data is non-empty.

useArrayLookup\All;
$data = [1, 2, 3];
$filter = staticfn($datum): bool => $datum > 0;
var_dump(All::match($data, $filter)) // true$data = [1, 0, 3];
$filter = staticfn($datum): bool => $datum > 0;
var_dump(All::match($data, $filter)) // false$data = [];
$filter = staticfn($datum): bool => $datum !== null;
var_dump(All::match($data, $filter)) // false// WITH key array included, pass $key variable as 2nd arg on filter to be used in filter$data = ['abc', 'def'];
$filter = staticfn($datum, $key): bool => $datum !== '' && $key >= 0;
var_dump(All::match($data, $filter)) // true

2. `All::none()`

It verify that no items match the filter (empty data returns true).

useArrayLookup\All;
$data = [1, 2, 3];
$filter = staticfn($datum): bool => $datum === 4;
var_dump(All::none($data, $filter)) // true$data = [1, 2, 3];
$filter = staticfn($datum): bool => $datum === 2;
var_dump(All::none($data, $filter)) // false$data = [];
$filter = staticfn($datum): bool => $datum !== null;
var_dump(All::none($data, $filter)) // true// WITH key array included, pass $key variable as 2nd arg on filter to be used in filter$data = ['abc', 'def'];
$filter = staticfn($datum, $key): bool => $key === 0 && $datum === 'abc';
var_dump(All::none($data, $filter)) // false

F. Finder

1. `Finder::first()`

It search first data filtered found.

useArrayLookup\Finder;
$data = [1, 2, 3];
$filter = staticfn($datum): bool => $datum === 1;
var_dump(Finder::first($data, $filter)) // 1$filter = staticfn($datum): bool => $datum == 1000;
var_dump(Finder::first($data, $filter)) // null// RETURN the Array key, pass true to 3rd arg$filter = staticfn($datum): bool => $datum === 1;
var_dump(Finder::first($data, $filter, true)) // 0$filter = staticfn($datum): bool => $datum == 1000;
var_dump(Finder::first($data, $filter, true)) // null// WITH key array included, pass $key variable as 2nd arg on filter to be used in filter$filter = staticfn($datum, $key): bool => $datum === 1 && $key >= 0;
var_dump(Finder::first($data, $filter)) // 1$filter = staticfn($datum, $key): bool => $datum == 1000 && $key >= 0;
var_dump(Finder::first($data, $filter)) // null

2. `Finder::last()`

It search last data filtered found.

useArrayLookup\Finder;
$data = [6, 7, 8, 9];
var_dump(Finder::last(
$data,
staticfn ($datum): bool => $datum > 5
)); // 9var_dump(Finder::last(
$data,
staticfn ($datum): bool => $datum < 5
)); // null// RETURN the Array key, pass true to 3rd arg// ... with PRESERVE original keyvar_dump(Finder::last(
$data,
staticfn ($datum): bool => $datum > 5,
true
)); // 3// ... with RESORT key, first key is last recordvar_dump(Finder::last(
$data,
staticfn ($datum): bool => $datum > 5,
true,
false
)); // 0var_dump(Finder::last(
$data,
staticfn ($datum): bool => $datum < 5,
true
)); // null// WITH key array included, pass $key variable as 2nd arg on filter to be used in filtervar_dump(Finder::last(
$data,
staticfn ($datum, $key): bool => $datum > 5 && $key >= 0
)); // 9var_dump(Finder::last(
$data,
staticfn ($datum, $key): bool => $datum < 5 && $key >= 0
)); // null

3. `Finder::nth()`

It returns the 1st, 2nd, 3rd, and so on matching item, or multiple matching items at specific positions. The position is 1-based among matched results, not the original array index. Pass a single position to get one matching item, or an array of positions to get multiple matching items. If no match is found, it returns null for a single position or an empty array for multiple positions. Pass true to the 4th argument to return the key(s) instead of the value(s).

useArrayLookup\Finder;
$data = [10, 20, 30, 40, 50];
$filter = staticfn($datum): bool => $datum > 15;
// Get the 2nd matching valuevar_dump(Finder::nth($data, $filter, 2)); // 30// Get the 2nd matching keyvar_dump(Finder::nth($data, $filter, 2, true)); // 2// Get the 1st and 3rd matching valuesvar_dump(Finder::nth($data, $filter, [1, 3])); // [20, 40]// Get the 1st and 3rd matching keysvar_dump(Finder::nth($data, $filter, [1, 3], true)); // [1, 3]// No match (single)var_dump(Finder::nth($data, $filter, 5)); // null// No match (multiple)var_dump(Finder::nth($data, $filter, [5, 6])); // []

4. `Finder::rows()`

It get rows data filtered found.

useArrayLookup\Finder;
$data = [6, 7, 8, 9];
var_dump(Finder::rows(
$data,
staticfn($datum): bool => $datum > 6
)); // [7, 8, 9]var_dump(Finder::rows(
$data,
staticfn ($datum): bool => $datum < 5
)); // []// ... with PRESERVE original keyvar_dump(Finder::rows(
$data,
staticfn ($datum): bool => $datum > 6,
true
)); // [1 => 7, 2 => 8, 3 => 9]var_dump(Finder::rows(
$data,
staticfn ($datum): bool => $datum < 5,
true
)); // []// WITH key array included, pass $key variable as 2nd arg on filter to be used in filtervar_dump(Finder::rows(
$data,
staticfn($datum, $key): bool => $datum > 6 && $key > 1
)); // [8, 9]// WITH gather only limited found data$data = [1, 2];
$filter = staticfn($datum): bool => $datum >= 0;
$limit = 1;
var_dump(
Finder::rows($data, $filter, limit: $limit)
); // [1]

5. `Finder::partition()`

It splits data into two arrays: matching and non-matching items based on a filter.

useArrayLookup\Finder;
// Basic partition - split numbers into greater than 5 and not$data = [1, 6, 3, 8, 4, 9];
$filter = staticfn($datum): bool => $datum > 5;
[$matching, $notMatching] = Finder::partition($data, $filter);
var_dump($matching); // [6, 8, 9]var_dump($notMatching); // [1, 3, 4]// Partition with preserved keys
[$matching, $notMatching] = Finder::partition($data, $filter, preserveKey: true);
var_dump($matching); // [1 => 6, 3 => 8, 5 => 9]var_dump($notMatching); // [0 => 1, 2 => 3, 4 => 4]// Using the array key inside the filter$data = [10, 20, 30, 40];
$keyFilter = staticfn($datum, $key): bool => $key % 2 === 0;
[$even, $odd] = Finder::partition($data, $keyFilter, preserveKey: true);
var_dump($even); // [0 => 10, 2 => 30]var_dump($odd); // [1 => 20, 3 => 40]

G. Collector

It collect filtered data, with new transformed each data found:

Before

$newArray = [];
foreach ($dataas$datum) {
if (is_string($datum)) {
$newArray[] = trim($datum);
}
}

After

useArrayLookup\Collector;
$when = fn ($datum): bool => is_string($datum);
$limit = 2;
$transform = fn ($datum): string => trim($datum);
$newArray = Collector::setUp($data)
->when($when) // optional, can just transform without filtering
->withLimit(2) // optional to only collect some data provided by limit config
->withTransform($transform)
->getResults();

Name		Name	Last commit message	Last commit date
.github		.github
src		src
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json
phpcs.xml		phpcs.xml
phpstan.neon		phpstan.neon
phpunit.xml		phpunit.xml
rector.php		rector.php
structarmed.php		structarmed.php

Navigation Menu

Uh oh!

Repository files navigation

ArrayLookup

Introduction

Features

Installation

Usage

A. AtLeast

1. `AtLeast::once()`

2. `AtLeast::twice()`

3. `AtLeast::times()`

B. AtMost

1. `AtMost::once()`

2. `AtMost::twice()`

3. `AtMost::times()`

C. Only

1. `Only::once()`

2. `Only::twice()`

3. `Only::times()`

D. Interval

1. `Interval::isInclusiveOf()`

2. `Interval::isExclusiveOf()`

E. All

1. `All::match()`

2. `All::none()`

F. Finder

1. `Finder::first()`

2. `Finder::last()`

3. `Finder::nth()`

4. `Finder::rows()`

5. `Finder::partition()`

G. Collector

About

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

ArrayLookup

Introduction

Features

Installation

Usage

A. AtLeast

1. AtLeast::once()

2. AtLeast::twice()

3. AtLeast::times()

B. AtMost

1. AtMost::once()

2. AtMost::twice()

3. AtMost::times()

C. Only

1. Only::once()

2. Only::twice()

3. Only::times()

D. Interval

1. Interval::isInclusiveOf()

2. Interval::isExclusiveOf()

E. All

1. All::match()

2. All::none()

F. Finder

1. Finder::first()

2. Finder::last()

3. Finder::nth()

4. Finder::rows()

5. Finder::partition()

G. Collector

About

Topics

Resources

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

1. `AtLeast::once()`

2. `AtLeast::twice()`

3. `AtLeast::times()`

1. `AtMost::once()`

2. `AtMost::twice()`

3. `AtMost::times()`

1. `Only::once()`

2. `Only::twice()`

3. `Only::times()`

1. `Interval::isInclusiveOf()`

2. `Interval::isExclusiveOf()`

1. `All::match()`

2. `All::none()`

1. `Finder::first()`

2. `Finder::last()`

3. `Finder::nth()`

4. `Finder::rows()`

5. `Finder::partition()`