====Datamap data====

There are occasions when you may need to work with collections of values that "belong" to a
specific object or entity in your story - for example, a table of numeric "statistics" for
a monster - or that associate a certain kind of value with another kind, such as a combination of
adjectives ("slash", "thump") that change depending on the player's weapon name ("claw", "mallet") etc.
You can create datamaps to keep these values together, move them around en masse, and organise them.

Datamaps are one of the two major "data structures" you can use in Harlowe. The other, [[harlowe:Array|Array]],
are created with [[harlowe:a|(a:)]]. You'll want to use datamaps if you want to store values that directly correspond to //[[harlowe:string|string]]//,
and whose //order// and //position// do not matter. If you need to preserve the order of the values, then an array
may be better suited.

Datamaps consist of several string //name//s, each of which maps to a specific //value//. ''%%$animals's frog%%'' and ''%%frog of $animals%%''
refers to the value associated with the name 'frog'. You can add new names or change existing values by using [[harlowe:set|(set:)]] -
''%%(set: $animals's wolf to "howl")%%''.

You can express the name as a bare word if it doesn't have a space or other punctuation in it - ''%%$animals's frog%%'' is OK, but
''%%$animals's komodo dragon%%'' is not. In that case, you'll need to always supply it as a string - ''%%$animals's "komodo dragon"%%''.

Datamaps may be joined by adding them together: ''%%(dm: "goose", "honk") + (dm: "robot", "whirr")%%'' is the same as
''%%(dm: "goose", "honk", "robot", "whirr")%%''. In the event that the second datamap has the same name as the first one,
it will override the first one's value - ''%%(dm: "dog", "woof") + (dm: "dog", "bark")%%'' will act as
''%%(dm: "dog", "bark")%%''.

You may notice that you usually need to know the names a datamap contains in order to access its values. There are certain
macros which provide other ways of examining a datamap's contents: [[harlowe:datanames|(datanames:)]] provides a sorted array of its names,
[[harlowe:datavalues|(datavalues:)]] provides a sorted array of its values, and [[harlowe:dataentries|(dataentries:)]] provides an array of names and values.

To summarise, the following operators work on datamaps.
^Operator ^ Meaning ^ Example ^
| ''is'' | Evaluates to boolean ''true'' if both sides contain equal names and values, otherwise ''false''. | ''(dm:"HP",5) is (dm:"HP",5)'' (is true)|
| ''is not'' | Evaluates to ''true'' if both sides differ in items or ordering. | ''(dm:"HP",5) is not (dm:"HP",4)'' (is true), ''(dm:"HP",5) is not (dm:"MP",5)'' (is true)|
| ''contains'' | Evaluates to ''true'' if the left side contains the name on the right. (To check that a datamap contains a value, try using ''contains'' with [[harlowe:datavalues|(datavalues:)]] | ''(dm:"HP",5) contains "HP"'' (is true), ''(dm:"HP",5) contains 5'' (is false)|
| ''is in'' | Evaluates to ''true'' if the right side contains the name on the left. | ''"HP" is in (dm:"HP",5)'' (is true)|
| ''+'' | Joins datamaps, using the right side's value whenever both sides contain the same name. | ''(dm:"HP",5) + (dm:"MP",5)''|
| '''s'' | Obtaining the value using the name on the right. | ''(dm:"love",155)'s love'' (is 155).|
| ''of'' | Obtaining the value using the name on the left. | ''love of (dm:"love",155)'' (is 155).|
| ''matches'' | Evaluates to boolean ''true'' if the datamap on one side matches the pattern on the other. | ''(dm:"Love",2,"Fear",4) matches (dm: "Love", num, "Fear", num)''|
| ''is a'', ''is an'' | Evaluates to boolean ''true'' if the right side is ''dm'' or ''datamap'', and the left side is a datamap. | ''(dm:) is a datamap''|