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

A common role for types that support name-based lookup through postcircumfix:<{ }> such as Hash and Map. It is used for type checks in operators that expect to find specific methods to call. See Subscripts for details.

The % sigil restricts variables to objects that do Associative, so you will have to mix in that role if you want to use it for your classes.

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

Please note that we are using binding := here, since by default % assignments expect a Hash in the right-hand side, and thus assignment would try and convert it to a hash (also failing). However, with the Associative role:

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

will be syntactically correct.


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.

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

The value is the first parameter you use when instantiating Associative with particular classes:

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

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.

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

Methods that classes mixing Associative should provide§

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 simply want objects of a class to use {}, you can implement them without mixing the Associative role.

method AT-KEY§

method AT-KEY(\key)

Should return the value / container at the given key.

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

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:

my %h is Foo = => 42=> 666;

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.

See also§

See Methods to implement for associative subscripting for information about additional methods that can be implemented for the Associative role.


Type relations for Associative
raku-type-graph Associative Associative Mu Mu Any Any Any->Mu Cool Cool Cool->Any Iterable Iterable Map Map Map->Associative Map->Cool Map->Iterable QuantHash QuantHash QuantHash->Associative Pair Pair Pair->Associative Pair->Any Telemetry Telemetry Telemetry->Any Telemetry::Period Telemetry::Period Telemetry::Period->Associative Telemetry::Period->Telemetry Positional Positional IO::Path::Parts IO::Path::Parts IO::Path::Parts->Associative IO::Path::Parts->Any IO::Path::Parts->Iterable IO::Path::Parts->Positional Hash Hash Hash->Map PseudoStash PseudoStash PseudoStash->Map Setty Setty Setty->QuantHash Baggy Baggy Baggy->QuantHash Stash Stash Stash->Hash SetHash SetHash SetHash->Any SetHash->Setty Set Set Set->Any Set->Setty BagHash BagHash BagHash->Any BagHash->Baggy Bag Bag Bag->Any Bag->Baggy Mixy Mixy Mixy->Baggy

Expand chart above