December 23, 2021

New in Pine: overloads, new string functions, and more!

The Pine team has been working hard to continue to improve Pine since the v5 rollout. Let’s go over some of the long-awaited features they’ve added during the past two months.

Function overloads

Function overloads are variations of a function that can be defined in a library or included in a script. Overloads share the same name as the original function, but use different quantities of parameters, or parameters of different types. They are especially useful in libraries, where parameter types are mandatory.

In this indicator, we define an overload of the mult() function that accepts three arguments:

//@version=5
indicator("Function overload")

// Two parameters
mult(x1, x2) =>
    x1 * x2

// Three parameters
mult(x1, x2, x3) =>
    x1 * x2 * x3

plot(mult(7, 4))
plot(mult(7, 4, 2))

Here, we define overloads that operate differently, depending on the type of arguments used. When overloads have the same quantity of parameters as the original function, parameters must be defined using different, explicit types:

//@version=5
indicator("Function overload")

// Accepts both 'int' and 'float' values because any 'int' can be automatically cast to 'float'
mult(float x1, float x2) =>
    x1 * x2

// Returns a 'bool' value instead of a number
mult(bool x1, bool x2) =>
    x1 and x2 ? true : false

mult(string x1, string x2) =>
    str.tonumber(x1) * str.tonumber(x2)

// Has three parameters, so explicit types are not required
mult(x1, x2, x3) =>
    x1 * x2 * x3

plot(mult(7, 4))
plot(mult(7.5, 4.2))
plot(mult(true, false) ? 1 : 0)
plot(mult("5", "6"))
plot(mult(7, 4, 2))

for…in

Iterating over an array with the for structure requires preventing loop entry if the array is empty and protecting against an out-of-bounds array index.

The new for…in structure makes your life easier by iterating over all the elements of an array for you. The syntax is simple: for array_element in array_id will iterate over the elements of array_id starting from index zero, assigning the value of the array’s element to the array_element variable on each iteration. No iteration or error will occur if the array is empty, and array elements can be added or removed in loop iterations.

In the script below, we use for…in to find the highest number in the a1 array:

//@version=5
indicator("For...in cycle")
var int[] a1 = array.from(1, 3, 6, 3, 8, 0, -9, 5)

highest(array) =>
    var int highestNum = na
    for element in array
        if na(highestNum) or element > highestNum
            highestNum := element
    highestNum

plot(highest(a1))

New string-manipulation functions

These new functions provide more ways to process strings, and introduce regular expressions to Pine. Note that, contrary to user-defined string functions using arrays, they can return values of “simple” form, which one can use to create symbol arguments for request.security(), for example.

str.contains(source, str)

Determines if the source string contains the str substring. For example, we can determine if the current chart is a continuous futures chart by looking for the “!” substring in the syminfo.tickerid built-in variable:

var isContinuous = str.contains(syminfo.tickerid, "!")  
plot(isContinuous ? 1 : 0)

str.pos(source, str)

Returns the position of the str string in the source string.

str.substring(source, begin_pos, end_pos)

Extracts a substring from the source string. In this example we use str.substring() and str.pos() to fetch the “AAPL” substring from the s input string:

s = input.string("Time to sell some NASDAQ:AAPL") 
pos = str.pos(s, ":")  // Get the position of the ":" character
tkr = str.substring(s, pos + 1) // "AAPL"

str.replace(source, target, replacement, occurrence)

Contrary to the existing str.replace_all() function, str.replace() allows the selective replacement of a matched substring with a replacement string. In this example, we are replacing the “FTX” prefix with “BINANCE” for the first symbol in the spread string:

var source = "FTX:BTCUSD / FTX:BTCEUR"
// Replace the first occurrence of "FTX" with the "BINANCE" replacement string
var newSource = str.replace(source, "FTX",  "BINANCE", 0)

str.lower(source) and str.upper(source)

Converts all letters of the source string to lower or upper case:

s = str.lower("Time to Sell Some AAPL") // time to sell some aapl!
s = str.upper("Time to Sell Some AAPL!") // TIME TO SELL SOME AAPL!

str.startswith(source, str) and  str.endswith(source, str)

Determines if the source string starts or ends with the str substring.

str.match(source, regex)

Extract the substring matching the specified regular expression. For example, with regex [\\w]+:[\\w]+ it is possible to find and return the symbol name from the “It’s time to sell some NASDAQ:AAPL!” source string:

s = "It's time to sell some NASDAQ:AAPL!"
var string tickerId = str.match(s, "[\\w]+:[\\w]+") //"NASDAQ:AAPL"

Currency Conversion

Most functions in the request.* namespace can now convert the values they return in another currency. If the currency argument is specified in the function call, price values returned by the function will be converted from the source currency to the target currency. The currency parameter was added to the following functions:

Textboxes

The box drawing in Pine now supports text! Just add the text argument to the box.new() function whenever you draw the box and the text will be displayed inside it. You can finetune the behavior of the text by setting the values for the text_size, text_color, text_valign, and text_halign parameters when you create the box, or by referring to the box with one of the following new functions:

As an example of this feature, here’s the built-in Multi-Time Period Charts indicator modified to display the number and the high/low of the week that it highlights:

To stay informed of new Pine features, keep an eye on our Pine User Manual’s Release notes. Our PineCoders also broadcast updates on the Squawk Box Telegram channel, Twitter, and from the Pine Script public chat on TradingView.

We hope you find these highly-requested features useful. Please keep giving us your feedback and suggestions for improvement. We build TradingView for you, and we’re always keen to hear from you.

Look first / Then leap

Launch Chart