Pine Script® now features maps!

We present a new tool for Pine coders — Maps, collections that hold data in key-value pairs. They allow users to link related elements of different types together for access later in a script. Unlike other Pine collections, scripts quickly access a map’s values using the keys from its key-value pairs instead of an internal index.

The map namespace is home to all of our map-related functions. To create a map, use the map.new<key_type, value_type>() function. For example:

//@variable A map containing `int` keys and  `line` values.
m = map.new<int, line>()

A map’s keys can be of any fundamental type (int, float, bool, string, or color), and its values can be of any type, even a user-defined type.

After creating a map, you can use any of the functions in the map namespace with it. For instance, you can put key-value pairs into it using map.put() and retrieve the value linked to a unique key using map.get(). You can also generate an array from all mapped keys or values using map.keys() or map.values(). For more information about using these new collections and their related functions, see our User Manual’s page on Maps.

In the example below, we’ve created a script that uses maps to color the chart’s background on session price changes. It uses a data map to store closing time and net price change information for each day’s session, then calculates a ratio of the current session’s price change to the average change over a specified number of historical sessions. It colors the chart background based on this ratio using the contents of the colors map and displays the ratio’s value in the Data Window:

//@version=5
indicator("Session change highlighter", overlay = true)

// Inputs
sessionInput = input.session("0800-1700", "Session")
timezone     = input.string("America/New_York", "Timezone")
length       = input.int(10, "Sessions to compare")

//@variable A map of `int` closing time keys and `float` price change values.
var data = map.new<int, float>()
//@variable A map of `string` keys and `color` values for calculating the `highlightColor`.
var colors = map.new<string, color>()

var float sessionOpen    = na
float     relativeChange = na
int       closeTime      = time_close("D", sessionInput, timezone)

// Put (`string`, `color`) pairs into the `colors` map on the first bar.
if barstate.isfirst
    colors.put("Purple", color.new(color.purple, 50))
    colors.put("Orange", color.new(color.orange, 50))
    colors.put("Yellow", color.new(color.yellow, 50))

if not na(closeTime)
    // Update the session's opening price.
    if na(closeTime[1])
        sessionOpen := open

    // Assign a new value to the `closeTime` key in the `data` map.
    data.put(closeTime, math.abs(close - sessionOpen) / sessionOpen)

    //@variable An `array` of price changes from each session in the `data` map.
    sessionHistory = data.values()
    //@variable The number of sessions included in the `data` map.
    dataSize = data.size()

    if dataSize >= length
        //@variable The average price change over `length` sessions.
        avgSessionChange = sessionHistory.slice(dataSize - length, dataSize).avg()
        relativeChange := data.get(closeTime) / avgSessionChange

//@variable Returns a color gradient based on the `relativeChange` using the values in the `colors` map.
highlightColor = switch
    relativeChange <= 1 => color.from_gradient(relativeChange, 0, 1, colors.get("Purple"), colors.get("Orange"))
    =>                     color.from_gradient(relativeChange, 1, 2, colors.get("Orange"), colors.get("Yellow"))

bgcolor(highlightColor, title = "Background highlight")
plot(relativeChange, "Relative Change Ratio", highlightColor, display = display.data_window)

The following publications are examples of scripts using maps:

Volume/Market Profile by SamRecio

Volume Profile by LuxAlgo

Historical Pattern Matcher by Trendoscope

To stay up to date on new Pine Script® features, keep an eye on the User Manual’s Release notes. The PineCoders account also broadcasts updates from its Squawk Box on Telegram, its Twitter account, and from the Pine Script® Q&A public chat on TradingView.

We hope you find this highly-requested feature as useful as we think it’ll be, and please do keep sending us your feedback and suggestions so we can make the platform the best it can be. We build TradingView for you, and we’re always keen to hear your thoughts.

— Team TradingView