How To Work With Arrays And Maps

Arrays and maps store several values in one object.

Use an array when order matters:

tools = array('T1', 'T2', 'T3');

Use a map when names matter:

tool = map('name', 'T1', 'diameter', 6, 'feed', 800);

Both arrays and maps are useful before a script needs full classes.

Array Or Map?

Use this	When	Example
array	You have a list of values in order.	tool names, probe samples, file names
map	You have named values.	one tool record, settings, dialog result

Examples:

samples = array(0.02, 0.03, 0.01);
settings = map('safe_z', 5, 'feed', 100);

Create An Array

Create an empty array with `array()`.

items = array();

Create an array with starting values:

tools = array('T1', 'T2', 'T3');

Check how many values it has:

tools.size();

The final result is `3`.

Add And Read Array Values

Use `add(value)` to append a value.

tools = array();
tools.add('T1');
tools.add('T2');
 
tools.size();

The final result is `2`.

Array indexes start at `0`.

tools.get(0);    // 'T1'
tools.get(1);    // 'T2'

Reading outside the array returns `none()`.

tools.get(99).is_none();

Change Array Values

Use `set(index, value)` to change a value.

tools = array('T1', 'T2', 'T3');
tools.set(1, 'T2-new');
 
tools.get(1);

The final result is `'T2-new'`.

If the index is beyond the end, the array grows and missing positions are filled with `none()`.

items = array('A');
items.set(2, 'C');
items.to_string();     // ["A", none, "C"]

Insert And Remove Array Values

Use `insert(index, value)` to insert before an index.

items = array('A', 'C');
items.insert(1, 'B');
items.to_string();

The final result is `[“A”, “B”, “C”]`.

Use `remove(index)` to remove a value.

items.remove(1);
items.to_string();

The final result is `[“A”, “C”]`.

Loop Through An Array

Use a `for` loop with `size()`.

tools = array('T1', 'T2', 'T3');
 
for(i = 0; i < tools.size(); i += 1)
{
    print('tool ', tools.get(i));
};

Remember that the first index is `0`, and the last index is `size() - 1`.

Join Array Values Into Text

Use `join(separator)` to make text from array values.

tools = array('T1', 'T2', 'T3');
text = tools.join(', ');
text;

The final result is `'T1, T2, T3'`.

This is useful for reports and debug output.

Create A Map

Create an empty map with `map()`.

settings = map();

Create a map with starting key/value pairs:

tool = map('name', 'T1', 'diameter', 6, 'feed', 800);

The number of constructor arguments must be even: key, value, key, value.

Set And Get Map Values

Use `set(key, value)` to store a value.

tool = map();
tool.set('name', 'T1');
tool.set('diameter', 6);
tool.set('feed', 800);

Use `get(key)` to read a value.

tool.get('diameter');

The final result is `6`.

A missing key returns `none()`.

tool.get('speed').is_none();

Check Map Keys

Use `has(key)` to check whether a key exists.

if(tool.has('diameter'))
{
    print('diameter ', tool.get('diameter'));
}
else
{
    print('diameter missing');
};

This is better than assuming the value exists.

Read Map Values As Properties

Map keys can be read with property syntax when the key is a valid property name.

tool = map('name', 'T1', 'diameter', 6);
 
print(tool.name);
print(tool.diameter);

Property access is read-only. Use `set(key, value)` to change a map entry.

tool.set('diameter', 8);

Do not write this:

tool.diameter = 8;    // not supported

Loop Through Map Keys

Use `keys()` to get an array of map keys.

tool = map('name', 'T1', 'diameter', 6, 'feed', 800);
keys = tool.keys();
 
for(i = 0; i < keys.size(); i += 1)
{
    key = keys.get(i);
    print(key, ' = ', tool.get(key));
};

`keys()` returns keys in insertion order.

Use `values()` when you only need the values.

tool.values().to_string();

Remove And Clear Values

Use `remove(…)` to remove one item.

tools = array('T1', 'T2', 'T3');
tools.remove(1);

For maps, remove by key:

settings = map('safe_z', 5, 'feed', 100);
settings.remove('feed');

Use `clear()` to remove everything.

tools.clear();
settings.clear();

Store Maps In Arrays

Arrays can store maps. This is useful for simple tables.

tools = array();
tools.add(map('name', 'T1', 'diameter', 6));
tools.add(map('name', 'T2', 'diameter', 3));
 
for(i = 0; i < tools.size(); i += 1)
{
    tool = tools.get(i);
    print(tool.name, ' D=', tool.diameter);
};

For larger behavior, use classes. For simple data, array of maps is often enough.

Use Arrays And Maps From MDI

In MDI, start with `=` to evaluate Expr.

=tools=array('T1','T2','T3');
tools.add('T4');
tools.join(', ');

The final result is `'T1, T2, T3, T4'`.

Common Mistakes

Forgetting That Indexes Start At 0

items = array('A', 'B');
items.get(0);    // 'A'
items.get(1);    // 'B'
items.get(2);    // none()

Using Property Assignment On Maps

Map properties are read-only.

tool.diameter = 8;       // not supported
tool.set('diameter', 8); // correct

Not Checking Missing Values

feed = settings.get('feed');
feed * 2;                // error if feed is none()

Check first:

feed = settings.get('feed');
 
if(feed.is_none())
{
    error('feed setting is missing');
};

Using A Map When A Class Is Better

A map is good for simple named data. If the data also needs behavior, use a class.

class ToolInfo(name, diameter)
{
    Name = name;
    Diameter = diameter;
 
    function Radius()
    {
        return Diameter / 2;
    }
}

Try This

In MDI, try:

=tools=array();
tools.add(map('name','T1','diameter',6));
tools.add(map('name','T2','diameter',3));
text='';
for(i=0; i<tools.size(); i+=1)
{
    tool=tools.get(i);
    text += tool.name + ':' + tool.diameter + ';';
};
text;

The final result is `'T1:6;T2:3;'`.

Table of Contents