Implements a map that may only contain objects only.

Methods accepting a $collection may receive any of these types:

  • array
  • object
  • \Traversable
  • \Haldayne\Boost\Map
  • \Haldayne\Boost\Contract\Arrayable
  • \Haldayne\Boost\Contract\Jsonable

Methods accept a $key may be of any type: boolean, integer, float, string, array, object, closure, or resource.

Methods accepting an $expression may receive a [PHP callable][1] or a string. When given a string, the library wraps an anonymous function around the string code body and returns the result. By way of example, these are equivalent and both acceptable as an $expression:

  • $_0 < $_1
  • `function ($_0, $_1) { return $_0 < $_1; }

Expressions lets you write extremely compact code for filtering, at the one-time run-time cost of converting the string to the body of an anonymous function.

Expressions, whether given as a callable or a string, receive two formal arguments: the current value and the current key. Note that, inside string expressions, these are represented by $_0 and $_1 respectively.

package Haldayne
inherited_from \Haldayne\Boost\GuardedMapAbstract

 Methods

Create a new map.

__construct(\Haldayne\Boost\Map|\Haldayne\Boost\Contract\Arrayable|\Haldayne\Boost\Contract\Jsonable|\Haldayne\Boost\Traversable|object|array $collection = null
APIInherited

Initialize the map with the given collection, which can be any type that is "collection-like": array, object, Traversable, another Map, etc.

api

Parameters

$collection

\Haldayne\Boost\Map\Haldayne\Boost\Contract\Arrayable\Haldayne\Boost\Contract\Jsonable\Haldayne\Boost\Traversableobjectarray

Exceptions

\InvalidArgumentException

Create a new map containing all members from this map whose elements satisfy the expression.

all(callable|string $expression) : \Haldayne\Boost\new
APIInherited

The expression decides whether an element is in or out. If the expression returns boolean false, the element is out. Otherwise, it's in.

$nums = new Map(range(0, 9));
$even = $nums->all(function ($val, $key) { return 0 == $val % 2; });
$odds = $nums->all('$_0 & 1');
api

Parameters

$expression

callablestring

Returns

\Haldayne\Boost\newstatic

Call the given method on every object in the map, and return the results as a new map.

apply(string $method, array|null $args = array()) : \Haldayne\Boost\Map
API
api

Parameters

$method

string

The method on each contained object to call.

$args

arraynull

The arguments to pass to the method.

Returns

\Haldayne\Boost\Map

Count the number of items in the map.

count() : integer
APIInherited
api

Returns

integer

Return a new map containing those keys and values that are not present in the given collection.

diff(\Haldayne\Boost\Map|\Haldayne\Boost\Contract\Arrayable|\Haldayne\Boost\Contract\Jsonable|\Haldayne\Boost\Traversable|object|array $collection, \Haldayne\Boost\enum $comparison = \Haldayne\Boost\Map::LOOSE) : \Haldayne\Boost\new
APIInherited

If comparison is loose, then only those elements whose values match will be removed. Otherwise, comparison is strict, and elements whose keys and values match will be removed.

api

Parameters

$collection

\Haldayne\Boost\Map\Haldayne\Boost\Contract\Arrayable\Haldayne\Boost\Contract\Jsonable\Haldayne\Boost\Traversableobjectarray

$comparison

\Haldayne\Boost\enum

Returns

\Haldayne\Boost\newstatic

Test if every element passes the expression.

every(callable|string $expression) : boolean
APIInherited
api

Parameters

$expression

callablestring

Returns

boolean

Apply the filter to every element, creating a new map with only those elements from the original map that do not fail this filter.

filter(callable|string $expression) : \Haldayne\Boost\new
APIInherited

The filter expressions receives two arguments:

  • The current value
  • The current key

If the filter returns exactly boolean false, the element is not copied into the new map. Otherwise, it is. Keys from the original map carry into the new map.

api

Parameters

$expression

callablestring

Returns

\Haldayne\Boost\newstatic

Return a new map containing the first N elements passing the expression.

first(callable|string $expression, integer $n = 1) : \Haldayne\Boost\new
APIInherited

Like find, but stop after finding N elements from the front. Defaults to N = 1.

$nums = new Map(range(0, 9));
$odd3 = $nums->first('1 == ($_0 % 2)', 3); // first three odds
api

Parameters

$expression

callablestring

$n

integer

Returns

\Haldayne\Boost\newstatic

Remove a key and its corresponding value from the map.

forget(mixed $key) : \Haldayne\Boost\MapOfObjects
APIInherited

This is the object method equivalent of the magic unset($map[$key]);

api
fluent This method is part of a fluent interface and will return the same instance

Parameters

$key

mixed

Returns

\Haldayne\Boost\MapOfObjects

Get the value corresponding to the given key.

get(mixed $key, mixed $default = null) : mixed
APIInherited

If the key does not exist in the map, return the default.

This is the object method equivalent of the magic $map[$key].

api

Parameters

$key

mixed

$default

mixed

Returns

mixed

Get an iterator for a copy of the map.

getIterator() : \ArrayIterator
APIInherited
api

Returns

\ArrayIterator

Determine if a key exists the map.

has(mixed $key) : boolean
APIInherited

This is the object method equivalent of the magic isset($map[$key]);

api

Parameters

$key

mixed

Returns

boolean

Return a new map containing those keys and values that are present in the given collection.

intersect(\Haldayne\Boost\Map|\Haldayne\Boost\Contract\Arrayable|\Haldayne\Boost\Contract\Jsonable|\Haldayne\Boost\Traversable|object|array $collection, \Haldayne\Boost\enum $comparison = \Haldayne\Boost\Map::LOOSE) : \Haldayne\Boost\new
APIInherited

If comparison is loose, then only those elements whose value match will be included. Otherise, comparison is strict, and elements whose keys & values match will be included.

api

Parameters

$collection

\Haldayne\Boost\Map\Haldayne\Boost\Contract\Arrayable\Haldayne\Boost\Contract\Jsonable\Haldayne\Boost\Traversableobjectarray

$comparison

\Haldayne\Boost\enum

Returns

\Haldayne\Boost\newstatic

Put all of this map's elements into the target and return the target.

into(\Haldayne\Boost\Map $target) : \Haldayne\Boost\$target
APIInherited
$words = new MapOfStrings([ 'foo', 'bar' ]);
$words->map('strlen($_0)')->into(new MapOfInts)->sum(); // 6

Use when you've mapped your elements into a different type, and you want to fluently perform operations on the new type. In the example, the sum of the words' lengths was calculated.

api

Parameters

$target

Returns

\Haldayne\Boost\$target

Determine if any key and their values have been set into the map.

isEmpty() : boolean
APIInherited
api

Returns

boolean

Return a new map containing the last N elements passing the expression.

last(callable|string $expression, integer $n = 1) : \Haldayne\Boost\new
APIInherited

Like first, but stop after finding N elements from the end. Defaults to N = 1.

$nums = new Map(range(0, 9));
$odds = $nums->last('1 == ($_0 % 2)', 2); // last two odd numbers
api

Parameters

$expression

callablestring

$n

integer

Returns

\Haldayne\Boost\newstatic

Walk the map, applying the expression to every element, transforming them into a new map.

map(callable|string $expression) : \Haldayne\Boost\Map
APIInherited
$nums = new Map(range(0, 9));
$doubled = $nums->map('$_0 * 2');

The expression receives two arguments:

  • The current value in $_0
  • The current key in $_1

The keys in the resulting map will be the same as the keys in the original map: only the values have (potentially) changed.

Recommended to use this method when you are mapping from one type to the same type: int to int, string to string, etc. If you are changing types, use the more powerful transform method.

api

Parameters

$expression

callablestring

Returns

\Haldayne\Boost\Map

Merge the given collection into this map.

merge(\Haldayne\Boost\Map|\Haldayne\Boost\Contract\Arrayable|\Haldayne\Boost\Contract\Jsonable|\Haldayne\Boost\Traversable|object|array $collection, callable $merger, mixed $default = null) : \Haldayne\Boost\MapOfObjects
APIInherited

The merger callable decides how to merge the current map's value with the given collection's value. The merger callable receives two arguments:

  • This map's value at the given key
  • The collection's value at the given key

If the current map does not have a value for a key in the collection, then the default value is assumed.

api
fluent This method is part of a fluent interface and will return the same instance

Parameters

$collection

\Haldayne\Boost\Map\Haldayne\Boost\Contract\Arrayable\Haldayne\Boost\Contract\Jsonable\Haldayne\Boost\Traversableobjectarray

$merger

callable

$default

mixed

Returns

\Haldayne\Boost\MapOfObjects

Test that no elements pass the expression.

none(callable|string $expression) : boolean
APIInherited
api

Parameters

$expression

callablestring

Returns

boolean

Determine if a value exists at a given key.

offsetExists(mixed $key) : boolean
Inherited

Parameters

$key

mixed

Returns

boolean

Get a value at a given key.

offsetGet(mixed $key) : mixed
Inherited

Parameters

$key

mixed

Returns

mixed

Set the value at a given key.

offsetSet(mixed $key, mixed $value) : void
Inherited

If key is null, the value is appended to the array using numeric indexes, just like native PHP. Unlike native-PHP, $key can be of any type: boolean, int, float, string, array, object, closure, resource.

Parameters

$key

mixed

$value

mixed

Unset the value at a given key.

offsetUnset(mixed $key) : void
Inherited

Parameters

$key

mixed

Groups elements of this map based on the result of an expression.

partition(callable|string $expression) : \Haldayne\Boost\MapOfCollections
APIInherited

Calls the expression for each element in this map. The expression receives the value and key, respectively. The expression may return any value: this value is the grouping key and the element is put into that group.

$nums = new Map(range(0, 9));
$part = $nums->partition(function ($value, $key) {
   return 0 == $value % 2 ? 'even' : 'odd';
});
var_dump(
    $part['odd']->count(), // 5
    array_sum($part['even']->toArray()) // 20
);
api

Parameters

$expression

callablestring

Returns

\Haldayne\Boost\MapOfCollections

Treat the map as a stack and pop an element off its end.

pop() : mixed
APIInherited
api

Returns

mixed

Treat the map as a stack and push an element onto its end.

push($element) : \Haldayne\Boost\MapOfObjects
APIInherited
api
fluent This method is part of a fluent interface and will return the same instance

Parameters

$element

Returns

\Haldayne\Boost\MapOfObjects

Walk the map, applying a reducing expression to every element, so as to reduce the map to a single value.

reduce(callable|string $reducer, mixed $initial = null, callable|string|null $finisher = null) : mixed
APIInherited

The $reducer expression receives three arguments:

  • The current reduction ($_0)
  • The current value ($_1)
  • The current key ($_2)

The initial value, if given or null if not, is passed as the current reduction on the first invocation of $reducer. The return value from $reducer then becomes the new, current reduced value.

$nums = new Map(range(0, 3));
$sum = $nums->reduce('$_0 + $_1');
// $sum == 6

If $finisher is a callable or string expression, then it will be called last, after iterating over all elements. It will be passed reduced value. The $finisher must return the new final value.

api
see

Parameters

$reducer

callablestring

$initial

mixed

$finisher

callablestringnull

Returns

mixed

Change the key for every element in the map using an expression to calculate the new key.

rekey(callable|string $expression) : \Haldayne\Boost\new
APIInherited
$keyed_by_bytecode = new Map(count_chars('war of the worlds', 1));
$keyed_by_letter   = $keyed_by_bytecode->rekey('chr($_1)');
api

Parameters

$expression

callablestring

Returns

\Haldayne\Boost\newstatic

Set a key and its corresponding value into the map.

set(mixed $key, mixed $value) : \Haldayne\Boost\MapOfObjects
APIInherited

This is the object method equivalent of the magic $map[$key] = 'foo'.

api
fluent This method is part of a fluent interface and will return the same instance

Parameters

$key

mixed

$value

mixed

Returns

\Haldayne\Boost\MapOfObjects

Test if at least one element passes the expression.

some(callable|string $expression) : boolean
APIInherited
api

Parameters

$expression

callablestring

Returns

boolean

Copy this map into an array, recursing as necessary to convert contained collections into arrays.

toArray() 
APIInherited
api
inherited_from \Haldayne\Boost\Contract\Arrayable::toArray()

Return a JSON representation of the object.

toJson($options = 0
APIInherited
api
inherited_from \Haldayne\Boost\Contract\Jsonable::toJson()

Parameters

$options

Flexibly and thoroughly change this map into another map.

transform(callable $transformer, callable|null $creator = null, callable|null $finisher = null) : mixed
APIInherited
// transform a word list into a map of word to frequency in the list
use Haldayne\Boost\Map;
$words   = new Map([ 'bear', 'bee', 'goose', 'bee' ]);
$lengths = $words->transform(
    function (Map $new, $word) {
        if ($new->has($word)) {
            $new->set($word, $new->get($word)+1);
        } else {
            $new->set($word, 1);
        }
    }
);

Sometimes you need to create one map from another using a strategy that isn't one-to-one. You may need to change keys. You may need to add multiple elements. You may need to delete elements. You may need to change from a map to a number.

Whatever the case, the other simpler methods in Map don't quite fit the problem. What you need, and what this method provides, is a complete machine to transform this map into something else:

// convert a word list into a count of unique letters in those words
use Haldayne\Boost\Map;
$words   = new Map([ 'bear', 'bee', 'goose', 'bee' ]);
$letters = $words->transform(
    function ($frequencies, $word) {
        foreach (count_chars($word, 1) as $byte => $frequency) {
            $letter = chr($byte);
            if ($frequencies->has($letter)) {
                $new->set($letter, $frequencies->get($letter)+1);
            } else {
                $new->set($letter, 1);
            }
        }
    },
    function (Map $original) { return new MapOfIntegers(); },
    function (MapOfIntegers $new) { return $new->sum(); }
);

This method accepts three callables

  1. $creator, which is called first with the current map, performs any initialization needed. The result of this callable will be passed to all the other callables. If no creator is given, then use a default one that returns an empty Map.

  2. $transformer, which is called for every element in this map and receives the initialized value, the current value, and the current key in that order. The transformer should modify the initialized value appropriately. Often this means adding to a new map zero or more tranformed values.

  3. $finisher, which is called last, receives the initialized value that was modified by the transformer calls. The finisher may transform that value once more as needed. If no finisher given, then no finishing step is made.
api

Parameters

$transformer

$creator

callablenull

$finisher

callablenull

Returns

mixed

Decides if the given element should be allowed into the map.

allowed(mixed $value) 
inherited_from \Haldayne\Boost\GuardedMapAbstract::allowed()

Parameters

$value

Decides if the given element should be allowed into the map.

allowed(mixed $value) : boolean
Inherited

Parameters

$value

mixed

Returns

boolean

Give me a native PHP array, regardless of what kind of collection-like structure is given.

collection_to_array($collection) : array | boolean
Inherited

Parameters

$collection

Exceptions

\InvalidArgumentException

Returns

arrayboolean

Finds elements for which the given code passes, optionally limited to a maximum count.

grep(callable|string $expression, integer|null $limit = null) : \Haldayne\Boost\new
Inherited

If limit is null, no limit on number of matches. If limit is positive, return that many from the front of the array. If limit is negative, return that many from the end of the array.

Parameters

$expression

callablestring

$limit

integernull

Returns

\Haldayne\Boost\newstatic

Decide if the given value is considered collection-like.

is_collection_like(mixed $value) : boolean
Inherited

Parameters

$value

mixed

Returns

boolean

Normalize the value before storing.

normalize(mixed $value) : mixed
Inherited

This default implementation does nothing.

Parameters

$value

mixed

Returns

mixed

Decide if the given result is considered "passing" or "failing".

passes(mixed $result) : boolean
Inherited

This method provides a definitive reference for what this and all derived classes consider passing:

  • if the result is strictly false, the result "failed"
  • otherwise, the result "succeeded"

Parameters

$result

mixed

Returns

boolean

Execute the given code over each element of the map. The code receives the value by reference and then the key as formal parameters.

walk(callable $code) : \Haldayne\Boost\MapOfObjects
Inherited

The items are walked in the order they exist in the map. If the code returns boolean false, then the iteration halts. Values can be modified from within the callback, but not keys.

Example:

$map->each(function (&$value, $key) { $value++; return true; })->sum();
fluent This method is part of a fluent interface and will return the same instance

Parameters

$code

callable

Returns

\Haldayne\Boost\MapOfObjects

Like `walk`, except walk from the end toward the front.

walk_backward(callable $code) : \Haldayne\Boost\MapOfObjects
Inherited
fluent This method is part of a fluent interface and will return the same instance

Parameters

$code

callable

Returns

\Haldayne\Boost\MapOfObjects

Call the expression with the arguments.

call(callable|string $expression) 
Inherited

Parameters

$expression

callablestring

Exceptions

\InvalidArgumentException

Lookup the key for the given hash.

hash_to_key(string $hash) : mixed
Inherited

Parameters

$hash

string

Returns

mixed

Lookup the hash for the given key. If a hash does not yet exist, one is created.

key_to_hash(mixed $key) : string
Inherited

Parameters

$key

mixed

Exceptions

\InvalidArgumentException

Returns

string

 Properties

 

The internal array representation of the map.

$array : array

Default

array()
 

Track hashes we've created for non-string keys.

$map_key_to_hash : array

Default

array()

 Constants

 

Should the comparison be made loosely?

LOOSE = true 
API
see
see
api
 

Should the comparison be made strictly?

STRICT = false 
API
see
see
api