class Pair

Key/value pair

class Pair does Associative {}

Consists of two parts, a key and a value. Pairs can be seen as the atomic units in Hashes, and they are also used in conjunction with named arguments and parameters.

There are many syntaxes for creating Pairs:

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(127);                # short for  foo => 127 
:127foo;                  # the same   foo => 127 

Variants of this are

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

And this other variant, to be used in routine invocation

sub colon-pair:$key-value ) {
    say $key-value;
}
my $key-value = 'value';
colon-pair:$key-value );               # OUTPUT: «value␤» 
colon-pairkey-value => $key-value );   # OUTPUT: «value␤» 

Colon pairs can be chained without a comma to create a List of Pairs. Depending on context you may have to be explicit when assigning colon lists.

sub s(*%h){ say %h.perl };
s :a1:b2;
# OUTPUT: «{:a1, :b2}␤» 
 
my $manna = :a1:b2:c3;
say $manna.^name;
# OUTPUT: «Pair␤» 
 
$manna = (:a1:b2:c3);
say $manna.^name;
# OUTPUT: «List␤» 

Any variable can be turned into a Pair of its name and its value.

my $bar = 10;
my $p   = :$bar;
say $p# OUTPUT: «bar => 10␤» 

It is worth noting that when assigning a Scalar as value of a Pair the value holds the container of the value itself. This means that it is possible to change the value from outside of the Pair itself:

my $v = 'value A';
my $pair = => $v;
$pair.say;  # OUTPUT: a => value A 
 
$v = 'value B';
$pair.say# OUTPUT: a => value B 

Please also note that this behavior is totally unrelated to the way used to build the Pair itself (i.e., explicit usage of new, use of colon, fat arrow), as well as if the Pair is bound to a variable.

It is possible to change the above behaviour forcing the Pair to remove the scalar container and to hold the effective value itself via the method freeze:

my $v = 'value B';
my $pair = => $v;
$pair.freeze;
$v = 'value C';
$pair.say# OUTPUT: a => value B 

Methods

method new

Defined as:

multi method new(Pair: Mu  $keyMu  $value)
multi method new(Pair: Mu :$keyMu :$value)

Constructs a new Pair object.

method ACCEPTS

Defined as:

multi method ACCEPTS(Pair:D $: %topic)
multi method ACCEPTS(Pair:D $: Pair:D $topic)
multi method ACCEPTS(Pair:D $: Mu $topic)

If topic is an Associative, looks up the value using invocant's key in it and checks invocant's value .ACCEPTS that value:

say %(:42a) ~~ :42a; # OUTPUT: «True␤» 
say %(:42a) ~~ :10a; # OUTPUT: «False␤» 

If topic is another Pair, checks the invocant's value .ACCEPTS the topic's value. Note that the keys are not considered and can be different:

say :42~~ :42a; # OUTPUT: «True␤» 
say :42~~ :42a; # OUTPUT: «True␤» 
say :10~~ :42a; # OUTPUT: «False␤» 

If topic is any other value, uses the invocant's key as the name of the method to call on topic and check's its .Bool is the same as .Bool of the invocant's value. This form can be used to check Bool values of multiple methods on the same object, such as IO::Path, by using Junctions:

say "foo" .IO ~~ :f & :rw# OUTPUT: «False␤» 
say "/tmp".IO ~~ :!f;      # OUTPUT: «True␤» 
say "."   .IO ~~ :f | :d;  # OUTPUT: «True␤» 

method antipair

Defined as:

method antipair(--> Pair:D)

Returns a new Pair object with key and value exchanged.

my $p = (6 => 'Perl').antipair;
say $p.key;         # OUTPUT: «Perl␤» 
say $p.value;       # OUTPUT: «6␤» 

method key

Defined as:

multi method key(Pair:D:)

Returns the key part of the Pair.

my $p = (Perl => 6);
say $p.key# OUTPUT: «Perl␤» 

method value

Defined as:

multi method value(Pair:D:is rw

Returns the value part of the Pair.

my $p = (Perl => 6);
say $p.value# OUTPUT: «6␤» 

infix cmp

Defined as:

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

The type-agnostic comparator; compares two Pairs. Compares first their key parts, and then compares the value parts if the keys are equal.

my $a = (Apple => 1);
my $b = (Apple => 2);
say $a cmp $b# OUTPUT: «Less␤» 

method fmt

Defined as:

multi method fmt(Pair:D: Str:D $format --> Str:D)

Takes a format string, and returns a string the key and value parts of the Pair formatted. Here's an example:

my $pair = :Earth(1);
say $pair.fmt("%s is %.3f AU away from the sun")
# OUTPUT: «Earth is 1.000 AU away from the sun␤» 

For more about format strings, see sprintf.

method kv

Defined as:

multi method kv(Pair:D: --> List:D)

Returns a two-element List with the key and value parts of Pair, in that order. This method is a special case of the same-named method on Hash, which returns all its entries as a list of keys and values.

my $p = (Perl => 6);
say $p.kv[0]; # OUTPUT: «Perl␤» 
say $p.kv[1]; # OUTPUT: «6␤» 

method pairs

Defined as:

multi method pairs(Pair:D:)

Returns a list of one Pair, namely this one.

my $p = (Perl => 6);
say $p.pairs.^name# OUTPUT: «List␤» 
say $p.pairs[0];    # OUTPUT: «Perl => 6␤» 

method antipairs

Defined as:

multi method antipairs(Pair:D:)

Returns a List containing the antipair of the invocant.

my $p = (6 => 'Perl').antipairs;
say $p.^name;                                     # OUTPUT: «List␤» 
say $p.first;                                     # OUTPUT: «Perl => 6␤» 
say $p.first.^name;                               # OUTPUT: «Pair␤» 

method invert

Defined as:

method invert(Pair:D: --> Seq:D)

Returns a Seq. If the .value of the invocant is NOT an Iterable, the Seq will contain a single Pair whose .key is the .value of the invocant and whose .value is the .key of the invocant:

:foo<bar>.invert.perl.say# OUTPUT: «(:bar("foo"),).Seq» 

If invocant's .value is an Iterable, the returned Seq will contain the same number of Pairs as items in the .value, with each of those items a .key of a pair and the .key of the invocant the .value of that pair:

:foo<Perl is great>.invert.perl.say;
# OUTPUT: «(:Perl("foo"), :is("foo"), :great("foo")).Seq» 
 
:foo{ :42a, :72}.invert.perl.say;
# OUTPUT: «((:a(42)) => "foo", (:b(72)) => "foo").Seq» 

To perform the exact .key and .value swap, use .antipair method.

method keys

Defined as:

multi method keys(Pair:D: --> List:D)

Returns a List containing the key of the invocant.

say ('Perl' => 6).keys;                           # OUTPUT: «(Perl)␤» 

method values

Defined as:

multi method values(Pair:D: --> List:D)

Returns a List containing the value of the invocant.

say ('Perl' => 6).values;                         # OUTPUT: «(6)␤» 

method freeze

Defined as:

method freeze(Pair:D:)

Makes the value of the Pair read-only, by removing it from its Scalar container, and returns it.

my $str = "apple";
my $p = Pair.new('key'$str);
$p.value = "orange";              # this works as expected 
$p.say;                           # OUTPUT: «key => orange␤» 
$p.freeze.say;                    # OUTPUT: «orange␤» 
$p.value = "a new apple";         # Fails 
CATCH { default { put .^name''.Str } };
# OUTPUT: «X::Assignment::RO: Cannot modify an immutable Str (apple)␤» 

NOTE: this method is proposed for removal in 6.d language and its use is not recommended.

method Str

Defined as:

multi method Str(Pair:D: --> Str:D)

Returns a string representation of the invocant formatted as key ~ \t ~ value.

my $b = eggs => 3;
say $b.Str;                                       # OUTPUT: «eggs  3␤» 

Type Graph

Type relations for Pair
perl6-type-graph Pair Pair Any Any Pair->Any Associative Associative Pair->Associative Mu Mu Any->Mu

Stand-alone image: vector