class Map does Associative does Iterable { }

A Map is an immutable mapping from string keys to values of arbitrary types. It serves as a base class for Hash, which is mutable.

In list context a Map behaves as a list of Pair objects.

Note that the order in which keys, values and pairs are retrieved is generally arbitrary, but the keys, values and pairs methods return them always in the same order when called on the same object.

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

To retrieve a value from the Map by key, use the { } postcircumfix operator:

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

To check whether a given key is stored in a Map, modify the access with the :exists adverb:

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

Being an immutable instance, it is not possible to add keys after a Map has been initialized:

my $m = Map.new( 'a', 1, 'b', 2 );
$m{ 'c' } = 'foo'; # WRONG! 
                   # Cannot modify an immutable Str

Unlike its mutable companion type Hash, a Map cannot be parameterized by key or value types.

Methods

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.

my %h = Map.new('a', 1, 'b', 2);
 
# WRONG: :b(2) interpreted as named argument 
say Map.new('a', 1, :b(2)).keys; # OUTPUT: «(a)␤» 
 
# RIGHT: :b(2) interpreted as Pair because of extra parentheses 
say Map.new( ('a', 1, :b(2)) ).keys.sort; # OUTPUT: «(a b)␤» 
 
# RIGHT: 'b' => 2 always creates a Pair 
say Map.new('a', 1, 'b' => 2).keys.sort; # OUTPUT: «(a b)␤»

A shorthand syntax for creating Maps is provided:

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

method elems

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

Returns the number of pairs stored in the Map.

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

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 an 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 behavior is applied.

method gist

method gist(Map:D: --> 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 a Seq of all keys in the Map.

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

method values

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

Returns a Seq of all values in the Map.

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

method pairs

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

Returns a Seq of all pairs in the Map.

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

method antipairs

method antipairs(Map:D: --> 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.

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

method invert

method invert(Map:D: --> 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.

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

method kv

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

Returns a Seq of keys and values interleaved.

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

method list

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

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

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

method sort

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

Returns a Seq of Pair objects, which are the pairs of the hash, sorted by key. Equivalent to %hash.sort: *.key

# 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)␤»

See Any.sort for additional available candidates.

method Int

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

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

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

method Numeric

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

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

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

method Bool

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

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

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

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.

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