txt: ## map.md
  map
  
  Combined from primary sources listed below.
  
  # [In List](#___top "go to top of document")[§](#(List)_routine_map "direct link")
  
  See primary documentation
  [in context](/type/List#routine_map)
  for **routine map**.
  
  ```raku
  multi method map(\SELF: &block)
  multi        map(&code, +values)
  ```
  
  Examples applied to lists are included here for the purpose of illustration.
  
  For a list, it invokes `&code` for each element and gathers the return values in a sequence and returns it. This happens lazily, i.e. `&code` is only invoked when the return values are accessed.Examples:
  
  ```raku
  say ('hello', 1, 22/7, 42, 'world').map: { .^name } # OUTPUT: «(Str Int Rat Int Str)␤»
  say map *.Str.chars, 'hello', 1, 22/7, 42, 'world'; # OUTPUT: «(5 1 8 2 5)␤»
  
  ```
  
  `map` inspects the arity of the code object, and tries to pass as many arguments to it as expected:
  
  ```raku
  sub b($a, $b) { "$a before $b" };
  say <a b x y>.map(&b).join(', ');   # OUTPUT: «a before b, x before y␤»
  ```
  
  iterates the list two items at a time.
  
  Note that `map` does not flatten embedded lists and arrays, so
  
  ```raku
  ((1, 2), <a b>).map({ .join(',')})
  ```
  
  passes `(1, 2)` and `<a b>` in turn to the block, leading to a total of two iterations and the result sequence `"1,2", "a,b"`.
  
  If `&code` is a [`Block`](/type/Block) loop phasers will be executed and loop control statements will be treated as in loop control flow. Please note that `return` is executed in the context of its definition. It is not the return statement of the block but the surrounding Routine. Using a [`Routine`](/type/Routine) will also handle loop control statements and loop phasers. Any [`Routine`](/type/Routine) specific control statement or phaser will be handled in the context of that [`Routine`](/type/Routine).
  
  ```raku
  sub s {
      my &loop-block = {
          return # return from sub s
      };
      say 'hi';
      (1..3).map: &loop-block;
      say 'oi‽' # dead code
  };
  s
  # OUTPUT: «hi␤»
  ```
  
  # [In Any](#___top "go to top of document")[§](#(Any)_routine_map "direct link")
  
  See primary documentation
  [in context](/type/Any#routine_map)
  for **routine map**.
  
  ```raku
  multi method map(\SELF: &block)
  multi        map(&code, +values)
  ```
  
  `map` will iterate over the invocant and apply the number of positional parameters of the code object from the invocant per call. The returned values of the code object will become elements of the returned [`Seq`](/type/Seq).
  
  The `:$label` and `:$item` are useful only internally, since `for` loops get converted to `map`s. The `:$label` takes an existing [`Label`](/type/Label) to label the `.map`'s loop with and `:$item` controls whether the iteration will occur over `(SELF,)` (if `:$item` is set) or `SELF`.
  
  In `sub` form, it will apply the `code` block to the `values`, which will be used as invocant.
  
  The forms with `|c`, `Iterable:D \iterable` and `Hash:D \hash` as signatures will fail with `X::Cannot::Map`, and are mainly meant to catch common traps.
  
  Inside a `for` statement that has been sunk, a [`Seq`](/type/Seq) created by a map will also sink:
  
  ```raku
  say gather for 1 {
      ^3 .map: *.take;
  } # OUTPUT: «(0 1 2)␤»
  
  ```
  
  In this case, `gather` sinks the `for` statement, and the result of sinking the [`Seq`](/type/Seq) will be iterating over its elements, calling `.take` on them.
  
  # [In HyperSeq](#___top "go to top of document")[§](#(HyperSeq)_method_map "direct link")
  
  See primary documentation
  [in context](/type/HyperSeq#method_map)
  for **method map**.
  
  ```raku
  method map(HyperSeq:D: $matcher, *%options)
  ```
  
  Uses maps on the `HyperSeq`, generally created by application of `hyper` to a preexisting [`Seq`](/type/Seq).
  
  # [In RaceSeq](#___top "go to top of document")[§](#(RaceSeq)_method_map "direct link")
  
  See primary documentation
  [in context](/type/RaceSeq#method_map)
  for **method map**.
  
  ```raku
  method map(RaceSeq:D: $matcher, *%options)
  ```
  
  Uses maps on the `RaceSeq`, generally created by application of `.race` to a preexisting [`Seq`](/type/Seq).
  
  # [In Backtrace](#___top "go to top of document")[§](#(Backtrace)_method_map "direct link")
  
  See primary documentation
  [in context](/type/Backtrace#method_map)
  for **method map**.
  
  ```raku
  multi method map(Backtrace:D: &block --> Seq:D)
  ```
  
  It invokes `&block` for each element and gathers the return values in a sequence and returns it.
  
  This program:
  
  ```raku
  sub inner { Backtrace.new.map({ say "{$_.file}: {$_.line}" }); }
  sub outer { inner; }
  outer;
  ```
  
  results in:
  
  ｢text｣ without highlighting
  
  ```
  
  
  ```
  
  SETTING::src/core.c/Backtrace.rakumod: 85
  SETTING::src/core.c/Backtrace.rakumod: 85
  test.raku: 1
  test.raku: 2
  test.raku: 3
  test.raku: 1
  
  
  ```
  
  
  ```
  
  # [In Supply](#___top "go to top of document")[§](#(Supply)_method_map "direct link")
  
  See primary documentation
  [in context](/type/Supply#method_map)
  for **method map**.
  
  ```raku
  method map(Supply:D: &mapper --> Supply:D)
  ```
  
  Returns a new supply that maps each value of the given supply through `&mapper` and emits it to the new supply.
  
  ```raku
  my $supplier = Supplier.new;
  my $all      = $supplier.Supply;
  my $double   = $all.map(-> $value { $value * 2 });
  $double.tap(&say);
  $supplier.emit(4);           # OUTPUT: «8»
  ```
  