Rules / Types, classes & roles / composite

Map Reference

Immutable mapping from strings to values

What it is #

Position in the hierarchy #

Inherits from—
Does—
Inherited byPseudoStash, Hash

Routines #

Signatures are reproduced from the documentation, including their declared return types. A routine listed here is part of the type's published interface; whether Raku++ implements it is a separate question, answered by the examples below.

method new #

method new(*@args)

Creates a new Map from a list of alternating keys and values, with the same semantics as described in the Hashes and maps documentation, but also accepts Pairs instead of separate keys and values. Use the grouping operator or quote the key to ensure that a literal pair is not interpreted as a named argument.

method elems #

method elems(Map:D: --> Int:D)

Returns Int:D.

Returns the number of pairs stored in the Map.

method ACCEPTS #

multi method ACCEPTS(Map:D: Positional $topic)
multi method ACCEPTS(Map:D: Cool:D     $topic)
multi method ACCEPTS(Map:D: Regex      $topic)
multi method ACCEPTS(Map:D: Any        $topic)

Used in smartmatching if the right-hand side is a Map. If the topic is list-like (Positional), returns True if any of the list elements exist as a key in the Map. If the topic is of type Cool (strings, integers etc.), returns True if the topic exists as a key. If the topic is a regex, returns True if any of the keys match the regex. As a fallback, the topic is coerced to a list, and the Positional

method gist #

method gist(Map:D: --> Str:D)

Returns Str:D.

Returns the string containing the "gist" of the Map, sorts the pairs and lists up to the first 100, appending an ellipsis if the Map has more than 100 pairs.

method keys #

method keys(Map:D: --> Seq:D)

Returns Seq:D.

Returns a Seq of all keys in the Map.

method values #

method values(Map:D: --> Seq:D)

Returns Seq:D.

Returns a Seq of all values in the Map.

method pairs #

method pairs(Map:D: --> Seq:D)

Returns Seq:D.

Returns a Seq of all pairs in the Map.

method antipairs #

method antipairs(Map:D: --> Seq:D)

Returns Seq:D.

Returns all keys and their respective values as a Seq of Pairs where the keys and values have been exchanged, i.e. the opposite of method pairs. Unlike the invert method, there is no attempt to expand list values into multiple pairs.

method invert #

method invert(Map:D: --> Seq:D)

Returns Seq:D.

Returns all keys and their respective values as a Seq of Pairs where the keys and values have been exchanged. The difference between invert and antipairs is that invert expands list values into multiple pairs.

method kv #

method kv(Map:D: --> Seq:D)

Returns Seq:D.

Returns a Seq of keys and values interleaved.

method list #

multi method list(Map:D: --> List:D)

Returns List:D.

Returns a List of Pair objects of all keys and values in the Map.

method sort #

multi method sort(Map:D: --> Seq:D)

Returns Seq:D.

Returns a Seq of Pair objects, which are the pairs of the hash, sorted by key. Equivalent to %hash.sort: *.key See Any.sort for additional available candidates.

method Int #

method Int(Map:D: --> Int:D)

Returns Int:D.

Returns the number of pairs stored in the Map (same as .elems).

method Numeric #

method Numeric(Map:D: --> Int:D)

Returns Int:D.

Returns the number of pairs stored in the Map (same as .elems).

method Bool #

method Bool(Map:D: --> Bool:D)

Returns Bool:D.

Returns True if the invocant contains at least one key/value pair.

method Capture #

method Capture(Map:D:)

Returns a Capture where each key, if any, has been converted to a named argument with the same value as it had in the original Map. The returned Capture will not contain any positional arguments.

Examples, run three ways #

Every example below comes from the official documentation, together with the output that documentation asserts. Each was then executed by Rakudo and by Raku++ when this page was built. Where the three agree, one result is shown; where they do not, all three are — because which of them is wrong is exactly the information worth having.

1 doc-drift · 8 no-output · 1 not-runnable · 13 ok · 1 rakupp-differs

class Map does Associative does Iterable { }

Not executed: the documentation states no expected output for this example.

my %e := Map.new('a', 1, 'b', 2);
say %e.keys;    # can print «a b␤» or «b a␤»
say %e.values;  # prints «1 2␤» if the previous line
                # printed «a b␤», «2 1␤» otherwise

Not executed: the documentation states no expected output for this example.

my %map is Map = 'a', 1, 'b', 2;
say %map{'a'};      # OUTPUT: «1␤»
say %map{ 'a', 'b' }; # OUTPUT: «(1 2)␤»
Output
1
(1 2)

Documentation, Rakudo and Raku++ all agree.

my $map = Map.new('a', 1, 'b', 2);
my $key = 'a';
if $map{$key}:exists {
    say "$map{} has key $key";
}

Not executed: the documentation states no expected output for this example.

                  # Cannot modify an immutable Str

Not executed: the documentation states no expected output for this example.

my %h = Map.new('a', 1, 'b', 2);

Not executed: the documentation states no expected output for this example.

# WRONG: :b(2) interpreted as named argument
say Map.new('a', 1, :b(2)).keys; # OUTPUT: «(a)␤»
Documentation
(a)
Rakudo
(a)
Raku++
(a b)

Raku++ disagrees with both the documentation and Rakudo — a defect.

# RIGHT: :b(2) interpreted as Pair because of extra parentheses
say Map.new( ('a', 1, :b(2)) ).keys.sort; # OUTPUT: «(a b)␤»
Output
(a b)

Documentation, Rakudo and Raku++ all agree.

# RIGHT: 'b' => 2 always creates a Pair
say Map.new('a', 1, 'b' => 2).keys.sort; # OUTPUT: «(a b)␤»
Output
(a b)

Documentation, Rakudo and Raku++ all agree.

my %h is Map = 'a', 1, 'b', 2;

Not executed: the documentation states no expected output for this example.

my %map = Map.new('a', 1, 'b', 2);
say %map.elems; # OUTPUT: «2␤»
Output
2

Documentation, Rakudo and Raku++ all agree.

my $m = Map.new('a' => (2, 3), 'b' => 17);
say $m.keys; # OUTPUT: «(a b)␤»
Output
(a b)

Documentation, Rakudo and Raku++ all agree.

my $m = Map.new('a' => (2, 3), 'b' => 17);
say $m.values; # OUTPUT: «((2 3) 17)␤»
Output
((2 3) 17)

Documentation, Rakudo and Raku++ all agree.

my $m = Map.new('a' => (2, 3), 'b' => 17);
say $m.pairs; # OUTPUT: «(a => (2 3) b => 17)␤»
Output
(a => (2 3) b => 17)

Documentation, Rakudo and Raku++ all agree.

my $m = Map.new('a' => (2, 3), 'b' => 17);
say $m.antipairs;                        # OUTPUT: «((2 3) => a 17 => b)␤»
Output
((2 3) => a 17 => b)

Documentation, Rakudo and Raku++ all agree.

my $m = Map.new('a' => (2, 3), 'b' => 17);
say $m.invert;                          # OUTPUT: «(2 => a 3 => a 17 => b)␤»
Output
(2 => a 3 => a 17 => b)

Documentation, Rakudo and Raku++ all agree.

Map.new('a', 1, 'b', 2).kv  # (a 1 b 2)

Not executed: the documentation states no expected output for this example.

my $m = Map.new('a' => (2, 3), 'b' => 17);
say $m.list;                            # OUTPUT: «(b => 17 a => (2 3))␤»
Documentation
(b => 17 a => (2 3))
Rakudo
(a => (2 3) b => 17)
Raku++
(a => (2 3) b => 17)

Both engines agree; the documentation states something else. Trust the engines.

# These are equivalent:
say Map.new(<c 3 a 1 b 2>).sort;        # OUTPUT: «(a => 1 b => 2 c => 3)␤»
say Map.new(<c 3 a 1 b 2>).sort: *.key; # OUTPUT: «(a => 1 b => 2 c => 3)␤»
Output
(a => 1 b => 2 c => 3)
(a => 1 b => 2 c => 3)

Documentation, Rakudo and Raku++ all agree.

my $m = Map.new('a' => 2, 'b' => 17);
say $m.Int;                                       # OUTPUT: «2␤»
Output
2

Documentation, Rakudo and Raku++ all agree.

my $m = Map.new('a' => 2, 'b' => 17);
say $m.Numeric;                                   # OUTPUT: «2␤»
Output
2

Documentation, Rakudo and Raku++ all agree.

my $m = Map.new('a' => 2, 'b' => 17);
say $m.Bool;                                      # OUTPUT: «True␤»
Output
True

Documentation, Rakudo and Raku++ all agree.

my $map = Map.new('a' => 2, 'b' => 17);
my $capture = $map.Capture;
my-sub(|$capture);                                # OUTPUT: «2, 17␤»

Neither engine can run this in isolation — the example depends on context from the surrounding text.

sub my-sub(:$a, :$b) {
    say "$a, $b"
}

Not executed: the documentation states no expected output for this example.