Pair.pod

=begin pod

=TITLE class Pair

=SUBTITLE Key/value pair

    class Pair does Associative { ... }

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 many syntaxes for creating C<Pair>s:

    Pair.new('key','value)  # The canonical way
    'key' => 'value'        # this...
    :key<value>             # ...means the same as this
    :key<value1 value2>     # But this is  key => <value1 value2>
    :$foo                   # short for  foo => $foo
    :foo(127)               # short for  foo => 127
    :127foo                 # the same   foo => 127

Variants of this are

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

=head1 Methods

=head2 method antipair

Defined as:

    method antipair() returns Pair:D

Usage:

    PAIR.antipair

Returns a new C<Pair> object with key and value exchanged.

    my $p = (6 => 'Perl').antipair;
    say $p.key;         # Perl
    say $p.value;       # 6

=head2 method value

Defined as:

    multi method value(Pair:D:) is rw

Usage:

    PAIR.value

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

=head2 infix cmp

Defined as:

    multi sub infix:<cmp>(Pair:D, Pair:D)

Usage:

    PAIR1 cmp PAIR2

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 method fmt

Defined as:

    multi method fmt(Pair:D:) returns Str:D

Usage:

    PAIR.fmt(FORMATSTRING)

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 method kv

Defined as:

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

Usage:

    PAIR.kv

Returns a two-element C<List> with the I<key> and I<value> parts of
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 method pairs

Defined as:

    multi method pairs(Pair:D:)

Usage:

    PAIR.pairs

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

=end pod