txt: ## associative.md
  role Associative
  
  Object that supports looking up values by key
  
  ```raku
  role Associative[::TValue = Mu, ::TKey = Str(Any)] { }
  ```
  
  A common role for types that support name-based lookup through [postcircumfix:<{ }>](/language/operators#postcircumfix_{_}) such as [`Hash`](/type/Hash) and [`Map`](/type/Map). It is used for type checks in operators that expect to find specific methods to call. See [Subscripts](/language/subscripts#Methods_to_implement_for_associative_subscripting) 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.
  
  ```raku
  class Whatever {};
  my %whatever := Whatever.new;
  # 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`](/type/Hash) in the right-hand side, and thus assignment would try and convert it to a hash (also failing). However, with the Associative role:
  
  ```raku
  class Whatever is Associative {};
  my %whatever := Whatever.new;
  ```
  
  will be syntactically correct.
  
  # [Methods](#role_Associative "go to top of document")[§](#Methods "direct link")
  
  ## [method of](#role_Associative "go to top of document")[§](#method_of "direct link")
  
  ```raku
  method of()
  ```
  
  `Associative`, as the definition above shows, is actually a [parameterized role](/language/objects#Parameterized_roles) 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`](/type/Str) and uses a very generic [`Mu`](/type/Mu) for value.
  
  ```raku
  my %any-hash;
  say %any-hash.of; # OUTPUT: «(Mu)␤»
  ```
  
  The value is the first parameter you use when instantiating `Associative` with particular classes:
  
  ```raku
  class DateHash is Hash does Associative[Cool,DateTime] {};
  my %date-hash := DateHash.new;
  say %date-hash.of; # OUTPUT: «(Cool)␤»
  ```
  
  ## [method keyof](#role_Associative "go to top of document")[§](#method_keyof "direct link")
  
  ```raku
  method keyof()
  ```
  
  Returns the parameterized key used for the Associative role, which is [`Any`](/type/Any) coerced to [`Str`](/type/Str) by default. This is the class used as second parameter when you use the parameterized version of Associative.
  
  ```raku
  my %any-hash;
  %any-hash.keyof; # OUTPUT: «(Str(Any))␤»
  ```
  
  # [Methods that classes mixing Associative should provide](#role_Associative "go to top of document")[§](#Methods_that_classes_mixing_Associative_should_provide "direct link")
  
  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](#role_Associative "go to top of document")[§](#method_AT-KEY "direct link")
  
  ```raku
  method AT-KEY(\key)
  ```
  
  Should return the value / container at the given key.
  
  ```raku
  class What { method AT-KEY(\key) { 42 }};
  say What.new{33}; # OUTPUT: «42␤»
  
  ```
  
  ## [method EXISTS-KEY](#role_Associative "go to top of document")[§](#method_EXISTS-KEY "direct link")
  
  ```raku
  method EXISTS-KEY(\key)
  ```
  
  Should return a [`Bool`](/type/Bool) indicating whether the given key actually has a value.
  
  ## [method STORE](#role_Associative "go to top of document")[§](#method_STORE "direct link")
  
  ```raku
  method STORE(\values, :$INITIALIZE)
  ```
  
  This method should only be supplied if you want to support the:
  
  ```raku
  my %h is Foo = a => 42, b => 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 [`Pair`](/type/Pair)s, 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](#role_Associative "go to top of document")[§](#See_also "direct link")
  
  See [Methods to implement for associative subscripting](/language/subscripts#Methods_to_implement_for_associative_subscripting) for information about additional methods that can be implemented for the `Associative` role.
  
  # [Typegraph](# "go to top of document")[§](#typegraphrelations "direct link")
  
  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
  
  
  
  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
  
  
  
  Pair
  Pair
  
  
  Pair->Associative
  
  
  
  Pair->Any
  
  
  
  QuantHash
  QuantHash
  
  
  QuantHash->Associative
  
  
  
  PseudoStash
  PseudoStash
  
  
  PseudoStash->Map
  
  
  
  Hash
  Hash
  
  
  Hash->Map
  
  
  
  Setty
  Setty
  
  
  Setty->QuantHash
  
  
  
  Baggy
  Baggy
  
  
  Baggy->QuantHash
  
  
  
  Stash
  Stash
  
  
  Stash->Hash
  
  
  
  Set
  Set
  
  
  Set->Any
  
  
  
  Set->Setty
  
  
  
  SetHash
  SetHash
  
  
  SetHash->Any
  
  
  
  SetHash->Setty
  
  
  
  Bag
  Bag
  
  
  Bag->Any
  
  
  
  Bag->Baggy
  
  
  
  BagHash
  BagHash
  
  
  BagHash->Any
  
  
  
  BagHash->Baggy
  
  
  
  Mixy
  Mixy
  
  
  Mixy->Baggy
  
  [Expand chart above](/assets/typegraphs/Associative.svg)
  