=begin pod

=TITLE class Map

=SUBTITLE Immutable mapping from strings to values

=for code :skip-test
class Map does Associative is Iterable { }

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

In list context a Map behaves as a list of L<Pair> objects.

Note that the order in which keys, values and pairs are retrieved is
generally arbitrary, but the C<keys>, C<values> and C<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\n" or "b a\n";
    say %e.values;  # prints "1 2\n" if the previous line
                    # printed "a b\n", "b a\n" otherwise

=head1 Methods

=head2 method new

Defined as:

    proto method new(*@, *%)
    multi method new(*@args, *%pairs)

Creates a new Map from a list of alternating keys and values, with
the same semantics as described for hash assigning in the L<Hash>
documentation.

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

=head2 method elems

Defined as:

    method elems(Map:D:) returns Int:D

Returns the number of pairs stored in the Map.

    my %map = Map.new('a', 1, 'b', 2);
    say %map.elems; # 2

=head2 method ACCEPTS

Defined as:

    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 smart-matching if the right-hand side is an C<Map>.

If the topic is list-like (L<Positional>), returns True if
any of the list elements exist as a key in the Map.

If the topic is of type C<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 C<Positional>
behavior is applied.

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

    my $map = Map.new('a', 1, 'b', 2);
    say $map{'a'}; # 1

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

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

=head2 method keys

Defined as:

    method keys(Map:D:) returns List:D

Returns a list of all keys in the Map.

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

=head2 method values

Defined as:

    method values(Map:D:) returns List:D

Returns a list of all values in the Map.

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

=head2 method pairs

Defined as:

    method pairs(Map:D:) returns List:D

Returns a list of all pairs in the Map.

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

=head2 method antipairs

Defined as:

    method antipairs(Map:D:) returns Seq:D

Returns all keys and their respective values as a L<Seq|/type/Seq> of C<Pair>s
where the keys and values have been exchanged, i.e. the opposite of method
L<pairs|#method_pairs>. Unlike the L<invert|#method_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;                                  # ((2 3) => a 17 => b)

=head2 method invert

Defined as:

    method invert(Map:D:) returns Seq:D

Returns all keys and their respective values as a L<Seq|/type/Seq> of C<Pair>s
where the keys and values have been exchanged. The difference between C<invert>
and L<antipairs|#method_antipairs> is that C<invert> expands list values into
multiple pairs.

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

=head2 method kv

Defined as:

    method kv(Map:D:) returns List:D

Returns a list of keys and values interleaved.

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

=head2 method Int

Defined as:

    method Int(Map:D:) returns Int:D

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

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

=head2 method Numeric

Defined as:

    method Numeric(Map:D:) returns Int:D

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

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

=head2 method Bool

Defined as:

    method Bool(Map:D:) returns Bool:D

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

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

=head2 method Capture

Defined as:

    method Capture(Map:D:) returns Capture:D

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

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

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

=end pod
