map

How do you look a value up by a key, such as a running count for each weekday? Make a map with map.new<keyType, valueType>(), set a key with map.put and read it back with map.get, which gives na for a key the map doesn't hold. Declare the map with var to keep it from bar to bar. Most functions here can also be called as a method, as in counts.get(dayofweek).

//@version=6
indicator("Up closes by weekday")
var counts = map.new<int, int>() // var: one map, kept from bar to bar
if close > open
    counts.put(dayofweek, nz(counts.get(dayofweek)) + 1) // na for a day not seen yet
plot(nz(counts.get(dayofweek.monday)), "Mondays")

Key equality

A key matches only a key that is exactly equal. Two floats are the same key only when they are the same number, although == treats floats within 1e-10 of each other as equal. An int and the float of the same value are one key, so 1 and 1.0 are the same. Strings match by their exact text, case included, and colours by value. Objects, arrays and maps match only when they are the same one. Round a float before you use it as a key, for example with math.round(x, 2).

//@version=6
indicator("Two keys that == calls equal")
float a = (close - close) + 0.1 + 0.2 // worked out at run time: 0.30000000000000004
m = map.new<float, string>()
m.put(a, "first")
m.put(0.3, "second")
plot(m.size()) // 2, although a == 0.3 is true

Order

A map keeps its keys in the order they were first put. map.keys, map.values and a for [key, value] in m loop all go in that order, and for key in m loops over the keys alone. Putting a key the map already holds changes its value and keeps its place. A key removed and put again goes last.

References, copies and history

A map variable holds a reference, so m2 = m gives one map two names. map.copy makes a new map with the same pairs, one level deep: a value that is an object, an array or a map is the same one in both. m[1] is the map as it stood when the previous bar closed, one level deep in the same way, and na on the first bar.

Strict Pine refuses a map whose values are arrays, matrices or maps, such as map<string, array<float>>, as TradingView does. Hold the collection in a type of your own instead. AmenoScript accepts it as written.

map.new

Pine v6

map.new<keyType, valueType>() → map<keyType, valueType>

A new, empty map from keys of keyType to values of valueType, such as map.new<string, float>().

map.put

Pine v6

map.put(id, key, value) → <value_type>

Also a method: id.put(key, value).

Sets key to value and returns the value it replaced, or na for a key that is new.

Parameter	Description
id any map type	The map.
key series <type of the map's elements>	The key.
value series <type of the map's elements>	Its value.

map.put_all

Pine v6

map.put_all(id, id2) → void

Also a method: id.put_all(id2).

Puts every pair of id2 into id, in id2's order. Where both hold a key, id2's value wins.

Parameter	Description
id any map type	The map to add to.
id2 any map type	The map whose pairs are added.

map.get

Pine v6

map.get(id, key) → <value_type>

Also a method: id.get(key).

The value for key, or na if the map doesn't hold it.

A stored na reads na too, so use map.contains to tell the two apart.

Parameter	Description
id any map type	The map.
key series <type of the map's elements>	The key to look up.

map.contains

Pine v6

map.contains(id, key) → series bool

Also a method: id.contains(key).

Whether the map holds key.

Parameter
id any map type
key series <type of the map's elements>

map.remove

Pine v6

map.remove(id, key) → <value_type>

Also a method: id.remove(key).

Removes key and returns its value, or na if the map didn't hold it.

Parameter
id any map type
key series <type of the map's elements>

map.size

Pine v6

map.size(id) → series int

Also a method: id.size().

How many pairs the map holds.

Parameter
id any map type

map.clear

Pine v6

map.clear(id) → void

Also a method: id.clear().

Removes every pair, leaving the map empty.

Parameter
id any map type

map.keys

Pine v6

map.keys(id) → array<type>

Also a method: id.keys().

A new array of the keys, in order. Changing the array leaves the map as it was.

Parameter
id any map type

map.values

Pine v6

map.values(id) → array<type>

Also a method: id.values().

A new array of the values, in their keys' order. Setting an element of the array leaves the map as it was.

Parameter
id any map type

map.copy

Pine v6

map.copy(id) → map<keyType, valueType>

Also a method: id.copy().

A new map holding the same pairs, one level deep: see references, copies and history.

Parameter
id any map type