Maps

11 entries. What each one takes, what it returns, and a working example.

mapClear(map)

Removes all keys.

Does not return a value; removes all pairs from the map (the map is emptied in place).

map

The map to empty.

Note

The same map object is kept, only its contents are cleared; other variables holding it see it empty too.

CODESCRIPT

m = mapNew()
mapPut(m, "a", 1)
mapClear(m)
plot(mapSize(m))

One pair is written then the map is cleared; the size 0 is plotted.

mapContains(map, key)

Whether the key exists (true/false).

true if the key exists in the map, otherwise false.

map

The map to check.

key

any

The key whose presence is queried.

Note

A value being na is different from the key being absent; this function only checks whether the key exists.

CODESCRIPT

m = mapNew()
mapPut(m, "a", 1)
plot(iff(mapContains(m, "a"), 1, 0))

Since key "a" was written, it plots 1.

mapCopy(map)

Shallow copy of the map.

A new, independent map holding the same pairs.

map

The map to copy.

Note

The copy is independent — writing to the copy does not affect the original. Useful for branching a new state.

CODESCRIPT

a = mapNew()
mapPut(a, "x", 1)
b = mapCopy(a)
mapPut(b, "y", 2)
plot(mapSize(a))

A new pair is added to the copy, but the original still holds one pair so its size 1 is plotted.

mapGet(map, key)

Value for the key (na if absent).

The value at the key, or na if the key is absent (or the input is not a map).

map

The map to read.

key

any

The key whose value is requested.

Note

A missing key does not raise an error, it returns na — conditions run safely over na.

CODESCRIPT

m = mapNew()
mapPut(m, "high", highest(high, 20))
plot(mapGet(m, "high"))

Stores the 20-bar highest level under the "tepe" key and reads it back to plot it.

mapKeys(map)

Returns the keys as an array. Result: Arr(len=0, [])

An array holding the map's keys in insertion order.

map

The map whose keys are requested.

Note

You can read the array's length with arraySize and walk its elements with the array functions.

CODESCRIPT

m = mapNew()
mapPut(m, "a", 1)
mapPut(m, "b", 2)
plot(arraySize(mapKeys(m)))

Two keys are written; the length of the key array, 2, is plotted.

mapNew()

Creates an empty table that maps a key to a value. When you want to reach things by name rather than by position it suits better than an array — keeping a number per symbol name, for instance.

An empty map (key→value). Keys may be text, number or boolean.

Note

A map holds key→value pairs; writing the same key again overwrites the old value. Values may be numbers, text, booleans or series.

When to use

When you want to store a value against a label (a symbol, a level name, a state) and read it back by name later; when you need access by a meaningful key rather than a numeric index.

CODESCRIPT

m = mapNew()
mapPut(m, "threshold", 42)
plot(iff(mapContains(m, "threshold"), close, open))

Creates an empty map, writes 42 under the "esik" key; since the key exists it plots close.

mapPut(map, key, value)

Writes a value for a key in the map; if the key already exists it overwrites and returns the old value. Otherwise it creates a new entry.

The value previously held at the key, or na if the key was absent. The map is changed in place.

map

The map to write into.

key

any

The key to store the value under (text/number/boolean).

value

any

The value to store.

Note

If the key already exists its value is updated and the old value is returned; otherwise a new pair is added and na is returned.

CODESCRIPT

m = mapNew()
previous = mapPut(m, "k", 10)
mapPut(m, "k", 20)
plot(mapGet(m, "k"))

Writes 10 then 20 under key "k"; the previous value is na on the first write. The final value 20 is plotted.

mapPutAll(map1, map2)

Copies harita2 into harita1.

Does not return a value; copies all pairs from map2 into map1 (colliding keys are overwritten).

map1

map

The target map (written into).

map2

map

The source map (read from).

Note

Only the target (map1) changes; the source (map2) is left unchanged.

CODESCRIPT

a = mapNew()
mapPut(a, "x", 1)
b = mapNew()
mapPut(b, "y", 2)
mapPutAll(a, b)
plot(mapSize(a))

b's pair is added to a; a now holds two pairs so the size 2 is plotted.

mapRemove(map, key)

Removes the key and returns its value.

The value of the removed key, or na if the key was absent. The map is changed in place.

map

The map to remove from.

key

any

The key to remove.

Note

If the key is absent it silently returns na with no error.

CODESCRIPT

m = mapNew()
mapPut(m, "a", 5)
mapRemove(m, "a")
plot(iff(mapContains(m, "a"), 1, 0))

Key "a" is written then removed; since it is no longer present it plots 0.

mapSize(map)

Number of keys.

The number of key-value pairs in the map; 0 if the input is not a map.

map

The map whose size is requested.

Note

Returns 0 for an empty map. Writing the same key again does not increase the size.

CODESCRIPT

m = mapNew()
mapPut(m, "a", 1)
mapPut(m, "b", 2)
plot(mapSize(m))

Two distinct keys are written; the size 2 is plotted.

mapValues(map)

Returns the values as an array. Result: Arr(len=0, [])

An array holding the map's values in key insertion order.

map

The map whose values are requested.

Note

For numeric values you can combine values with array functions such as arraySum / arrayAvg.

CODESCRIPT

m = mapNew()
mapPut(m, "a", 10)
mapPut(m, "b", 20)
plot(arraySum(mapValues(m)))

Values are 10 and 20; the sum of the value array, 30, is plotted.