Documentation for routine map assembled from the following pages:

Class: Any §

From Any

(Any) routine map §

Defined as:

multi method map(\SELF: █; :$label, :$item)
multi sub map(&code, +values)
multi method map(Hash:D \hash)
multi method map(Iterable:D \iterable)
multi method map(|c)

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.

The :$label and :$item are useful only internally, since for loops get converted to maps. The :$label takes an existing 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 created by a map will also sink:

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 will be iterating over its elements, calling .take on them.

Class: Supply §

From Supply

(Supply) method map §

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.

my $supplier = Supplier.new;
my $all      = $supplier.Supply;
my $double   = $all.map(-> $value { $value * 2 });
$double.tap(&say);
$supplier.emit(4);           # OUTPUT: «8»

Class: List §

From List

(List) routine map §

Defined as:

multi method map(Hash:D \hash)
multi method map(Iterable:D \iterable)
multi method map(|c)
multi method map(\SELF: █; :$label, :$item)
multi sub 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:

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:

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

((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". See method flatmap for an alternative that flattens.

If &code is a 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 will also handle loop control statements and loop phasers. Any Routine specific control statement or phaser will be handled in the context of that Routine.

sub s {
    my &loop-block = {
        return # return from sub s 
    };
    say 'hi';
    (1..3).map: &loop-block;
    say 'oi‽' # dead code 
};
s 
# OUTPUT: «hi␤»

Class: Backtrace §

From Backtrace

(Backtrace) method map §

Defined as:

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:

sub inner { Backtrace.new.map({ say "{$_.file}: {$_.line}" }); }
sub outer { inner; }
outer;

results in:

SETTING::src/core.c/Backtrace.pm6: 85
SETTING::src/core.c/Backtrace.pm6: 85
test.p6: 1
test.p6: 2
test.p6: 3
test.p6: 1

Class: HyperSeq §

From HyperSeq

(HyperSeq) method map §

method map(HyperSeq:D: $matcher, *%options)

Uses maps on the HyperSeq, generally created by application of hyper to a preexisting Seq.

Class: RaceSeq §

From RaceSeq

(RaceSeq) method map §

method map(RaceSeq:D: $matcher, *%options)

Uses maps on the RaceSeq, generally created by application of .race to a preexisting Seq.