Immutable mapping from strings to values
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.
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(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»
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 behavior is applied.
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(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(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(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(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(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(Map:D: --> Seq:D)
Returns a Seq of keys and values interleaved.
Map.new('a', 1, 'b', 2).kv # (a 1 b 2)
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))»
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(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(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(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(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"
}