// 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.