README

A variety of utility functions for common programming needs.

Installation

The best way to install and use this package is with composer:

composer require dryist/functions

Usage

There are several categories of functions:

• algebra - some common functional language utilities
• array - helpers to work with arrays and iterators
• tool - other various tools

All functions have a constant that refers the fully qualified function name. These constants can be used for composed or piped operations.

There are a number of other packages that provide compatible (and/or similar) utility functions, including:

• https://github.com/ihor/Nspl
• https://github.com/krakphp/fn
• https://github.com/lstrojny/functional-php

Any functionality missing in this package can probably be found elsewhere.

Alegbra

always()

Creates a "K combinator" that always returns the original value:

use function Dryist\always;

$fn = always(true);

assert($fn() === true);

compose()

Creates a "substitution combinator" that composes two callables:

use function Dryist\compose;

$fn = compose('ucwords', 'strtolower');

assert($fn('SALLY SMITH') === 'Sally Smith');

identity()

Always returns the first input:

use function Dryist\identity;

assert(identity('foo') === 'foo');

This function is also aliased as Dryist\id.

invert()

Creates an inverted predicate:

use function Dryist\invert;

$notNull = invert('is_null');

assert($notNull(42) === true);
assert($notNull(null) === true);

Array

All of the array functions accept iterable variables, including arrays, iterators, and generators.

count()

Count the number of items in a list or map:

use function Dryist\count;

$items = [1, 2, 3];

assert(count($items) === 3);

combine()

Combines two lists to create a map:

use function Dryist\combine;
use function Dryist\resolve;

$keys = ['city', 'country'];
$values = ['London', 'England'];
$map = combine($keys, $values);

assert(resolve($map) === ['city' => 'London', 'country' => 'England']);

filter()

Filter a list or map by a predicate of the value:

use function Dryist\filter;
use function Dryist\resolve;
use function Dryist\values;

$positive = function (int $value): bool {
    return $value > 0;
};

$list = [-100, 0, 100];
$list = filter($list, $positive);

// Drop keys
$list = values($list);

assert(resolve($list) === [100]);

filterKey()

Filter a list or map by a predicate of the key:

use function Dryist\filterKey;
use function Dryist\resolve;
use function Dryist\values;

$even = function (int $value): bool {
    return $value % 2 === 0;
};

$map = [13 => 'a', 16 => 'b', 22 => 'c'];
$map = filterKey($map, $even);

// Drop keys
$list = values($map);

assert(resolve($list) === ['b', 'c']);

Related functions:

• take

keys()

Read the keys from a map into a list:

use function Dryist\keys;
use function Dryist\resolve;

$map = ['name' => 'Jane', 'friends' => 42];
$keys = keys($map);

assert(resolve($keys) === ['name', 'friends']);

map()

Apply a value modifier to a list or map:

use function Dryist\map;
use function Dryist\resolve;

$list = ['foo', 'bar', 'baz'];
$list = map($list, 'strtoupper');

assert(resolve($list) === ['FOO', 'BAR', 'BAZ']);

mapBoth()

Apply a value modifier to a list or map:

use function Dryist\mapBoth;
use function Dryist\resolve;

$list = ['foo', 'bar', 'baz'];
$list = mapBoth($list, function ($key, $value) {
    if ($key % 2 === 0) {
        return strtoupper($value);
    }
    return $value;
});

assert(resolve($list) === ['FOO', 'bar', 'BAZ']);

This differs from map() in that the modifier receives both the key and the value.

mapKey()

Apply a key modifier to a list or map:

use function Dryist\mapKey;
use function Dryist\resolve;

$map = ['NAME' => 'Bob', 'GAME' => 'football'];
$map = mapKey($map, 'strtolower');

assert(resolve($map) === ['name' => 'Bob', 'game' => 'football'])

resolve()

An alias for iterator_to_array.

take()

Take some values from a map by a list of keys:

use function Dryist\resolve;
use function Dryist\take;

$map = ['name' => 'Cassie', 'friends' => 152, 'age' => 39];
$map = take($map, ['name']);

assert(resolve($map) === ['name' => 'Cassie']);

values()

Read the values of a map into a list:

use function Dryist\values;
use function Dryist\resolve;

$map = ['a' => 1, 'b' => 2, 'c' => 3];
$list = values($map);

assert(resolve($list) === [1, 2, 3]);

Tool

make()

Create a modifier that constructs an object.

use function Dryist\make;
use function Dryist\map;
use function Dryist\resolve;

$list = [[1, 2, 3], [4, 5], [6]];
$list = map($list, make(ArrayIterator::class));

assert(resolve($list)[0] instanceof ArrayIterator);

stringify()

Convert a value to a string, unless it is null.

use function Dryist\stringify;

assert(stringify(null) === null);
assert(stringify(42) === "42");