Functionals

Functionals is a simple library that provides a set of functionals written in php.

What do you mean with "functionals"?

Here I use the term "functional" to denote Higher-Order functions, i.e. functions that take other functions as input and return a function as output.

Install

The best way to install Functionals is through composer.

Just create a composer.json file for your project:

{
    "require": {
        "nicmart/functionals": "dev-master"
    }
}

Then you can run these two commands to install it:

$ curl -s http://getcomposer.org/installer | php
$ php composer.phar install

or simply run composer install if you have have already installed the composer globally.

Then you can include the autoloader, and you will have access to the library classes:

<?php
require 'vendor/autoload.php';

use Functionals\Functionals;

Usage

Composition of functions

If you have two functions f : A → B and g: B → C their composition is a function h: A → C that maps x to f(g(x)).

In Functionals you can compose an arbitrary number of php callables through Functionals::compose():

$sum = function($a, $b) { return $a + $b; };
$half = function($n) { return $n/2; };

$middle = Functionals::compose($half, $sum);

echo $middle(10, 16); //Prints 13
echo $middle(-10, 10); //Prints 0

You can compose an arbitrary long list of functions, and they can be any callable:

$beautifyString = Functionals::compose(
    function($s){ return str_replace('bad', 'good', $s); },
    'ucfirst',
    'strtolower',
    'trim'
);

echo $beautifyString('   i\'m a reAlly Bad writTen STRING');
//prints "I'm a really good written string"

Partial

A partial application of a function in several variables is obtained by fixing some arguments of the function and get a function of the remaining arguments.

For example, if you have a function f : X x Y → B, and you fix a x in X, then you get the partial function g: Y → B that maps y to f(x,y).

In Functionals you can obtain a partial function application with the method Functionals::partial():

$sum = function($a, $b) { return $a + $b; };
$next = Functionals::partial($sum, array(1));

$next(2);  // 3
$next(10); // 11

You can fix arguments in any position, specifying the right index for the fixed arguments array:

$if = function($condition, $ifTrue, $ifFalse) { return $condition ? $ifTrue : $ifFalse; };

$boolDump = Functionals::partial($if, array( 1 => 'TRUE!', 2 => 'FALSE!'))

$boolDump(true);  // TRUE!
$boolDump(false); // FALSE!

Currying and uncurrying

To get a curried version of a function in several variables, use the Functionals::curry method:

$sum = function($a, $b, $c) { return $a + $b + $c; };
$a = Functionals::curry($sum);
$b = $a(1);
$c = $b(2);

$c(10);  // 13
$c(101); // 104

You can also uncurry a function. This time you have to specify the number of the original function arguments:

$uncurried = Functionals::uncurry($a, 3);

$uncurried(5, 7, 11);    //23

Combine and uncombine

Given a set of functions f, g, h, ... that act on the same domain, a combined version of that functions is the function

x → array(f(x), g(x), h(x), ...)

In Functionals you can easily combine callables with Functionals::combine:

$stringVersions = Functionals::combine('strtolower', 'strtoupper', 'ucfirst');

$stringVersions('hElLo'); // array('hello', 'HELLO', 'HElLo')

Conversely, you can uncombine a function that returns array values. In this case you have to specify the number of items in the array values:

$ops = function($a, $b) { return array($a + $b, $a * $b, $a - $b); };

list($sum, $multiplication, $difference) = Functionals::uncombine($ops, 3);

$sum(10, 5);            // 15
$multiplication(10, 5); // 50
$difference(10, 5);     // 5

Args to array and array to args

You can convert a function that accept several arguments to a function that accept a single array argument through the functional Functionals::args_to_array().

For example, if you have the function in two variables f(x, y) with this functional you obtain the function (in pseudo-code)

 Functionals::args_to_array(f) : array(x, y) → f(x, y)

In php:

$sum = function($a, $b) { return $a + $b; };
$sum2 = Functionals::args_to_array($sum);

$sum2(array(2, 10)); // 12

This functional can be useful in conjunction with composition, since the functions in a composition chain that are not in the last position can recieve only one argument:

$sum = function() { return array_sum(func_get_args()); };
$numbersUntil = function($n) {
    $numbers = array();
    for ($i = 0; $i <= $n; $i++)
        $numbers[] = $i;
    return $numbers;
};

$sumUntil = Functionals::compose(
    Functionals::args_to_array($sum),
    $numbersUntil
);

$sumUntil(1); // 1
$sumUntil(5); // 15
$sumUntil(100); // 5050 (=100 + 101 / 2)

The inverse of the previous functional is Functionals::array_to_args():

$sum = function(array $numbers) { return array_sum($numbers); };

$sum2 = Functionals::array_to_args($sum);

$sum2(1, 2, 3); //6
$sum2(10, 20, 3); //33

TODO

Some security checks on inputs and array sizes
Performance considerations
Give more useful/amusing examples?
Automatically detect end of chain for uncurrying

Tests

$ phpunit

License

MIT, see LICENSE.

jusheehy/Functionals