[Pair] mostly stolen from u4x

Author: moritz

lib/Pair.pod

@@ -0,0 +1,64 @@
+=begin pod
+
+=head1 Pair
+
+Consists of two parts, a I<key> and a I<value>. C<Pair>s can be seen as the
+atomic units in C<Hash>es, and they are also used in conjunction with named
+arguments and parameters.
+
+There are three syntaxes for C<Pair>s:
+
+    'key' => 'value'    # this...
+    :key<value>         # ...means the same as this
+    :$foo               # short for foo => $foo
+
+=head2 Methods
+
+=head3 key
+
+    multi method key(Pair:D:)
+
+Gives the I<key> part of the C<Pair>.
+
+=head3 value
+
+    multi method value(Pair:D:)
+
+Gives the I<value> part of the C<Pair>.
+
+=head3 cmp
+
+    multi sub infix:<cmp>(Pair:D, Pair:D)
+
+The type-agnostic comparator; compares two C<Pair>s. Compares first their
+I<key> parts, and then (if the first comparison yielded 0) the I<value> parts.
+
+=head3 fmt
+
+    multi method fmt(Pair:D:) returns Str:D
+
+Takes a I<format string>, and returns a string the I<key> and I<value>
+parts of the C<Pair> formatted. Here's an example:
+
+    my $pair = :Earth(1);
+    say $pair.fmt("%s is %.3f AU away from the sun")
+    # Prints "Earth is 1.000 AU away from the sun"
+
+For more about format strings, see X<sprintf>.
+
+=head3 kv
+
+    multi method kv(Pair:D:) returns List:D
+
+Returns a two-element C<List> with the I<key> and I<value> parts of the
+C<Pair>, in that order. This method is a special case of the same-named
+method on C<Hash>, which returns all its entries as a list of keys and
+values.
+
+=head3 pairs
+
+    multi method pairs(Pair:D:)
+
+Returns a list of one C<Pair>, namely this one.
+
+=end pod