src/Map.php
public function transform(callable $transformer, callable $creator = null, callable $finisher = null)
    {
        // create the initial object, using as needed the default creator function
        if (null === $creator) {
            $creator = function (Map $original) { return new Map(); };
        }
        $initial = $creator($this);

        // transform the initial value using the transformer
        $this->walk(function ($value, $key) use ($transformer, &$initial) {
            $transformer($initial, $value, $key);
        });

        // finish up
        if (null === $finisher) {
            return $initial;
        } else {
            return $finisher($initial);
        }
    }
public function transform(callable $transformer, callable $creator = null, callable $finisher = null)
    {
        // create the initial object, using as needed the default creator function
        if (null === $creator) {
            $creator = function (Map $original) { return new Map(); };
        }
        $initial = $creator($this);

        // transform the initial value using the transformer
        $this->walk(function ($value, $key) use ($transformer, &$initial) {
            $transformer($initial, $value, $key);
        });

        // finish up
        if (null === $finisher) {
            return $initial;
        } else {
            return $finisher($initial);
        }
    }
public function transform ( callable $ transformer , callable $ creator = null , callable $ finisher = null ) { // create the initial object, using as needed the default creator function if ( null === $ creator ) { $ creator = function ( Map $ original ) { return new Map ( ) ; } ; } $ initial = $ creator ( $ this ) ; // transform the initial value using the transformer $ this -> walk ( function ( $ value , $ key ) use ( $ transformer , & $ initial ) { $ transformer ( $ initial , $ value , $ key ) ; } ) ; // finish up if ( null === $ finisher ) { return $ initial ; } else { return $ finisher ( $ initial ) ; } }
Flexibly and thoroughly change this map into another map.

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

@param callable $tranformer
@param callable|null $creator
@param callable|null $finisher
@return mixed
@api
Flexibly and thoroughly change this map into another map .