Skip to main content

Collections

The Immutable collections described in this section are pertinent in the Functional Programming discourse because of their inherent persistence. Persistence implies creating (sometimes almost churning out) new copies of an immutable state - this is especially important for graceful mutation.

The ad-hoc polymorphism of the Collection class is an enabler of controlled state transition - the ethos of functional programming. The internal structure of the Collections class is such that an SPL fixed array is used to store list items. Below is a detailed enumeration of the class' methods.

I wrote an article about the Data Structure documented in this section. Please refer to it for additional information.

Note: Immutable lists are not available in bingo-functional-js. Consider downloading immutable.js if you want to infuse your JavaScript code with the potency of immutable collections.

from#

Collection::from(items)

Creates a Collection object from an arbitrary array.

Since: v1.10.0

Argument(s)

  • items (array) - The items to store
use Chemem\Bingo\Functional\Immutable\Collection;
// for arrays with numeric indices$fst = Collection::from(range(1, 10000));
// for arrays with string keys$snd = Collection::from([  [    'package' => 'bingo-functional',    'creator' => '@ace411',  ]]);

map#

Collection::map(function)

Applies a function to each item in a list in a single iteration.

Since: v1.10.0

Argument(s)

  • function - The function to apply to each list item
use Chemem\Bingo\Functional\Immutable\Collection;use function Chemem\Bingo\Functional\concat;
$camelCase  = fn (string $str): string => concat('', 'str', '_', $str);$list       = Collection::from(['foo', 'bar', 'baz'])->map($camelCase);

flatMap#

Collection::flatMap(function)

The flatMap method, like the map method, iteratively applies a function to items in a list but evaluates to an array and not a Collection object.

Since: v1.10.0

Argument(s)

  • function - The function to apply to each list item
use Chemem\Bingo\Functional\Immutable\Collection;
$list = Collection::from(range(1, 4))  ->flatMap(fn (int $x): int => $x ** 3);

filter#

Collection::filter(function)

The filter function evaluates to an immutable list whose values conform to a boolean predicate present in the function signature of a supplied function.

Since: v1.10.0

Argument(s)

  • function - The filter function
use Chemem\Bingo\Functional\Immutable\Collection;
$list = Collection::from(range(1, 10))  ->filter(fn (int $x): bool => $x % 2 === 0);

fold#

Collection::fold(function, accumulator)

The fold function transforms a list into a single value.

Since: v1.10.0

Argument(s)

  • function - The fold function
  • accumulator - The accumulator value
use Chemem\Bingo\Functional\Immutable\Collection;
$max = Collection::from([2, 4, 33, ...range(1, 7)])  ->fold(fn (int $acc, int $val) => ($val > $acc ? $val : $acc), 0);

any#

Collection::any(function)

Checks if one or more list elements conform to a boolean predicate.

Since: v1.13.0

Argument(s)

  • function - The function whose return value bears the examinable boolean predicate
use Chemem\Bingo\Functional\Immutable\Collection;
$list = Collection::from(['foo', ...range(5, 43)])  ->any('is_string');

every#

Collection::every(function)

Checks if every list element conforms to a boolean predicate.

Since: v1.13.0

Argument(s)

  • function - The function whose return value bears the examinable boolean predicate
use Chemem\Bingo\Functional\Immutable\Collection;
$list = Collection::from(['foo', 'bar', ...range(4, 21)])  ->every('is_string');

reject#

Collection::reject(function)

Returns a list containing values whose items do not conform to a boolean predicate - the opposite of the filter function.

Since: v1.13.0

Argument(s)

  • function - The filter function
use Chemem\Bingo\Functional\Immutable\Collection;
$list = Collection::from(range(1, 10))  ->reject(fn (int $x): bool => $x % 2 === 0);

merge#

Collection::merge(list)

Combines two immutable list objects.

Since: v1.10.0

Argument(s)

  • list - The list object to merge with
use Chemem\Bingo\Functional\Immutable\Collection;
$fst = Collection::from(range(1, 3));
$snd = $fst->merge(Collection::from(range(4, 6)));

mergeN#

Collection::mergeN(...lists)

Combines multiple list objects into a single list.

Since: v1.13.0

Argument(s)

  • lists - The list objects to merge with
use Chemem\Bingo\Functional\Immutable\Collection;
$fst    = Collection::from(range(1, 2));
$final  = $fst->mergeN(  Collection::from(['foo', 'bar']),  Collection::from([    ['jersey' => 24, 'name' => 'Kobe'],  ]));

reverse#

Collection::reverse()

Reverses the order of a list object.

Since: v1.10.0

Argument(s)

None

use Chemem\Bingo\Functional\Immutable\Collection;
$list = Collection::from(range(1, 4))->reverse();

slice#

Collection::slice(count)

Removes a specified number of items from a list.

Since: v1.13.0

Argument(s)

  • count - The number of items to remove from the list
use Chemem\Bingo\Functional\Immutable\Collection;
$list = Collection::from(range(40, 50))->slice(5);

fill#

Collection::fill(value, start, end)

The fill function replaces, with an arbitrary value, the items in a specified index range.

Since: v1.13.0

Argument(s)

  • value (mixed) - The value to insert in list
  • start (int) - The first index whose corresponding value is to be replaced with fill value
  • end (int) - The last index whose corresponding value is to be replaced with fill value
use Chemem\Bingo\Functional\Immutable\Collection;
$list = Collection::from(range(1, 5))  ->fill('foo', 1, 3);

fetch#

Collection::fetch(key)

Returns a list object containing values that match a specified key.

Since: v1.10.0

Argument(s)

  • key (mixed) - The key whose associate value(s) are desired
$collection = Collection::from([    ['id' => 35, 'name' => 'Durant'],    ['id' => 24, 'name' => 'Bryant']]);
$collection->fetch('name');

contains#

Collection::contains(key)

Checks if a key exists in a collection. Akin to the key_exists function.

Since: v1.10.0

Argument(s)

  • key (mixed) - The key whose presence is to be ascertained
$collection = Collection::from([  ['id' => 3, 'name' => 'Wade'],  ['id' => 23, 'name' => 'Mike']]);
$collection->exists('name');

offsetGet#

Collection::offsetGet(offset)

Returns a value which corresponds to a specified numerical key.

Since: v1.10.0

Argument(s)

  • offset (int) - The numerical key with a unique data value binding
$collection = Collection::from(range(1, 5));
$collection->offsetGet(2);

head#

Collection::head()

Returns the first element in the list.

Since: v1.10.0

Argument(s)

None

use Chemem\Bingo\Functional\Immutable\Collection;
$list = Collection::from(['foo', 'bar'])->head();

tail#

Collection::tail()

Returns a list containing all initial list values but the first.

Since: v1.10.0

Argument(s)

None

use Chemem\Bingo\Functional\Immutable\Collection;
$list = Collection::from(['foo', 'bar', 'baz'])->tail();

last#

Collection::last()

Returns the last element in a list.

Since: v1.10.0

Argument(s)

None

use Chemem\Bingo\Functional\Immutable\Collection;
$list = Collection::from(['foo', 'bar'])->last();

intersects#

Collection::intersects(list)

Determines if two lists intersect and thus, have a commonality.

Since: v1.10.0

Argument(s)

  • list (Collection) - The list to compare values with
$list = Collection::from(range(1, 5));
$list->intersects(Collection::from(range(4, 12)));

implode#

Collection::implode(delimeter)

Combines list elements into a string and inserts, between elements, a special string (delimeter). Analogous to the implode function.

Since: v1.10.0

Argument(s)

  • delimeter (string) - The string to insert between elements
$list = Collection::from(['foo', 'bar', 'baz'])  ->implode(', ');

toArray#

Collection::toArray()

Converts a list object to a traditional PHP array.

Since: v1.10.0

Argument(s)

None

use Chemem\Bingo\Functional\Immutable\Collection;
$list = Collection::from(['foo', 'bar'])->toArray();

Additional Properties#

The collection class implements the Countable, JsonSerializable, and IteratorAggregate interfaces. The implication is that bingo-functional's immutable collections are compatible with count(), json_encode(), and idiomatic PHP recursion constructs such as for and foreach.

use Chemem\Bingo\Functional\Immutable\Collection;
$list = Collection::from(['foo', 'bar', 'baz']);
echo count($list);
echo json_encode($list);
foreach ($list as $val) {  echo $val . PHP_EOL;}