=begin pod

=TITLE class 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.

X<:> X<< => >> X<:!>
There are three syntaxes for C<Pair>s:

    'key' => 'value'    # this...
    :key<value>         # ...means the same as this
    :$foo               # short for foo => $foo

Variants of this are

    :key                # same as   key => True
    :!key               # same as   key => False

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

=head1 Methods

=head2 value

    multi method value(Pair:D:) is rw

Returns the I<value> part of the C<Pair>.

=head2 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 compares the I<value> parts if the keys are equal.

=head2 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 L<sprintf>.

=head2 kv

    multi method kv(Pair:D:) returns Parcel:D

Returns a two-element C<Parcel> with the I<key> and I<value> parts o
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.

=head2 pairs

    multi method pairs(Pair:D:)

Returns a list of one C<Pair>, namely this one.

=end pod