Rules / Types, classes & roles / composite

Associative Reference

Object that supports looking up values by key

What it is #

Position in the hierarchy #

Inherits from—
Does—
Consumed byTelemetry::Period, IO::Path::Parts, Pair, Map, QuantHash

Routines #

Signatures are reproduced from the documentation, including their declared return types. A routine listed here is part of the type's published interface; whether Raku++ implements it is a separate question, answered by the examples below.

method of #

method of()

Associative, as the definition above shows, is actually a parameterized role which can use different classes for keys and values. As seen at the top of the document, by default it coerces the key to Str and uses a very generic Mu for value. The value is the first parameter you use when instantiating Associative with particular classes:

method keyof #

method keyof()

Returns the parameterized key used for the Associative role, which is Any coerced to Str by default. This is the class used as second parameter when you use the parameterized version of Associative. You need to provide these methods if you want your class to implement the Associative role properly and, thus, use the {} operator for accessing the value given a key. They are not mandatory, however; on the other hand, if you

method AT-KEY #

method AT-KEY(\key)

Should return the value / container at the given key.

method EXISTS-KEY #

method EXISTS-KEY(\key)

Should return a Bool indicating whether the given key actually has a value.

method STORE #

method STORE(\values, :$INITIALIZE)

This method should only be supplied if you want to support the: syntax for binding your implementation of the Associative role. Should accept the values to (re-)initialize the object with, which either could consist of Pairs, or separate key/value pairs. The optional named parameter will contain a True value when the method is called on the object for the first time. Should return the invocant.

Examples, run three ways #

Every example below comes from the official documentation, together with the output that documentation asserts. Each was then executed by Rakudo and by Raku++ when this page was built. Where the three agree, one result is shown; where they do not, all three are — because which of them is wrong is exactly the information worth having.

1 doc-drift · 4 no-output · 2 ok · 1 rakupp-differs

role Associative[::TValue = Mu, ::TKey = Str(Any)] { }

Not executed: the documentation states no expected output for this example.

class Whatever {};
my %whatever := Whatever.new;
# OUTPUT: «Type check failed in binding; expected Associative but got Whatever

Not executed: the documentation states no expected output for this example.

class Whatever is Associative {};
my %whatever := Whatever.new;

Not executed: the documentation states no expected output for this example.

my %any-hash;
say %any-hash.of; # OUTPUT: «(Mu)␤»
Output
(Mu)

Documentation, Rakudo and Raku++ all agree.

class DateHash is Hash does Associative[Cool,DateTime] {};
my %date-hash := DateHash.new;
say %date-hash.of; # OUTPUT: «(Cool)␤»
Documentation
(Cool)
Rakudo
(Cool)
Raku++
(Mu)

Raku++ disagrees with both the documentation and Rakudo — a defect.

my %any-hash;
%any-hash.keyof; # OUTPUT: «(Str(Any))␤»
Documentation
(Str(Any))
Rakudo
Raku++

Both engines agree; the documentation states something else. Trust the engines.

class What { method AT-KEY(\key) { 42 }};
say What.new{33}; # OUTPUT: «42␤»
Output
42

Documentation, Rakudo and Raku++ all agree.

my %h is Foo = a => 42, b => 666;

Not executed: the documentation states no expected output for this example.