Operations.md

Operations

Is there an operation you'd like to see? Open an issue or vote on an existing one.

Iterable

Operation	Signature
all / every	all($iterable, $predicate = 'Dash\identity'): boolean
any / some	any($iterable, $predicate = 'Dash\identity'): boolean
at	at($iterable, $index, $default = null): mixed
average / mean	average($iterable): double|null
contains / includes	contains($iterable, $target, $comparator = 'Dash\equal'): boolean
deltas	deltas($iterable): array
difference	difference($iterable /*, ...iterables */): array
each	each($iterable, $iteratee): mixed
filter	filter($iterable, $predicate = 'Dash\identity'): array|iterable
find	find($iterable, $predicate = 'Dash\identity'): array|null
findKey	findKey($iterable, $predicate = 'Dash\identity'): string|null
findLast	findLast($iterable, $predicate = 'Dash\identity'): array|null
findLastKey	findLastKey($iterable, $predicate = 'Dash\identity'): string|null
findLastValue	findLastValue($iterable, $predicate = 'Dash\identity'): mixed|null
findValue	findValue($iterable, $predicate = 'Dash\identity'): mixed|null
first / head	first($iterable): mixed|null
groupBy	groupBy($iterable, $iteratee = 'Dash\identity', $defaultGroup = null): array
intersection	intersection($iterable /*, ...iterables */): array
isIndexedArray	isIndexedArray($value): boolean
join / implode	join($iterable, $separator): string
keyBy / indexBy	keyBy($iterable, $iteratee = 'Dash\identity'): array
keys	keys($iterable): array
last	last($iterable): mixed|null
map	map($iterable, $iteratee = 'Dash\identity'): array
mapValues	mapValues($iterable, $iteratee = 'Dash\identity'): array
matchesProperty	matchesProperty($path, $value = true, $comparator = 'Dash\equal'): function
max	max($iterable): mixed|null
median	median($iterable): mixed|null
min	min($iterable): mixed|null
omit	omit($iterable, $keys): array
pick	pick($iterable, $keys): array
pluck	pluck($iterable, $path, $default = null): array
property	property($path, $default = null): function
reduce	reduce($iterable, $iteratee, $initial = []): mixed
reject	reject($iterable, $predicate = 'Dash\identity'): array
reverse	reverse($iterable, $preserveIntegerKeys = false): array
rotate	rotate($iterable, $count = 1): array
sort	sort($iterable, $comparator = 'Dash\compare'): array
sum	sum($iterable): numeric
take	take($iterable, $count = 1): array|iterable
takeRight	takeRight($iterable, $count = 1): array
toArray	toArray($value): array
toObject	toObject($value): object
union	union($iterable /*, ...iterables */): array
values	values($iterable): array

Utility

Operation	Signature
assertType	assertType($value, $type, $funcName = __FUNCTION__): void
chain	chain($input = null): Dash\_
compare	compare($a, $b): integer
custom	custom($name): function
debug	debug($value /*, ...value */): mixed
equal	equal($a, $b): boolean
get	get($input, $path, $default = null): mixed
getDirect	getDirect($input, $key, $default = null): mixed
getDirectRef	getDirectRef(&$input, $key): mixed
hasDirect	hasDirect($input, $key): boolean
identical	identical($a, $b): boolean
identity	identity($value): mixed
isEmpty	isEmpty($value): boolean
isType	isType($value, $type): boolean
result	result($input, $path, $default = null): mixed
set	set(&$input, $path, $value): mixed
size / count	size($value, $encoding = 'UTF-8'): integer
tap	tap($value, callable $interceptor): mixed
thru	thru($value, callable $interceptor): mixed

Callable

Operation	Signature
apply	apply(callable $callable, $args): mixed
ary	ary(callable $callable, $arity): callable
call	call(callable $callable /*, ...args */): mixed
currify	currify(callable $callable, array $args = [], $rotate = 1): function|mixed
currifyN	currifyN(callable $callable, $totalArgs, array $args = [], $rotate = 1): function|mixed
curry	curry(callable $callable /*, ...args */): function|mixed
curryN	curryN(callable $callable, $numRequiredArgs /*, ...args */): function|mixed
curryRight	curryRight(callable $callable /*, ...args */): function|mixed
curryRightN	curryRightN(callable $callable, $numRequiredArgs /*, ...args */): function|mixed
negate	negate(callable $predicate): callable
partial	partial($callable /*, ...args */): callable
partialRight	partialRight($callable /*, ...args */): callable
unary	unary(callable $callable): callable

Number

Operation	Signature
isEven	isEven($value): boolean
isOdd	isOdd($value): boolean

Iterable

all / every

Operations › Iterable

all($iterable, $predicate = 'Dash\identity'): boolean

# Curried: (all parameters required)
Curry\all($predicate, $iterable)

Checks whether $predicate returns truthy for every item in $iterable.

Iteration will stop at the first falsey return value.

Note: Returns true if $iterable is empty, because everything is true of empty iterables.

Parameter	Type	Description
$iterable	iterable|stdClass|null
$predicate	callable	(optional) Invoked with ($value, $key, $iterable) for each element in $iterable
Returns	boolean	true if $predicate returns truthy for every item in $iterable

Example:

Dash\all([1, 3, 5], 'Dash\isOdd');
// === true

Dash\all([1, 3, 5], function ($n) { return $n != 3; });
// === false

Dash\all([], 'Dash\isOdd');
// === true

Dash\all((object) ['a' => 1, 'b' => 3, 'c' => 5], 'Dash\isOdd');
// === true

Example: With the default predicate

Dash\all([true, true, true]);
// === true

Dash\all([true, false, true]);
// === false

↑ Top

any / some

Operations › Iterable

any($iterable, $predicate = 'Dash\identity'): boolean

# Curried: (all parameters required)
Curry\any($predicate, $iterable)

Checks whether $predicate returns truthy for any item in $iterable.

Iteration will stop at the first truthy return value.

Parameter	Type	Description
$iterable	iterable|stdClass|null
$predicate	callable	(optional) Invoked with ($value, $key, $iterable) for each element in $iterable
Returns	boolean	true if $predicate returns truthy for any element in $iterable

Example:

Dash\any([1, 2, 3], 'Dash\isEven');
// === true

Dash\any([1, 2, 3], function ($n) { return $n > 5; });
// === false

Dash\any([], 'Dash\isOdd');
// === false

Dash\any((object) ['a' => 1, 'b' => 2, 'c' => 3], 'Dash\isEven');
// === true

Example: With the default predicate

Dash\any([false, true, true]);
// === true

Dash\any([false, false, false]);
// === false

↑ Top

at

Operations › Iterable

at($iterable, $index, $default = null): mixed

# Curried: (all parameters required)
Curry\at($index, $default, $iterable)

Iterates over $iterable and returns the value of the $indexth element, ignoring keys.

Parameter	Type	Description
$iterable	iterable|stdClass|null
$index	integer	0-based index
$default	mixed	(optional) Value to return if $index is out of bounds
Returns	mixed	Value of the $indexth item of `$iterable, ignoring keys

Example:

Dash\at(['a', 'b', 'c'], 0);
// === 'a'

Dash\at([2 => 'a', 1 => 'b', 0 => 'c'], 0);
// === 'a'

Dash\at(['a' => 'first', 'b' => 'second', 'c' => 'third'], 2);
// === 'third'

Example: With a custom default value

Dash\at(['a', 'b', 'c'], 5, 'none');
// === 'none'

↑ Top

average / mean

Operations › Iterable

average($iterable): double|null

# Curried: (all parameters required)
Curry\average($iterable)

Gets the average value of all elements in $iterable.

Parameter	Type	Description
$iterable	iterable|stdClass|null
Returns	double|null	Null if $iterable is empty

Example:

Dash\average([2, 3, 5, 8]);
// === 4.5

↑ Top

contains / includes

Operations › Iterable

contains($iterable, $target, $comparator = 'Dash\equal'): boolean

# Curried: (all parameters required)
Curry\contains($target, $comparator, $iterable)

Checks whether $iterable has any elements for which $comparator returns truthy.

Parameter	Type	Description
$iterable	iterable|stdClass|null
$target	mixed	Value to compare
$comparator	callable	Invoked with ($target, $value) for each element in $iterable
Returns	boolean	true if $comparator returns truthy for any element in $iterable

Example: With loose equality comparison (the default)

Dash\contains([1, '2', 3], 2);
// === true

Example: With strict equality comparison

Dash\contains([1, '2', 3], 2, 'Dash\identical');
// === false

↑ Top

deltas

Operations › Iterable

deltas($iterable): array

# Curried: (all parameters required)
Curry\deltas($iterable)

Returns a new array whose values are the differences between successive values of $iterable.

Parameter	Type	Description
$iterable	iterable|stdClass|null
Returns	array

Example:

Dash\deltas([3, 8, 9, 9, 5, 13]);
// === [0, 5, 1, 0, -4, 8]

↑ Top

difference

Operations › Iterable

difference($iterable /*, ...iterables */): array

Returns the set of elements from $iterable whose values are not present in any of the other iterables, where values are compared using loose equality.

The order, keys, and values of elements in the returned array are determined by $iterable.

Related: intersection(), union()

Parameter	Type	Description
$iterable	iterable|stdClass|null	(variadic) Iterable against which all other passed iterables are compared
Returns	array

Example: With indexed arrays

Dash\difference(
	[1, 2, 3, 4, 5],
	['2', 4],
	[3.0, 4]
);
// === [1, 5]

Example: With associative arrays

Dash\difference(
	['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5],
	['a' => '2', 'b' => 4],
	['a' => 3.0, 'b' => 4]
);
// === ['a' => 1, 'e' => 5]

↑ Top

each

Operations › Iterable

each($iterable, $iteratee): mixed

# Curried: (all parameters required)
Curry\each($iteratee, $iterable)

Iterates over elements of $iterable and invokes $iteratee for each element.

$iteratee is invoked with ($value, $key, $iterable) for each element. Iteratees can exit iteration early by returning false. Any changes to $value, $key, or $iterable from within the iteratee will not persisted.

Parameter	Type	Description
$iterable	iterable|stdClass|null
$iteratee	callable
Returns	mixed	$iterable The original $iterable

Example:

Dash\each(['a', 'b', 'c'], function ($value, $index, $array) {
	echo "[$index]: $value\n";
});
// Prints:
// [0]: 'a'
// [1]: 'b'
// [2]: 'c'

Example: Early exit

Dash\each(['a', 'b', 'c'], function ($value, $index, $array) {
	echo "[$index]: $value\n";
	if ($value === 'b') {
		return false;
	}
});
// Prints:
// [0]: 'a'
// [1]: 'b'

↑ Top

filter

Operations › Iterable

filter($iterable, $predicate = 'Dash\identity'): array|iterable

# Curried: (all parameters required)
Curry\filter($predicate, $iterable)

Gets a list of elements in $iterable for which $predicate returns truthy.

Keys are preserved unless $iterable is an indexed array. An indexed array is one with sequential integer keys starting at zero. See isIndexedArray()

Related: reject()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$predicate	callable|string|array	(optional) If a callable, invoked with ($value, $key, $iterable) for each element in $iterable; if a string, will get elements with truthy values at $field; if an array of form [$field, $value], will get elements whose $field loosely equals $value
Returns	array|iterable	List of elements in $iterable that satisfy $predicate

Example:

Dash\filter([1, 2, 3, 4], 'Dash\isEven');
// === [2, 4]

Dash\filter(
	[3 => 'c', 1 => 'a', 2 => 'b'],
	function ($value, $key) { return $key > 1; }
);
// === [3 => 'c', 2 => 'b']

Example: The default predicate checks truthiness

Dash\filter([1, 2, null, 3, false, true]);
// === [1, 2, 3, true]

Example: With a field and value

$data = [
	['name' => 'John', 'active' => false],
	['name' => 'Mary', 'active' => true],
	['name' => 'Pete', 'active' => true],
];

Dash\filter($data, 'active');
// === [
	['name' => 'Mary', 'active' => true],
	['name' => 'Pete', 'active' => true]
]

Dash\filter($data, ['active', false]);
// === [
	['name' => 'John', 'active' => false],
]

↑ Top

find

Operations › Iterable

find($iterable, $predicate = 'Dash\identity'): array|null

# Curried: (all parameters required)
Curry\find($predicate, $iterable)

Gets the key and value of the first element for which $predicate returns truthy.

Iteration will stop at the first truthy return value.

Related: findKey(), findValue(), findLast()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$predicate	callable|string|array	(optional) If a callable, invoked with ($value, $key, $iterable) for each element in $iterable until a truthy value is returned; if a string, will get the first element with a truthy value at $field; if an array of form [$field, $value], will get the first element whose $field loosely equals $value
Returns	array|null	[$key, $value] of the matching key and value, or null if not found

Example:

Dash\find(['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4], 'Dash\isEven');
// === ['b', 2]

Dash\find(
	['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4],
	function ($value, $key) { return $value > 1 && $key !== 'b'; }
);
// === ['c', 3]

Example: The default predicate checks truthiness

Dash\find([0, null, false, 'a', true]);
// === [3, 'a']

Example: With a field and value

$data = [
	['name' => 'John', 'active' => false],
	['name' => 'Mary', 'active' => true],
	['name' => 'Pete', 'active' => true],
	['name' => 'Jane', 'active' => false],
];

Dash\find($data, 'active');
// === [1, ['name' => 'Mary', 'active' => true]]

Dash\find($data, ['active', false]);
// === [0, ['name' => 'John', 'active' => false]]

↑ Top

findKey

Operations › Iterable

findKey($iterable, $predicate = 'Dash\identity'): string|null

# Curried: (all parameters required)
Curry\findKey($predicate, $iterable)

Gets the key of the first element for which $predicate returns truthy.

Iteration will stop at the first truthy return value.

Related: find(), findValue(), findLastKey()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$predicate	callable|string|array	(optional) If a callable, invoked with ($value, $key, $iterable) for each element in $iterable until a truthy value is returned; if a string, will get the first element with a truthy value at $field; if an array of form [$field, $value], will get the first element whose $field loosely equals $value
Returns	string|null	The key of the first matching element, or null if not found

Example:

Dash\findKey(['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4], 'Dash\isEven');
// === 'b'

Dash\findKey(
	['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4],
	function ($value, $key) { return $value > 1 && $key !== 'b'; }
);
// === 'c'

Example: The default predicate checks truthiness

Dash\findKey([0, null, false, 'a', true]);
// === 3

Example: With a field and value

$data = [
	['name' => 'John', 'active' => false],
	['name' => 'Mary', 'active' => true],
	['name' => 'Pete', 'active' => true],
	['name' => 'Jane', 'active' => false],
];

Dash\findKey($data, 'active');
// === 1

Dash\findKey($data, ['active', false]);
// === 0

↑ Top

findLast

Operations › Iterable

findLast($iterable, $predicate = 'Dash\identity'): array|null

# Curried: (all parameters required)
Curry\findLast($predicate, $iterable)

Gets the key and value of the last element for which $predicate returns truthy.

Iteration begin at the end and will stop at the last truthy return value.

Related: findLastKey(), findLastValue(), find()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$predicate	callable|string|array	(optional) If a callable, invoked with ($value, $key, $iterable) for each element in $iterable until a truthy value is returned; if a string, will get the last element with a truthy value at $field; if an array of form [$field, $value], will get the last element whose $field loosely equals $value
Returns	array|null	[$key, $value] of the last matching element, or null if not found

Example:

Dash\findLast(['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4], 'Dash\isEven');
// === ['d', 4]

Dash\findLast(
	['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4],
	function ($value, $key) { return $value > 1 && $key !== 'b'; }
);
// === ['d', 4]

Example: The default predicate checks truthiness

Dash\findLast([0, null, false, 'a', true]);
// === [4, true]

Example: With a field and value

$data = [
	['name' => 'John', 'active' => false],
	['name' => 'Mary', 'active' => true],
	['name' => 'Pete', 'active' => true],
	['name' => 'Jane', 'active' => false],
];

Dash\findLast($data, 'active');
// === [2, ['name' => 'Pete', 'active' => true]]

Dash\findLast($data, ['active', false]);
// === [3, ['name' => 'Jane', 'active' => false]]

↑ Top

findLastKey

Operations › Iterable

findLastKey($iterable, $predicate = 'Dash\identity'): string|null

# Curried: (all parameters required)
Curry\findLastKey($predicate, $iterable)

Gets the key of the last element for which $predicate returns truthy.

Iteration begin at the end and will stop at the last truthy return value.

Related: findLast(), findLastValue(), findKey()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$predicate	callable|string|array	(optional) If a callable, invoked with ($value, $key, $iterable) for each element in $iterable until a truthy value is returned; if a string, will get the last element with a truthy value at $field; if an array of form [$field, $value], will get the last element whose $field loosely equals $value
Returns	string|null	The key of the last matching element, or null if not found

Example:

Dash\findLastKey(['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4], 'Dash\isEven');
// === 'd'

Dash\findLastKey(
	['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4],
	function ($value, $key) { return $value > 1 && $key !== 'b'; }
);
// === 'd'

Example: The default predicate checks truthiness

Dash\findLastKey([0, null, false, 'a', true]);
// === 4

Example: With a field and value

$data = [
	['name' => 'John', 'active' => false],
	['name' => 'Mary', 'active' => true],
	['name' => 'Pete', 'active' => true],
	['name' => 'Jane', 'active' => false],
];

Dash\findLastKey($data, 'active');
// === 2

Dash\findLastKey($data, ['active', false]);
// === 3

↑ Top

findLastValue

Operations › Iterable

findLastValue($iterable, $predicate = 'Dash\identity'): mixed|null

# Curried: (all parameters required)
Curry\findLastValue($predicate, $iterable)

Gets the value of the last element for which $predicate returns truthy.

Iteration begin at the end and will stop at the last truthy return value.

Related: findLast(), findLastKey(), findValue()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$predicate	callable|string|array	(optional) If a callable, invoked with ($value, $key, $iterable) for each element in $iterable until a truthy value is returned; if a string, will get the last element with a truthy value at $field; if an array of form [$field, $value], will get the last element whose $field loosely equals $value
Returns	mixed|null	The value of the last matching element, or null if not found

Example:

Dash\findLastValue(['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4], 'Dash\isEven');
// === 4

Dash\findLastValue(
	['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4],
	function ($value, $key) { return $value > 1 && $key !== 'b'; }
);
// === 4

Example: The default predicate checks truthiness

Dash\findLastValue([0, null, false, 'a', true]);
// === true

Example: With a field and value

$data = [
	['name' => 'John', 'active' => false],
	['name' => 'Mary', 'active' => true],
	['name' => 'Pete', 'active' => true],
	['name' => 'Jane', 'active' => false],
];

Dash\findLastValue($data, 'active');
// === ['name' => 'Pete', 'active' => true]

Dash\findLastValue($data, ['active', false]);
// === ['name' => 'Jane', 'active' => false]

↑ Top

findValue

Operations › Iterable

findValue($iterable, $predicate = 'Dash\identity'): mixed|null

# Curried: (all parameters required)
Curry\findValue($predicate, $iterable)

Gets the value of the first element for which $predicate returns truthy.

Iteration will stop at the first truthy return value.

Related: find(), findKey(), findLastValue()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$predicate	callable|string|array	(optional) If a callable, invoked with ($value, $key, $iterable) for each element in $iterable until a truthy value is returned; if a string, will get the first element with a truthy value at $field; if an array of form [$field, $value], will get the first element whose $field loosely equals $value
Returns	mixed|null	The value of the first matching element, or null if not found

Example:

Dash\findValue(['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4], 'Dash\isEven');
// === 2

Dash\findValue(
	['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4],
	function ($value, $key) { return $value > 1 && $key !== 'b'; }
);
// === 3

Example: The default predicate checks truthiness

Dash\findValue([0, null, false, 'a', true]);
// === 'a'

Example: With a field and value

$data = [
	['name' => 'John', 'active' => false],
	['name' => 'Mary', 'active' => true],
	['name' => 'Pete', 'active' => true],
	['name' => 'Jane', 'active' => false],
];

Dash\findValue($data, 'active');
// === ['name' => 'Mary', 'active' => true]

Dash\findValue($data, ['active', false]);
// === ['name' => 'John', 'active' => false]

↑ Top

first / head

Operations › Iterable

first($iterable): mixed|null

# Curried: (all parameters required)
Curry\first($iterable)

Gets the value of the first element in $iterable.

Parameter	Type	Description
$iterable	iterable|stdClass|null
Returns	mixed|null	Null if $iterable is empty

Example:

Dash\first(['a' => 'one', 'b' => 'two', 'c' => 'three']);
// === 'one'

Dash\first([]);
// === null

↑ Top

groupBy

Operations › Iterable

groupBy($iterable, $iteratee = 'Dash\identity', $defaultGroup = null): array

# Curried: (all parameters required)
Curry\groupBy($iteratee, $defaultGroup, iterable)

Groups the element values of $iterable by the common return values of $iteratee.

Related: keyBy()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$iteratee	callable|string	(optional) If a callable, invoked with ($value, $key, $iterable) for each element in $iterable if a string, will use Dash\property($iteratee) as the iteratee
$defaultGroup	string	(optional) The key for the set of elements for which $iteratee returns null
Returns	array	A new associative array of [key => [value, ...]]

Example:

Dash\groupBy(['a' => 1, 'b' => 2, 'c' => 3], 'Dash\isOdd');
// === [true => [1, 3], false => [2]]

Dash\groupBy([2.1, 2.5, 3.5, 3.9, 4.1], Dash\unary('floor'));
// === [2 => [2.1, 2.5], 3 => [3.5, 3.9], 4 => [4.1]]

Example: With a path $iteratee

$data = [
	['first' => 'John', 'last' => 'Doe'],
	['first' => 'Alice', 'last' => 'Hart'],
	['first' => 'Anonymous'],
	['first' => 'Jane', 'last' => 'Doe'],
	['first' => 'Peter', 'last' => 'Gibbons'],
	['first' => 'Fred', 'last' => 'Hart'],
];

Dash\groupBy($data, 'last');
// === [
	'Doe' => [
		['first' => 'John', 'last' => 'Doe'],
		['first' => 'Jane', 'last' => 'Doe'],
	],
	'Hart' => [
		['first' => 'Alice', 'last' => 'Hart'],
		['first' => 'Fred', 'last' => 'Hart'],
	],
	'Gibbons' => [
		['first' => 'Peter', 'last' => 'Gibbons'],
	],
	null => [
		['first' => 'Anonymous'],
	],
]

Dash\groupBy($data, 'last', 'Unknown');
// === [
	'Doe' => [
		['first' => 'John', 'last' => 'Doe'],
		['first' => 'Jane', 'last' => 'Doe'],
	],
	'Hart' => [
		['first' => 'Alice', 'last' => 'Hart'],
		['first' => 'Fred', 'last' => 'Hart'],
	],
	'Gibbons' => [
		['first' => 'Peter', 'last' => 'Gibbons'],
	],
	'Unknown' => [
		['first' => 'Anonymous'],
	],
]

↑ Top

intersection

Operations › Iterable

intersection($iterable /*, ...iterables */): array

Returns the set of elements from $iterable whose values are present in each of the other iterables, where values are compared using loose equality.

The order, keys, and values of elements in the returned array are determined by $iterable.

Related: difference(), union()

Parameter	Type	Description
$iterable	iterable|stdClass|null	(variadic) Iterable against which all other passed iterables are compared
Returns	array

Example: With indexed arrays

Dash\intersection(
	[1, 2, 3, 4, 5],
	['2', '4'],
	[4.0, 2.0]
);
// === [2, 4]

Example: With associative arrays

Dash\intersection(
	['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5],
	['a' => 2, 'b' => 4],
	['a' => 4, 'b' => 2]
);
// === ['b' => 2, 'd' => 4]

↑ Top

isIndexedArray

Operations › Iterable

isIndexedArray($value): boolean

# Curried: (all parameters required)
Curry\isIndexedArray($value)

Checks whether $value is an array with sequential integer keys starting at 0.

Parameter	Type	Description
$value	mixed
Returns	boolean	True if $value is an indexed array, false otherwise

Example:

Dash\isIndexedArray(['a', 'b', 'c']);
// === true

Dash\isIndexedArray([1 => 'a', 'b', 'c']);
// === false

Dash\isIndexedArray(['a' => 1, 'b' => 2]);
// === false

↑ Top

join / implode

Operations › Iterable

join($iterable, $separator): string

# Curried: (all parameters required)
Curry\join($separator, $iterable)

Concatenates the string value of all elements in $iterable, with each value separated by $separator.

Parameter	Type	Description
$iterable	iterable|stdClass|null
$separator	string
Returns	string

Example:

Dash\join([123, 456, 789], '-');
// === '123-456-789'

Dash\join(['a' => 1, 'b' => 2, 'c' => 3], ', ');
// === '1, 2, 3'

↑ Top

keyBy / indexBy

Operations › Iterable

keyBy($iterable, $iteratee = 'Dash\identity'): array

# Curried: (all parameters required)
Curry\keyBy($iteratee, $iterable)

Gets the element values of $iterable as an associative array indexed by $iteratee.

A later value will overwrite an earlier value that has the same key.

Related: groupBy()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$iteratee	callable|string	(optional) If a callable, invoked with ($value, $key, $iterable) for each element in $iterable; if a string, will use Dash\property($iteratee) as the iteratee
Returns	array	A new associative array

Example:

$data = [
	['first' => 'John', 'last' => 'Doe'],
	['first' => 'Alice', 'last' => 'Hart'],
	['first' => 'Jane', 'last' => 'Smith'],
	['first' => 'Peter', 'last' => 'Gibbons'],
	['first' => 'Fred', 'last' => 'Durst'],
];

Dash\keyBy($data, function ($value) {
	return $value['first'] . ' ' . $value['last'];
});
// === [
	'John Doe' => ['first' => 'John', 'last' => 'Doe'],
	'Alice Hart' => ['first' => 'Alice', 'last' => 'Hart'],
	'Jane Smith' => ['first' => 'Jane', 'last' => 'Smith'],
	'Peter Gibbons' => ['first' => 'Peter', 'last' => 'Gibbons'],
	'Fred Durst' => ['first' => 'Fred', 'last' => 'Durst'],
]

Example: With a path $iteratee

$data = [
	['first' => 'John', 'last' => 'Doe'],
	['first' => 'Alice', 'last' => 'Hart'],
	['first' => 'Jane', 'last' => 'Smith'],
	['first' => 'Peter', 'last' => 'Gibbons'],
	['first' => 'Fred', 'last' => 'Durst'],
];

Dash\keyBy($data, 'last');
// === [
	'Doe' => ['first' => 'John', 'last' => 'Doe'],
	'Hart' => ['first' => 'Alice', 'last' => 'Hart'],
	'Smith' => ['first' => 'Jane', 'last' => 'Smith'],
	'Gibbons' => ['first' => 'Peter', 'last' => 'Gibbons'],
	'Durst' => ['first' => 'Fred', 'last' => 'Durst'],
]

↑ Top

keys

Operations › Iterable

keys($iterable): array

# Curried: (all parameters required)
Curry\keys($iterable)

Gets the keys of $iterable as an array.

Related: values()

Parameter	Type	Description
$iterable	iterable|stdClass|null
Returns	array

Example:

Dash\keys(['c' => 3, 'a' => 1, 'b' => 2]);
// === ['c', 'a', 'b']

↑ Top

last

Operations › Iterable

last($iterable): mixed|null

# Curried: (all parameters required)
Curry\last($iterable)

Gets the value of the last element in $iterable.

Parameter	Type	Description
$iterable	iterable|stdClass|null
Returns	mixed|null	Null if $iterable is empty

Example:

Dash\last(['a' => 'one', 'b' => 'two', 'c' => 'three']);
// === 'three'

Dash\last([]);
// === null

↑ Top

map

Operations › Iterable

map($iterable, $iteratee = 'Dash\identity'): array

# Curried: (all parameters required)
Curry\map($iteratee, $iterable)

Gets a new array of the return values of $iteratee when called with successive elements in $iterable.

Keys in $iterable are not preserved. To preserve keys, use mapValues() instead.

Related: mapValues()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$iteratee	callable|string|numeric	(optional) If a callable, invoked with ($value, $key, $iterable) for each element in $iterable; if a string, will use Dash\property($iteratee) as the iteratee
Returns	array	A new 0-indexed array

Example:

Dash\map(['a' => 1, 'b' => 2, 'c' => 3], function ($value) {
	return $value * 2;
});
// === [2, 4, 6]

Example: With a path $iteratee

$data = [
	'jdoe' => ['name' => ['first' => 'John', 'last' => 'Doe']],
	'mjane' => ['name' => ['first' => 'Mary', 'last' => 'Jane']],
	'psmith' => ['name' => ['first' => 'Pete', 'last' => 'Smith']],
];
Dash\map($data, 'name.last');
// === ['Doe', 'Jane', 'Smith']

↑ Top

mapValues

Operations › Iterable

mapValues($iterable, $iteratee = 'Dash\identity'): array

# Curried: (all parameters required)
Curry\mapValues($iteratee, $iterable)

Gets a new array of the return values of $iteratee when called with successive elements in $iterable.

Unlike map(), keys in $iterable are preserved.

Related: map()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$iteratee	callable|string	(optional) If a callable, invoked with ($value, $key, $iterable) for each element in $iterable; if a string, will use Dash\property($iteratee) as the iteratee
Returns	array	A new 0-indexed array

Example:

Dash\mapValues(['a' => 1, 'b' => 2, 'c' => 3], function ($value) {
	return $value * 2;
});
// === ['a' => 2, 'b' => 4, 'c' => 6]

Example: With a path $iteratee

$data = [
	'jdoe' => ['name' => ['first' => 'John', 'last' => 'Doe']],
	'mjane' => ['name' => ['first' => 'Mary', 'last' => 'Jane']],
	'psmith' => ['name' => ['first' => 'Pete', 'last' => 'Smith']],
];
Dash\mapValues($data, 'name.last');
// === ['jdoe' => 'Doe', 'mjane' => 'Jane', 'psmith' => 'Smith']

↑ Top

matchesProperty

Operations › Iterable

matchesProperty($path, $value = true, $comparator = 'Dash\equal'): function

# Curried: (all parameters required)
Curry\matchesProperty($value, $comparator, $path)

Creates a function that returns whether $comparator returns truthy for the value at $path for a given input.

Parameter	Type	Description
$path	callable|string|number|null	Any valid path supported by Dash\get()
$value	mixed	Value passed to $comparator for comparison
$comparator	callable	(optional) Function with signature ($valueAtPath, $value) that compares $value to the value at $path for the given input
Returns	function	Function with signature ($input) that returns whether the value at $path within $input

Example: Matches truthy field value

$matcher = Dash\matchesProperty('foo');
$matcher(['foo' => 'bar']);  // === true
$matcher(['foo' => null]);   // === false

Example: Matches falsey field value

$matcher = Dash\matchesProperty('foo', false);
$matcher(['foo' => false]);  // === true
$matcher(['foo' => 'bar']);  // === false

Example: Matches field value that loosely equals a given value

$matcher = Dash\matchesProperty('foo', 3);
$matcher(['foo' => 3.0]);  // === true
$matcher(['foo' => 4]);   // === false

Example: Matches field value for which a given comparator returns true

$matcher = Dash\matchesProperty('foo', 3, 'Dash\identical');
$matcher(['foo' => 3]);    // === true
$matcher(['foo' => 3.0]);  // === false

↑ Top

max

Operations › Iterable

max($iterable): mixed|null

# Curried: (all parameters required)
Curry\max($iterable)

Gets the maximum value of all elements in $iterable.

Parameter	Type	Description
$iterable	iterable|stdClass|null
Returns	mixed|null	Null if $iterable is empty

Example:

Dash\max([3, 8, 2, 5]);
// === 8

Dash\max([]);
// === null

↑ Top

median

Operations › Iterable

median($iterable): mixed|null

# Curried: (all parameters required)
Curry\median($iterable)

Returns the median value of an iterable.

Parameter	Type	Description
$iterable	iterable|stdClass|null
Returns	mixed|null	Null if $iterable is empty

Example:

Dash\median([3, 2, 1, 5, 4]);
// === 3

Dash\median([3, 2, 1, 4]);
// === 2.5

↑ Top

min

Operations › Iterable

min($iterable): mixed|null

# Curried: (all parameters required)
Curry\min($iterable)

Gets the minimum value of all elements in $iterable.

Parameter	Type	Description
$iterable	iterable|stdClass|null
Returns	mixed|null	Null if $iterable is empty

Example:

Dash\min([3, 8, 2, 5]);
// === 2

Dash\min([]);
// === null

↑ Top

omit

Operations › Iterable

omit($iterable, $keys): array

# Curried: (all parameters required)
Curry\omit($keys, $iterable)

Gets the elements of $iterable with keys that match any in $keys. The opposite of pick().

Related: pick()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$keys	string|array	Single key or list of keys
Returns	array

Example:

Dash\omit(['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4], ['b', 'c']);
// === ['a' => 1, 'd' => 4]

↑ Top

pick

Operations › Iterable

pick($iterable, $keys): array

# Curried: (all parameters required)
Curry\pick($keys, $iterable)

Gets the elements of $iterable with keys that match any in $keys.

Related: omit()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$keys	string|array	Single key or list of keys
Returns	array

Example:

Dash\pick(['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4], ['b', 'c']);
// === ['b' => 2, 'c' => 3]

↑ Top

pluck

Operations › Iterable

pluck($iterable, $path, $default = null): array

# Curried: (all parameters required)
Curry\pluck($path, $default, $iterable)

Gets an array of values at $path for all elements in $iterable.

Related: map()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$path	callable	Any valid path accepted by Dash\property()
$default	mixed	(optional) Default value for each element without a value at $path
Returns	array	New array of plucked values from $iterable

Example:

$data = [
	['name' => 'John'],
	['name' => 'Mary', 'age' => 35],
	['name' => 'Pete', 'age' => 20],
];

Dash\pluck($data, 'name');
// === ['John', 'Mary', 'Pete']

Dash\pluck($data, 'age');
// === [null, 35, 20]

↑ Top

property

Operations › Iterable

property($path, $default = null): function

# Curried: (all parameters required)
Curry\property($default, $path)

Creates a function that returns the value at a $path for a given input.

Parameter	Type	Description
$path	string|number|null	Path of the property to retrieve; can be nested by delimiting each sub-property or array index with a period.
$default	mixed	(optional) Default value to return if nothing exists at $path
Returns	function	Function with signature ($input) that returns the value at $path within $input

Example: Accepts arrays and objects

$getter = Dash\property('foo');
$getter(['foo' => 'value']);  // === 'value'
$getter((object) ['foo' => 'value']);  // === 'value'

Example: Methods can be accessed too

$getter = Dash\property('items.count');
$countFn = $getter(['items' => new ArrayObject([1, 2, 3])]);
$countFn();  // === 3

Example: Nested properties can be referenced with dot notation

$getter = Dash\property('a.b.c');
$getter([
	'a' => [
		'b' => [
			'c' => 'value'
		]
	]
]);
// === 'value'

Example: Array elements can be referenced by index

$getter = Dash\property('items.1.name');
$getter([
	'items' => [
		['name' => 'one'],
		['name' => 'two'],
		['name' => 'three'],
	]
]);
// === 'two'

Example: Keys with the same name as the full path can be used

$getter = Dash\property('a.b.c');
$getter(['a.b.c' => 'value']);  // === 'value'

↑ Top

reduce

Operations › Iterable

reduce($iterable, $iteratee, $initial = []): mixed

# Curried: (all parameters required)
Curry\reduce($iteratee, $initial, $iterable)

Iteratively reduces $iterable to a single value by way of $iteratee.

Parameter	Type	Description
$iterable	iterable|stdClass|null
$iteratee	callable	Called with ($result, $value, $key) for each ($key, $value) in $iterable and the current accumulated $result. $iteratee should return the updated $result
$initial	mixed	(optional) Initial value
Returns	mixed

Example: Computes the sum of an array's values

Dash\reduce([1, 2, 3, 4], function ($sum, $value) {
	return $sum + $value;
}, 0);
// === 10

↑ Top

reject

Operations › Iterable

reject($iterable, $predicate = 'Dash\identity'): array

# Curried: (all parameters required)
Curry\reject($predicate, $iterable)

Gets a list of elements in $iterable for which $predicate returns falsey. The opposite of filter().

Keys are preserved unless $iterable is an indexed array. An indexed array is one with sequential integer keys starting at zero. See isIndexedArray()

Related: filter()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$predicate	callable|string|array	(optional) If a callable, invoked with ($value, $key, $iterable) for each element in $iterable; if a string, will get elements with a falsey value for that field/index; if an array of form [$field, $value], will get elements where the field/index does not loosely equal $value
Returns	array	List of elements in $iterable that do not satisfy $predicate

Example:

Dash\reject([1, 2, 3, 4], 'Dash\isOdd');
// === [2, 4]

Dash\reject(
	[3 => 'c', 1 => 'a', 2 => 'b'],
	function ($value, $key) { return $key <= 1; }
);
// === [3 => 'c', 2 => 'b']

Example: The default predicate checks truthiness

Dash\reject([1, 2, null, 3, false, true]);
// === [null, false]

Example: With a field/value

$data = [
	['name' => 'John', 'active' => false],
	['name' => 'Mary', 'active' => true],
	['name' => 'Pete', 'active' => true],
];

Dash\reject($data, 'active');
// === [
	['name' => 'John', 'active' => false],
]

Dash\reject($data, ['active', false]);
// === [
	['name' => 'Mary', 'active' => true],
	['name' => 'Pete', 'active' => true]
]

↑ Top

reverse

Operations › Iterable

reverse($iterable, $preserveIntegerKeys = false): array

# Curried: (all parameters required)
Curry\reverse($preserveIntegerKeys, iterable)

Gets a new array of $iterable elements in reverse order.

Parameter	Type	Description
$iterable	iterable|stdClass|null
$preserveIntegerKeys	boolean	(optional) If true, integer keys will be preserved; non-integer keys are always preserved regardless of this setting
Returns	array	New array of $iterable elements in reverse order

Example:

Dash\reverse(['a', 'b', 'c']);
// === ['c', 'b', 'a']

Dash\reverse(['a' => 1, 'b' => 2, 'c' => 3]);
// === ['c' => 3, 'b' => 2, 'a' => 1]

Example: Preserving integer keys

Dash\reverse(['a', 'b', 'c'], true);
// === [2 => 'c', 1 => 'b', 0 => 'a']

Dash\reverse(['a', 'b', 'c'], false);
// === [0 => 'c', 1 => 'b', 2 => 'a']

↑ Top

rotate

Operations › Iterable

rotate($iterable, $count = 1): array

# Curried: (all parameters required)
Curry\rotate($count, $iterable)

Gets a new array of $iterable elements where $count elements are moved counter-clockwise from the beginning of $iterable to the end.

Keys are preserved unless $iterable is an indexed array. An indexed array is one with sequential integer keys starting at zero. See isIndexedArray()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$count	integer	If negative, moves $count elements from the end to the beginning
Returns	array	New array of rotated elements

Example:

Dash\rotate(['a', 'b', 'c', 'd', 'e'], 2);
// === ['c', 'd', 'e', 'a', 'b']

Dash\rotate(['a' => 1, 'b' => 2, 'c' => 3], 1);
// === ['b' => 2, 'c' => 3, 'a' => 1]

Dash\rotate(['a', 'b', 'c', 'd', 'e'], -1);
// === ['e', 'a', 'b', 'c', 'd']

↑ Top

sort

Operations › Iterable

sort($iterable, $comparator = 'Dash\compare'): array

# Curried: (all parameters required)
Curry\sort($comparator, $iterable)

Gets a new array containing the sorted elements of $iterable.

Keys are preserved unless $iterable is an indexed array. An indexed array is one with sequential integer keys starting at zero. See isIndexedArray()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$comparator	callable	(optional) Invoked with ($a, $b) where $a and $b are values in $iterable; $comparator should returns a number less than, equal to, or greater than zero if $a is less than, equal to, or greater than $b, respectively
Returns	array	New array of $iterable elements ordered by $comparator

Example:

Dash\sort([4, 2, 3, 1]);
// === [1, 2, 3, 4]

Dash\sort(['a' => 3, 'b' => 1, 'c' => 2]);
// === ['b' => 1, 'c' => 2, 'a' => 3]

↑ Top

sum

Operations › Iterable

sum($iterable): numeric

# Curried: (all parameters required)
Curry\sum($iterable)

Gets the sum of all element values in $iterable.

Parameter	Type	Description
$iterable	iterable|stdClass|null
Returns	numeric	Zero if $iterable is empty

Example:

Dash\sum([2, 3, 5, 8]);
// === 18

Dash\sum([]);
// === 0

↑ Top

take

Operations › Iterable

take($iterable, $count = 1): array|iterable

# Curried: (all parameters required)
Curry\take($count, $iterable)

Gets a new array of the first $count elements of $iterable.

Keys are preserved unless $iterable is an indexed array. An indexed array is one with sequential integer keys starting at zero. See isIndexedArray()

Related: takeRight()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$count	integer	If negative, gets all but the last $count elements of $iterable
Returns	array|iterable	New array of $count elements

Example:

Dash\take([2, 3, 5, 8, 13], 3);
// === [2, 3, 5]

Dash\take(['b' => 2, 'c' => 3, 'a' => 1], 2);
// === ['b' => 2, 'c' => 3]

Dash\take([1, 2, 3, 4, 5, 6], -2);
// === [1, 2, 3, 4]

↑ Top

takeRight

Operations › Iterable

takeRight($iterable, $count = 1): array

# Curried: (all parameters required)
Curry\takeRight($count, $iterable)

Gets a new array of the last $count elements of $iterable.

Keys are preserved unless $iterable is an indexed array. An indexed array is one with sequential integer keys starting at zero. See isIndexedArray()

Related: take()

Parameter	Type	Description
$iterable	iterable|stdClass|null
$count	integer	If negative, gets all but the first $count elements of $iterable
Returns	array	New array of $count elements

Example:

Dash\take([2, 3, 5, 8, 13], 3);
// === [5, 8, 13]

Dash\take(['b' => 2, 'c' => 3, 'a' => 1], 2);
// === ['c' => 3, 'a' => 1]

Dash\take([1, 2, 3, 4, 5, 6], -2);
// === [3, 4, 5, 6]

↑ Top

toArray

Operations › Iterable

toArray($value): array

# Curried: (all parameters required)
Curry\toArray($value)

Gets an array representation of $value.

Parameter	Type	Description
$value	mixed
Returns	array	Empty array if $value is not iterable

Example:

Dash\toArray((object) ['a' => 1, 'b' => 2]);
// === ['a' => 1, 'b' => 2]

Dash\toArray(new FilesystemIterator(__DIR__));
// === [ SplFileInfo, SplFileInfo, ... ]

↑ Top

toObject

Operations › Iterable

toObject($value): object

# Curried: (all parameters required)
Curry\toObject($value)

Gets a plain object representation of $value.

Parameter	Type	Description
$value	mixed
Returns	object	Empty object if $value is not iterable

Example:

Dash\toObject(['a' => 1, 'b' => 2]);
// === (object) ['a' => 1, 'b' => 2]

Dash\toObject(new ArrayObject(['a' => 1, 'b' => 2]));
// === (object) ['a' => 1, 'b' => 2]

↑ Top

union

Operations › Iterable

union($iterable /*, ...iterables */): array

Returns a new array containing the combined set of unique values, in order, of all provided iterables.

Non-indexed keys are preseved, but duplicate keys will overwrite previous ones.

Related: intersection(), difference()

Parameter	Type	Description
$iterable	iterable|stdClass|null	(variadic) One or more iterables to merge
Returns	array

Example: With indexed arrays

Dash\union(
	[1, 3, 5],
	[2, 4, 6],
	[7, 8]
);
// === [1, 3, 5, 2, 4, 6, 7, 8]

Example: With associative arrays

Dash\union(
	['a' => 1, 'c' => 3],
	['b' => 2, 'd' => 4],
	['e' => 5, 'f' => 6]
);
// === ['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5, 'f' => 6]

↑ Top

values

Operations › Iterable

values($iterable): array

# Curried: (all parameters required)
Curry\values($iterable)

Gets the values of $iterable as an array.

Related: keys()

Parameter	Type	Description
$iterable	iterable|stdClass|null
Returns	array

Example:

Dash\values(['c' => 3, 'a' => 1, 'b' => 2]);
// === [3, 1, 2]

↑ Top

Utility

assertType

Operations › Utility

assertType($value, $type, $funcName = __FUNCTION__): void

# Curried: (all parameters required)
Curry\assertType($type, $funcName, input)

Throws an InvalidArgumentException exception if $value is not of type $type. If $value is an accepted type, this function is a no-op.

Related: isType()

Parameter	Type	Description
$value	mixed
$type	string|array	Single type to check or a list of accepted types
$funcName	string	(optional) Name of the calling function where assertType() was called; this is used in the thrown exception message and aids debugging
Returns	void

Example:

$value = [1, 2, 3];
Dash\assertType($value, ['iterable', 'stdClass']);
// Does not throw an exception

$value = [1, 2, 3];
Dash\assertType($value, 'object');
// Throws an exception

↑ Top

chain

Operations › Utility

chain($input = null): Dash\_

# Curried: (all parameters required)
Curry\chain($input)

Creates a new chain. Alias for _::chain().

Parameter	Type	Description
$input	mixed	(optional) Initial input value of the chain
Returns	Dash\_	A new chain

Example:

Dash\chain([1, 2, 3])
	->filter(function ($n) { return $n < 3; })
	->map(function ($n) { return $n * 2; })
	->value();
// === [2, 4]

↑ Top

compare

Operations › Utility

compare($a, $b): integer

# Curried: (all parameters required)
Curry\compare($b, $a)

Returns a number less than, equal to, or greater than zero if $a is less than, equal to, or greater than $b, respectively.

Uses loose equality for comparison. For comparison tables across data types, see: http://php.net/manual/en/types.comparisons.php

Parameter	Type	Description
$a	mixed
$b	mixed
Returns	integer

Example:

Dash\compare(2, 3);
// < 0

Dash\compare(2, 1);
// > 0

Dash\compare(2, 2);
// === 0

↑ Top

custom

Operations › Utility

custom($name): function

# Curried: (all parameters required)
Curry\custom($name)

Gets a custom operation by name.

Parameter	Type	Description
$name	string	Name of the custom operation
Returns	function	The custom operation

Example:

_::setCustom('double', function ($n) { return $n * 2; });

$double = Dash\custom('double');
$double(3);
// === 6

_::chain([1, 2, 3])->map(Dash\custom('double'))->value();
// === [2, 4, 6]

↑ Top

debug

Operations › Utility

debug($value /*, ...value */): mixed

# Curried: (all parameters required)
Curry\debug(...value)

Prints debugging information for one or more values.

Parameter	Type	Description
$value	mixed	(variadic) One or more values to debug
Returns	mixed	The first argument

Example:

Dash\debug([1, 2, 3], 'hello', null);
// === [1, 2, 3]

// Prints:
array (
  0 => 1,
  1 => 2,
  2 => 3,
)
'hello'
NULL

@codeCoverageIgnore Due to output buffering

↑ Top

equal

Operations › Utility

equal($a, $b): boolean

# Curried: (all parameters required)
Curry\equal($b, $a)

Checks whether $a and $b are loosely equal (same value, possibly different types).

Parameter	Type	Description
$a	mixed
$b	mixed
Returns	boolean

Example:

Dash\equal(3, '3');
// === true

Dash\equal(3, 3);
// === true

Dash\equal([1, 2, 3], [1, '2', 3]);
// === true

Dash\equal([1, 2, 3], [3, 2, 1]);
// === false

↑ Top

get

Operations › Utility

get($input, $path, $default = null): mixed

# Curried: (all parameters required)
Curry\get($path, $default, $input)

Gets the value at $path within $input. Nested properties are accessible with dot notation.

Related: getDirect(), has(), property()

Parameter	Type	Description
$input	mixed
$path	callable|string|number	If a callable, invoked with ($input) to get the value at $path; if a string or number, Dash\property($path) used to get the value at $path
$default	mixed	(optional) Value to return if $path does not exist within $input
Returns	mixed	Value at $path or $default if no value exists

Example:

$input = [
	'people' => [
		['name' => 'Pete'],
		['name' => 'John'],
		['name' => 'Mark'],
	]
];
Dash\get($input, 'people.2.name');
// === 'Mark'

Example: Direct properties take precedence over nested ones

$input = [
	'a.b.c' => 'direct',
	'a' => ['b' => ['c' => 'nested']]
];
Dash\get($input, 'a.b.c');
// === 'direct'

↑ Top

getDirect

Operations › Utility

getDirect($input, $key, $default = null): mixed

# Curried: (all parameters required)
Curry\getDirect($key, $default, $iterable)

Gets the array value, object property, or method at $key within $input.

If an array offset, object property, and/or method all exist for the same key, the value at the array offset takes precedence and will be returned.

Related: getDirectRef(), hasDirect(), get()

Parameter	Type	Description
$input	mixed
$key	string	Array offset, object property name, or method name
$default	mixed	(optional) Value to return if $input has nothing at $key
Returns	mixed

Example:

Dash\getDirect(['a' => 'one', 'b' => 'two'], 'b');
// === 'two'

Dash\getDirect((object) ['a' => 'one', 'b' => 'two'], 'b');
// === 'two'

$count = Dash\getDirect(new ArrayObject([1, 2, 3]), 'count');
$count();
// === 3

Example: Array offsets take precedence over object properties

$input = new ArrayObject(['a' => 'array value']);
$input->a = 'object value';

Dash\getDirect($input, 'a');
// === 'array value'

↑ Top

getDirectRef

Operations › Utility

getDirectRef(&$input, $key): mixed

Similar to getDirect(), but returns a reference to the value at $key within $input.

Related: getDirect(), hasDirect()

Parameter	Type	Description
$input	array|object|ArrayAccess
$key	string	Array offset or object property name
Returns	mixed	Reference to $key within $input

Example:

$array = ['key' => 'value'];
$ref = &Dash\getDirectRef($array, 'key');
$ref = 'changed';
// $array['key'] === 'changed'

$object = (object) ['key' => 'value'];
$ref = &Dash\getDirectRef($object, 'key');
$ref = 'changed';
// $object->key === 'changed'

↑ Top

hasDirect

Operations › Utility

hasDirect($input, $key): boolean

# Curried: (all parameters required)
Curry\hasDirect($key, $input)

Checks whether an array value, object property, or method exists at $key within $input.

Related: getDirect()

Parameter	Type	Description
$input	mixed
$key	string	Array offset, object property name, or method name
Returns	boolean

Example:

Dash\hasDirect(['a' => 1, 'b' => 2], 'a');
// === true

Dash\hasDirect(['a' => 1, 'b' => 2], 'x');
// === false

Dash\hasDirect((object) ['a' => 1, 'b' => 2], 'a');
// === true

Dash\hasDirect(new DateTime(), 'getTimestamp');
// === true

↑ Top

identical

Operations › Utility

identical($a, $b): boolean

# Curried: (all parameters required)
Curry\identical($b, $a)

Checks whether $a and $b are strictly equal (same value and type).

Parameter	Type	Description
$a	mixed
$b	mixed
Returns	boolean

Example:

Dash\identical(3, '3');
// === false

Dash\identical(3, 3);
// === true

Dash\identical([1, 2, 3], [1, '2', 3]);
// === false

Dash\identical([1, 2, 3], [1, 2, 3]);
// === true

↑ Top

identity

Operations › Utility

identity($value): mixed

# Curried: (all parameters required)
Curry\identity($value)

Returns the first argument it receives.

Parameter	Type	Description
$value	mixed
Returns	mixed	$value unmodified

Example:

$a = new ArrayObject();
$b = Dash\identity($a);
// $b === $a

↑ Top

isEmpty

Operations › Utility

isEmpty($value): boolean

# Curried: (all parameters required)
Curry\isEmpty($value)

Checks whether $value is empty.

A value is empty if it is an iterable of size zero or loosely equals false.

Parameter	Type	Description
$value	mixed
Returns	boolean	True if $value is empty, false otherwise

Example:

Dash\isEmpty([]);
// === true

Dash\isEmpty((object) []);
// === true

Dash\isEmpty(new ArrayObject());
// === true

Dash\isEmpty('');
// === true

Dash\isEmpty(0);
// === true

Dash\isEmpty([0]);
// === false

↑ Top

isType

Operations › Utility

isType($value, $type): boolean

# Curried: (all parameters required)
Curry\isType($type, $value)

Checks whether $value is of a particular data type.

A types can be:

• a native data type: string, array, integer, etc.
• a type corresponding to a native is_*() function: numeric (for is_numeric()), callable (for is_callable()), etc.
• a class name: stdClass, DateTime, Dash\_, etc.

Parameter	Type	Description
$value	mixed
$type	string|array	Single type to check or a list of accepted types
Returns	boolean

Example: With a native data type

Dash\isType([1, 2, 3], 'array');
// === true

Example: With a type corresponding to a native is_*() function

Dash\isType(3.14, 'numeric');
// === true

Example: With a class name

Dash\isType(new ArrayObject([1, 2, 3]), 'ArrayObject');
// === true

Example: With multiple types

Dash\isType((object) [1, 2, 3], ['array', 'object']);
// === true

↑ Top

result

Operations › Utility

result($input, $path, $default = null): mixed

# Curried: (all parameters required)
Curry\result($path, $default, $input)

Gets the value at $path within $input. Nested properties are accessible with dot notation. Like get() but if the value is callable, it is invoked and its return value is returned.

Related: get(), property()

Parameter	Type	Description
$input	mixed
$path	callable|string	If a callable, invoked with ($input) to get the value at $path; if a string, will use Dash\property($path) to get the value at $path
$default	mixed	(optional) Value to return if $path does not exist within $input
Returns	mixed	Value at $path or $default if no value exists

Example:

$input = [
	'people' => new ArrayObject([
		['name' => 'Pete', 'getHash' => function () { return '4d17a4'; }],
		['name' => 'John', 'getHash' => function () { return 'fd2a48'; }],
		['name' => 'Paul', 'getHash' => function () { return 'd8575d'; }],
	])
];

Dash\result($input, 'people.1.name');
// === 'John'

Dash\result($input, 'people.count');
// === 3

Dash\result($input, 'people.1.joined.getTimestamp');
// === 'fd2a48'

↑ Top

set

Operations › Utility

set(&$input, $path, $value): mixed

Sets the value at $path within $input. Nested properties are accessible with dot notation. Note: This will modify $input.

Related: get(), getDirect(), property()

Parameter	Type	Description
$input	mixed
$path	string	Path at which to set $value; can be a nested path (eg. a.b.0.c). Intermediate arrays or objects will be created where missing (see examples)
$value	mixed	Value to set at $path
Returns	mixed	$input, modified

Example:

$input = (object) [
	'a' => [1, 2],
	'b' => [3, 4],
	'c' => [5, 6],
];
Dash\set($input, 'a', [7, 8, 9]);
Dash\set($input, 'b.0', 10);

// $input === (object) [
	'a' => [7, 8, 9],
	'b' => [10, 4],
	'c' => [5, 6],
]

Example: Intermediate array/objects are created if missing

$input = ['a' => []];
Dash\set($input, 'a.b.c', 'value');

// $input === [
	'a' => [
		'b' => [
			'c' => 'value'
		]
	]
]

$input = ['a' => (object) []];
Dash\set($input, 'a.b.c', 'value');

// $input === [
	'a' => (object) [
		'b' => (object) [
			'c' => 'value'
		]
	]
]

↑ Top

size / count

Operations › Utility

size($value, $encoding = 'UTF-8'): integer

# Curried: (all parameters required)
Curry\size($value)

Gets the number of items in $value.

For iterables, this is the number of elements. For strings, this is number of characters.

Parameter	Type	Description
$value	iterable|string
$encoding	string	(optional) The character encoding of $value if it is a string; see mb_list_encodings() for the list of supported encodings
Returns	integer	Size of $value or zero if $value is neither iterable nor a string

Example:

Dash\size([1, 2, 3]);
// === 3

Dash\size('Beyoncé');
// === 7

↑ Top

tap

Operations › Utility

tap($value, callable $interceptor): mixed

# Curried: (all parameters required)
Curry\tap($interceptor, $value)

Invokes $interceptor with ($value) and returns $value unchanged.

Note: Any changes made to $value in $interceptor will not be returned.

Parameter	Type	Description
$value	mixed
$interceptor	callable	Invoked with ($value)
Returns	mixed	Original $value

Example:

$result = _::chain([1, 3, 4])
	->filter('Dash\isOdd')
	->tap(function ($value) {
		// $value === [1, 3]
		print_r($value);
	})
	->value();

// $result === [1, 3]

↑ Top

thru

Operations › Utility

thru($value, callable $interceptor): mixed

# Curried: (all parameters required)
Curry\thru($interceptor, $value)

Invokes $interceptor with ($value) and returns its result.

Parameter	Type	Description
$value	mixed
$interceptor	callable	Invoked with ($value)
Returns	mixed	Return value of $interceptor($value)

Example:

$result = _::chain([1, 3, 4])
	->filter('Dash\isOdd')
	->thru(function ($value) {
		// $value === [1, 3]
		$value[] = $value[0];
		return $value;
	})
	->value();

// $result === [1, 3, 1]

↑ Top

Callable

apply

Operations › Callable

apply(callable $callable, $args): mixed

# Curried: (all parameters required)
Curry\apply($callable, $args)

Invokes $callable with a list of arguments.

Note: Contrary to other curried operations, the curried version of this operation accepts arguments in the same order as the original method.

Parameter	Type	Description
$callable	callable
$args	iterable|stdClass	Arguments to pass to $callable
Returns	mixed	Return value of $callable

Example:

$func = function ($time, $name) {
	return "Good $time, $name";
};

Dash\apply($func, ['morning', 'John']);
// === 'Good morning, John'

Example: Curried version accepts arguments in the same order

$func = function ($time, $name) {
	return "Good $time, $name";
};

$apply = Dash\Curry\apply($func);

$apply(['morning', 'John']);
// === 'Good morning, John'

↑ Top

ary

Operations › Callable

ary(callable $callable, $arity): callable

# Curried: (all parameters required)
Curry\ary($arity, $callable)

Creates a new function that invokes $callable with up to $arity arguments and ignores the rest.

Parameter	Type	Description
$callable	callable
$arity	integer	Maximum number of arguments to accept
Returns	callable	New function

Example:

$isNumeric = Dash\ary('is_numeric', 1);

Dash\filter([1, 2.0, '3', 'a'], $isNumeric);
// === [1, 2.0, '3']

↑ Top

call

Operations › Callable

call(callable $callable /*, ...args */): mixed

Invokes $callable with an inline list of arguments.

Parameter	Type	Description
$callable	callable
...$args	mixed	Inline arguments to pass to $callable
Returns	mixed	Return value of $callable

Example:

$func = function ($time, $name) {
	return "Good $time, $name";
};

Dash\call($func, 'morning', 'John');
// === 'Good morning, John'

↑ Top

currify

Operations › Callable

currify(callable $callable, array $args = [], $rotate = 1): function|mixed

Creates a new, curried version of $callable where the first $rotate arguments are moved to the end of the arguments list.

In essence, this takes a data-first function and returns a curryable data-last function.

Related: currifyN(), curry(), partial()

Parameter	Type	Description
$callable	callable
$args	array	(optional) Initial arguments to pass to the final curried function
$rotate	integer	(optional) The number of arguments to move from start to end; see Dash\rotate()
Returns	function|mixed

Example:

$greet = function ($name, $greeting, $punctuation) {
	return "$greeting, $name$punctuation";
};

$goodMorning = Dash\currify($greet, ['Good morning', '!']);
$goodMorning('John')
// === 'Good morning, John!'

Example: With a custom $rotate

$greet = function ($salutation, $name, $greeting, $punctuation) {
	return "$greeting, $salutation $name$punctuation";
};

$goodMorning = Dash\currify($greet, ['Good morning', '!'], 2);
$goodMorning('Sir', 'John')
// === 'Good morning, Sir John!'

↑ Top

currifyN

Operations › Callable

currifyN(callable $callable, $totalArgs, array $args = [], $rotate = 1): function|mixed

Creates a new, curried version of $callable where the first $rotate of $totalArgs arguments are moved to the end of the arguments list.

In essence, this takes a data-first function and returns a curryable data-last function.

Related: currify(), curry(), partial()

Parameter	Type	Description
$callable	callable
$totalArgs	integer	Total number of arguments accepted by $callable
$args	array	(optional) Initial arguments to pass to the final curried function
$rotate	integer	(optional) The number of arguments to move from start to end; see Dash\rotate()
Returns	function|mixed

↑ Top

curry

Operations › Callable

curry(callable $callable /*, ...args */): function|mixed

Creates a new function that returns the result of $callable if its required number of parameters are supplied; otherwise, it returns a function that accepts the remaining number of required parameters.

Use Dash\_ as a placeholder to replace with arguments from subsequent calls.

Related: curryN(), curryRight(), partial(), currify()

Parameter	Type	Description
$callable	callable	Any valid callable except for relative static methods, eg. ['A', 'parent::foo']
...$args	mixed	(optional, variadic) arguments to pass to $callable
Returns	function|mixed

Example:

$greet = function ($greeting, $salutation, $name) {
	return "$greeting, $salutation $name";
};

$goodMorning = Dash\curry($greet, 'Good morning');
$goodMorning('Ms.', 'Mary');
// === 'Good morning, Ms. Mary'

$goodMorning = Dash\curry($greet, 'Good morning');
$goodMorningSir = $goodMorning('Sir');
$goodMorningSir('Peter');
// === 'Good morning, Sir Peter'

Example: With placeholders

$greet = function ($greeting, $salutation, $name) {
	return "$greeting, $salutation $name";
};

$greetMary = Dash\curry($greet, Dash\_, 'Ms.', 'Mary');
$greetMary('Good morning');
// === 'Good morning, Ms. Mary'

$greetSir = Dash\curry($greet, Dash\_, 'Sir');
$goodMorningSir = $greetSir('Good morning');
$goodMorningSir('Peter');
// === 'Good morning, Sir Peter'

↑ Top

curryN

Operations › Callable

curryN(callable $callable, $numRequiredArgs /*, ...args */): function|mixed

Creates a new function that returns the result of $callable if the required number of parameters are supplied; otherwise, it returns a function that accepts the remaining number of required parameters.

Use Dash\_ as a placeholder to replace with arguments from subsequent calls.

Related: curry()

Parameter	Type	Description
$callable	callable
$numRequiredArgs	integer	The number of parameters to require before calling $callable
...$args	mixed	(optional, variadic) arguments to pass to $callable
Returns	function|mixed

Example:

$greet = function ($greeting, $salutation, $name, $punctuation = '!') {
	return "$greeting, $salutation $name$punctuation";
};

$goodMorning = Dash\curryN($greet, 3, 'Good morning');
$goodMorning('Ms.', 'Mary');
// === 'Good morning, Ms. Mary!'

$goodMorning = Dash\curryN($greet, 3, 'Good morning');
$goodMorningSir = $goodMorning('Sir');
$goodMorningSir('Peter');
// === 'Good morning, Sir Peter!'

Example: With placeholders

$greet = function ($greeting, $salutation, $name, $punctuation = '!') {
	return "$greeting, $salutation $name$punctuation";
};

$greetSir = Dash\curryN($greet, 3, Dash\_, 'Sir');
$goodMorningSir = $greetSir('Good morning');
$goodMorningSir('Peter');
// === 'Good morning, Sir Peter!'

$greetMary = Dash\curryN($greet, 3, Dash\_, Dash\_, 'Mary');
$greetMsMary = $greetMary(Dash\_, 'Ms.');
$greetMsMary('Good morning');
// === 'Good morning, Ms. Mary!'

↑ Top

curryRight

Operations › Callable

curryRight(callable $callable /*, ...args */): function|mixed

Creates a new function that returns the result of $callable if its required number of parameters are supplied; otherwise, it returns a function that accepts the remaining number of required parameters.

Like partialRight(), arguments are applied in reverse order.

Use Dash\_ as a placeholder to replace with arguments from subsequent calls.

Related: curry(), partial()

Parameter	Type	Description
$callable	callable
...$args	mixed	(optional, variadic) arguments to pass to $callable
Returns	function|mixed

Example:

$greet = function ($greeting, $salutation, $name) {
	return "$greeting, $salutation $name";
};

$goodMorning = Dash\curryRight($greet, 'Good morning');
$goodMorning('Ms.', 'Mary');
// === 'Good morning, Ms. Mary'

$goodMorning = Dash\curryRight($greet, 'Good morning');
$goodMorningSir = $goodMorning('Sir');
$goodMorningSir('Peter');
// === 'Good morning, Sir Peter'

Example: With placeholders

$greet = function ($greeting, $salutation, $name) {
	return "$greeting, $salutation $name";
};

$greetMary = Dash\curryRight($greet, Dash\_, 'Ms.', 'Mary');
$greetMary('Good morning');
// === 'Good morning, Ms. Mary'

$greetSir = Dash\curryRight($greet, Dash\_, 'Sir');
$goodMorningSir = $greetSir('Good morning');
$goodMorningSir('Peter');
// === 'Good morning, Sir Peter'

↑ Top

curryRightN

Operations › Callable

curryRightN(callable $callable, $numRequiredArgs /*, ...args */): function|mixed

Creates a new function that returns the result of $callable if the required number of parameters are supplied; otherwise, it returns a function that accepts the remaining number of required parameters.

Like partialRight(), arguments are applied in reverse order.

Use Dash\_ as a placeholder to replace with arguments from subsequent calls.

Related: curryN(), partialRight()

Parameter	Type	Description
$callable	callable
$numRequiredArgs	integer	The number of parameters to require before calling $callable
...$args	mixed	(optional, variadic) arguments to pass to $callable
Returns	function|mixed

Example:

$greet = function ($greeting, $salutation, $name, $punctuation = '!') {
	return "$greeting, $salutation $name$punctuation";
};

$greetMary = Dash\curryRightN($greet, 3, 'Mary');
$greetMsMary = $greetMary('Ms.');
$greetMsMary('Good morning');
// === 'Good morning, Ms. Mary!

$greetPeter = Dash\curryRightN($greet, 3, 'Peter');
$greetSirPeter = $greetPeter('Sir');
$greetSirPeter('Good morning');
// === 'Good morning, Sir Peter!

Example: With placeholders

$greet = function ($greeting, $salutation, $name, $punctuation = '!') {
	return "$greeting, $salutation $name$punctuation";
};

$goodMorning = Dash\curryRightN($greet, 3, 'Good morning', Dash\_, Dash\_);
$goodMorningSir = $goodMorning('Sir', Dash\_);
$goodMorningSir('Peter');
// === 'Good morning, Sir Peter!

$greetMs = Dash\curryRightN($greet, 3, 'Ms.', Dash\_);
$goodMorningMs = $greetMs('Good morning', Dash\_);
$goodMorningMs('Mary');
// === 'Good morning, Ms. Mary!

↑ Top

negate

Operations › Callable

negate(callable $predicate): callable

# Curried: (all parameters required)
Curry\negate($predicate)

Creates a new function that negates the return value of $predicate.

Parameter	Type	Description
$predicate	callable
Returns	callable	New function

Example:

$isEven = function ($n) { return $n % 2 === 0; };
$isOdd = Dash\negate($isEven);

$isEven(3);  // === false
$isOdd(3);   // === true

↑ Top

partial

Operations › Callable

partial($callable /*, ...args */): callable

Creates a new function that will invoke $callable with the given arguments and any others passed to the returned function.

When calling $callable, arguments provided to partial() will be listed BEFORE those passed to the returned function.

Use Dash\_ as a placeholder to replace with arguments passed to the returned function.

Related: partialRight(), curry()

Parameter	Type	Description
$callable	callable
...$args	mixed	(optional, variadic) arguments to pass to $callable
Returns	callable

Example:

$greet = function ($greeting, $name) {
	return "$greeting, $name!";
};

$sayHello = Dash\partial($greet, 'Hello');
$sayHowdy = Dash\partial($greet, 'Howdy');

$sayHello('Mark');  // === 'Hello, Mark!'
$sayHowdy('Jane');  // === 'Howdy, Jane!'

Example: With placeholders

$greet = function ($greeting, $name) {
	return "$greeting, $name!";
};

$greetMark = Dash\partial($greet, Dash\_, 'Mark');
$greetJane = Dash\partial($greet, Dash\_, 'Jane');

$greetMark('Hello');  // === 'Hello, Mark!'
$greetJane('Howdy');  // === 'Howdy, Jane!'

↑ Top

partialRight

Operations › Callable

partialRight($callable /*, ...args */): callable

Creates a new function that will invoke $callable with the given arguments and any others passed to the returned function.

When calling $callable, arguments provided to partial() will be listed AFTER those passed to the returned function.

Use Dash\_ as a placeholder to replace with arguments passed to the returned function.

Related: partial(), curryRight()

Parameter	Type	Description
$callable	callable
...$args	mixed	(optional, variadic) arguments to pass to $callable
Returns	callable

Example:

$greet = function ($greeting, $name) {
	return "$greeting, $name!";
};

$greetMark = Dash\partialRight($greet, 'Mark');
$greetJane = Dash\partialRight($greet, 'Jane');

$greetMark('Hello');  // === 'Hello, Mark!'
$greetJane('Howdy');  // === 'Howdy, Jane!'

Example: With a placeholder

$greet = function ($greeting, $name) {
	return "$greeting, $name!";
};

$sayHello = Dash\partialRight($greet, 'Hello', Dash\_);
$sayHowdy = Dash\partialRight($greet, 'Howdy', Dash\_);

$sayHello('Mark');  // === 'Hello, Mark!'
$sayHowdy('Jane');  // === 'Howdy, Jane!'

↑ Top

unary

Operations › Callable

unary(callable $callable): callable

# Curried: (all parameters required)
Curry\unary($callable)

Creates a new function that invokes $callable with a single argument and ignores the rest.

Parameter	Type	Description
$callable	callable
Returns	callable	New function

Example:

$isNumeric = Dash\unary('is_numeric');

Dash\filter([1, 2.0, '3', 'a'], $isNumeric);
// === [1, 2.0, '3']

↑ Top

Number

isEven

Operations › Number

isEven($value): boolean

# Curried: (all parameters required)
Curry\isEven($value)

Checks whether $value is an even number.

If a double is provided, only its truncated integer component is evaluated.

Parameter	Type	Description
$value	numeric
Returns	boolean	True if $value is an even number, false otherwise

Example:

Dash\isEven(3);
// === false

Dash\isEven(4);
// === true

Dash\isEven(4.9);
// === true

Dash\isEven('a');
// === false

↑ Top

isOdd

Operations › Number

isOdd($value): boolean

# Curried: (all parameters required)
Curry\isOdd($value)

Checks whether $value is an odd number.

If a double is provided, only its truncated integer component is evaluated.

Parameter	Type	Description
$value	numeric
Returns	boolean	True if $value is an odd number, false otherwise

Example:

Dash\isOdd(3);
// === true

Dash\isOdd(4);
// === false

Dash\isOdd(5.9);
// === true

Dash\isOdd('a');
// === false

↑ Top