original_string: 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);
          }
      }
code: 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);
          }
      }
code_tokens: 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 ) ; } }
docstring: 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
docstring_tokens: Flexibly and thoroughly change this map into another map .