start to document EnumMap

lib/EnumMap.pod

@@ -0,0 +1,76 @@
+=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
+
+=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.
+
+=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.
+
+=end pod