A MAP is a table of values, called elements. The elements of a MAP are distinguished by their keys. Keys may be either NUMBER or TEXT literals. MAPs in LDPL are variables that hold a collection of values. When you declare a MAP, you declare a structure that lets you store values of its type on any sub-index of the variable. For example, say you declare the map
DATA:myMap IS NUMBER MAP
Then you can use
myMap as a multi-variable with various indexes where you can store NUMBERs.
Unlike LISTs, MAPs are associative. This means that each MAP is a collection of pairs: a key and its corresponding element. For example, you could have a
NUMBER MAP with the following contents:
We have shown the pairs in jumbled order because their order is irrelevant. One advantage of MAPs is that new pairs can be added at any time. MAPs can be sparse: they can have missing keys (say for example you have keys 1 and 5, but don't have keys 2, 3 and 4). Another consequence of MAPs is that the keys don't necessarily have to be positive integers. Any number, or even a string, can be a key.
Values in MAPs can be stored and accessed just like any other variable (see the STORE - IN statement for further details) using the
: operator. This operator indicates what key of the MAP we are writing to or reading from. Here we declare a
NUMBER MAP and store the values
-10.2 in the keys
DATA:myMap IS NUMBER MAPPROCEDURE:STORE 5 IN myMap:1 #Stores 5 in key 1 of myMapSTORE -10.2 IN myMap:5 #Stores -10.2 in key 5 of myMap
As stated before, MAP keys don't always have to be constant NUMBERs. They can also be NUMBER variables, TEXT and TEXT variables, or even sub-indexes of LISTs or elements from other MAPs. For example:
DATA:myMap IS NUMBER MAPmyOtherMap IS NUMBER MAPmyVar IS NUMBERPROCEDURE:STORE 17 IN myVarSTORE 1 IN myMap:"hello" #Stores 1 in key "hello" of myMapSTORE 7 IN myMap:myVar #Stores 7 in a key equal to the current value of myVarSTORE 3 IN myMap:myOtherMap:4#Stores 3 in a key of equal value to the key of myMap with value equal to#key 4 of myOtherMap
In fact, when you use a NUMBER value as a subindex for a MAP, it is silently casted into a TEXT value. For example,
myMap:1 will be interpreted (an thus, the same) as
Please note that as a MAP is variable that's a collection of values, a single key of a MAP is a variable in itself. This means that any key of a MAP can be used in any position where you could use a variable of the same type of the MAP. So, if you have something like this:
STORE <NUMBER-VAR or NUMBER> IN <NUMBER-VAR>
You could use a
NUMBER MAP with a particular key where it says NUMBER-VAR, just like in the
STORE - IN examples in the code extracts above (for example
When LDPL creates a MAP for you using a built-in statement that automatically inserts values into the MAP, for example the SPLIT built-in statement with a MAP for destination, the keys used will be consecutive integers starting at zero (
As you'll see in the Default Variable Values section, you can access undeclared keys of a MAP just like if they were declared. See the following example:
DATA:myMap IS NUMBER MAPPROCEDURE:DISPLAY myMap:99
In the example above,
0 will be printed and no errors displayed during compilation, even though the key
myMap hasn't been explicitly declared. This is because when you try to access an element that hasn't been declared yet, LDPL declares it for you and initializes it to its type default value.
It's important to note that this very feature is a double-edged weapon. While you can use it to access uninitialized MAP keys, you cannot check if a value exists in a MAP without initializing it if it wasn't there before. Statements like STORE KEY COUNT OF and STORE KEYS OF are provided as means to overcome this situation.
In the MAP STATEMENTS section you'll find a collection of statements that can be used to work with MAPs.