Fetching contributors…
Cannot retrieve contributors at this time
106 lines (66 sloc) 3.11 KB
=begin pod
=TITLE role Associative
=SUBTITLE Object that supports looking up values by key
role Associative[::TValue = Mu, ::TKey = Str(Any)] { }
A common role for types that support name-based lookup through
L«postcircumfix:<{ }>|/language/operators#postcircumfix_{_}», for example
L<Hash> and L<Map>. It is used for type checks in operators that expect to find
specific methods to call. See
for details.
The C<%> sigil restricts variables to objects that do C<Associative>, so you
will have to mix in that role if you want to use it for your classes.
=begin code :skip-test<Throws exception>
class Whatever {};
my %whatever :=;
# OUTPUT: «(exit code 1) Type check failed in binding; expected Associative but got Whatever
=end code
Please note that we are using binding C<:=> here, since by default C<%>
assignments expect a C<Hash> in the right-hand side. However, with the
Associative role:
class Whatever is Associative {};
my %whatever :=;
will be syntactically correct.
=head1 Methods
=head2 of
Defined as:
method of()
C<Associative> is actually a L<parametrized role|language/objects#Parameterized_Roles>
which can use different classes for keys and values. As seen above, by default
it coerces to C<Str> for the key and uses a very generic C<Mu> for value.
my %any-hash;
say %any-hash.of;# OUTPUT: «(Mu)␤»
The value is the first parameter you use when instantiating C<Associative> with
particular classes:
class DateHash is Hash does Associative[Cool,DateTime] {};
my %date-hash :=;
say %date-hash.of; # OUTPUT: «(Cool)␤»
=head2 keyof
Defined as:
method keyof()
Returns the parametrized key used for the Associative role, which is C<Any>
coerced to C<Str> by default. This is the class used as second parameter when
you use the parametrized version of Associative.
my %any-hash;
%any-hash.keyof; #OUTPUT: «(Str(Any))␤»
=head1 Methods that should be provided
=head2 method AT-KEY
method AT-KEY(\key)
Should return the value / container at the given key.
=head2 method EXISTS-KEY
method EXISTS-KEY(\key)
Should return a C<Bool> indicating whether the given key actually has a value.
=head2 method STORE
method STORE(\values, :$initialize)
This method should only be supplied if you want to support the:
=for code :preamble<role Foo {}>
my %h is Foo = a => 42, b => 666;
syntax for binding your implementation of the C<Associative> role.
Should accept the values to (re-)initialize the object with, which either
could consist of C<Pair>s, or separate key/value pairs. The optional
named parameter will contain a C<True> value when the method is called on
the object for the first time. Should return the invocant.
=head1 See also
See L<Methods to implement for positional subscripting|> for information about additional methods that can be implemented for the C<Associative> role.
=end pod
# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6