=begin pod

=TITLE class EnumMap

    class EnumMap does Associative is Iterable { }

An EnumMap 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 an EnumMap 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 := EnumMap.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 new

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

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

=head2 elems

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

Returns the number of pairs stored in the EnumMap.

=head2 ACCEPTS

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

Used in smart-matching if the right-hand side is an C<EnumMap>.

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

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 EnumMap by key, use the C<{ }> postcircumfix
operator:

    my $value = $enummap{$key};

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

    if %h{$key}:exists {
        say "%h{} has key $key";
    }

Note that Rakudo does not yet implement operator adverbs. As a workaround
you can use the non-standard C<exists> method.

=head2 keys

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

Returns a list of all keys in the EnumMap.

=head2 values

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

Returns a list of all values in the EnumMap.

=head2 pairs

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

Returns a list of all pairs in the EnumMap.

=head2 invert

    method invert(EnumMap:D:) returns List:D

Returns a list of pairs, but with key and value exchanged.

=head2 kv

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

Returns a list of keys and values interleaved.

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

=end pod