MapCreate

Creates a new WIL map (associative array.)

Syntax:

MapCreate([keys-values[, kv-delimtier[, pr-delimiter]]])

Parameters:

(s) keys-values: [optional] one or more key and value pairs (defaults to an empty string.)

(s) kv-delimtier: [optional] single character delimiter used between each key and associated value (defaults to a comma(,)).

(s) pr-delimtier: [optional] single character delimiter used between each key-value pair (defaults to a tab character(@Tab)).

Returns:

(m) a new WIL map.

The MapCreate function creates a WIL map that is optionally initialized with the supplied keys and associated values. Each WIL map value is accessed using the name of a variable containing the map followed by a left square bracket([), its associated key text string and a right square bracket(]). For example,

x = map["apple"]

assigns the value associated with the key "apple" to the variable x.

Note: The case of key strings is ignored.

Elements can be added to a map and maps can be created dynamically using an assignment statement like the following,

map["peach"] = 1

The example above automatically adds a new key-value pair to the map if the "peach" key does not already exist. If the key does exist, it is given the new value 1. If the variable "map" does not already exist, a new WIL map is created and initialize with the key "peach" with a value of 1. When dynamically creating a WIL map the key used in the first assignment statement creating the map cannot be a literal or variable with contents that will convert to an integer. If the key is convertible to an integer, a regular WIL array will be created. To avoid this use the MapCreate function to create the map when there is any chance that the first assignment could be an integer. An empty map can be created by calling the MapCreate function without any parameters. An empty map does not have the same restrictions on the first key assignment statement.

While WIL maps share the square brackets syntax and the WIL array variable type (256) with WIL arrays, they cannot be passed to most WIL functions expecting a WIL array as a parameter. ArrInfo is the only array function that accepts maps in its array parameter and can be used to both discover whether or not a variable contains a WIL map and the number of key-value pairs in a WIL map. See the ArrInfo topic for more information.

The keys-values parameter's contents have the following requirements:

Keys or values with embedded delimiters require the key or value require being surrounded with double quotes (").
Keys or values needing to preserve leading and/or trailing white-space require being surrounded with double quotes (").
A key or value with an embedded double quote require the embedded quote be escaped by using two double quotes ("") and the key or value be surrounded with double quotes (").
Indicate an empty string key or value contents by using two double quotes ("") with no intervening characters or white-space.

Example 1:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Create an initialized map using default delimiters ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Pairs = 'Apples,0':@tab:'Oranges,0':@tab:'Pears,0'
Fruit = MapCreate(Pairs)
; Count an apple.
Fruit["apples"] += 1

Example 2:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Create an initialized map using a custom delimiter ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Pairs = $"Apples,0
Oranges,0
Pears,0$"
Fruit = MapCreate(Pairs,'',@lf)
; Count an Oranges.
Fruit["Oranges"] += 1

Example 3:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Create an empty map                                ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Fruit = MapCreate()
; Count a Pair.
Fruit["Apples"] = 0
Fruit["Oranges"] = 0
Fruit["Pears"] = 1