=begin pod

=head1 Pair

    class Pair is Enum { ... }

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

The immutable version of a C<Pair> is an C<Enum>.

=head2 Methods

=head3 value

    multi method value(Pair:D:) is rw

Returns 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
