~~Title: Map~~
<pageheader/>

The **Map** object is an [[http://en.wikipedia.org/wiki/Associative_container|associative container]]. It is similar to an array or vector (e.g. **[[vector|Vector]]**) in that it can store one or more objects, but has the advantage of using a dictionary system to locate objects rather than numeric indexes. You can therefore insert or lookup objects using an arbitrary value (string, integer, date, etc.) as the key. (Note that keys are implicitly converted into strings, regardless of initial type.)



You can access elements of the map as if the map is a function (e.g. **Map("foo")** to reference an element by the key //"foo"//). You can also use square brackets (like an array or Vector) but only if the name of the key begins with an underscore, or is completely numeric (e.g. **Map[123]** or **Map["_foo"]**). Additionally you can use the **get** and **set** methods.



You can create a new **Map** using the **[[dopusfactory|DOpusFactory]].Map** method.

The keys in a map can be enumerated, and are automatically kept sorted alphabetically. If you want to preserve the order of items added to the map, use an **[[orderedmap|OrderedMap]]** object instead.


The two examples below both output the following:
<code>
count: 4
bird -> tweet
cat -> meow
dog -> woof
snake -> hiss
</code>

==JScript Example:==
<code>
var map = DOpus.Create.Map();

map("cat") = "meow";
map("dog") = "woof";
map("bird") = "tweet";
map("snake") = "hiss";

DOpus.Output("count: " + map.count);

for (var e = new Enumerator(map); !e.atEnd(); e.moveNext())
{
 var key = e.item();
 var value = map(key);
 DOpus.Output(key + " -> " + value);
}</code>
==VBScript Example:==
<code>
Dim map, key, value
Set map = DOpus.Create.Map

map("cat") = "meow"
map("dog") = "woof"
map("bird") = "tweet"
map("snake") = "hiss"

DOpus.Output "count: " & map.count

For Each key In map
 value = map(key)
 DOpus.Output(key & " -> " & value)
Next</code>


<commandtable columns="3" id="cmdtable_1">
$$ Property Name
$$ Return Type
$$ Description
$$ count
$$ //int//
$$ Returns the number of elements the **Map** currently holds.
$$ empty
$$ //bool//
$$ Returns **True** if the **Map** is empty, **False** if not.
$$ length
$$ //int//
$$ A synonym for **count**.
$$ size
$$ //int//
$$ A synonym for **count**.
</commandtable>


<commandtable columns="4" id="cmdtable_2">
$$ Method Name
$$ **Arguments**
$$ Return Type
$$ Description
$$ assign
$$ <**Map**:from>\\
$$ //none//
$$ Copies the contents of another **Map** to this one.
$$ clear
$$ //none//
$$ //none//
$$ Clears the contents of the **Map**.
$$ erase
$$ <variant:key>
$$ //none//
$$ Erases the element matching the specified key, if it exists in the map.
$$ exists
$$ <variant:key>\\
$$ //bool//
$$ Returns **True** if the specified key exists in the map.
$$ get
$$ <variant:key>
$$ //variant//
$$ Returns the value of the specified key.
$$ merge
$$ <**Map**:from>
$$ //none//
$$ Merges the contents of another **Map** with this one.
$$ set
$$ <variant:key>\\
<variant:value>
$$ //none//
$$ Sets the value of the specified key.
</commandtable>