Arrays

Introduction

Arrays can be used to store multiple values in one data structure. Think of them as a better way to handle cases where you would otherwise need a set of variables named price00, price01 and price02. Arrays are an advanced feature used for scripts requiring intricate data-handling. If you are a beginning Pine programmer, we recommend you become familiar with other, more accessible Pine features before you tackle arrays.

Pine arrays are one-dimensional. All elements of an array are of the same type, which can be int, float, bool or color, always of series form. Arrays are referenced using an array id, similar to label and line id’s. Pine does not use an indexing operator to reference individual array elements; instead, functions like array.get() and array.set() are used to read and write values of array elements. Array values can be used in all Pine expressions and functions where a value of series form is allowed.

Elements within an array are referred to using an index, which starts at 0 and extends to the number or elements in the array, minus one. Arrays in Pine can be sized dynamically, so the number of elements in the array can be modified within one iteration of the script on a bar, and vary across bars. Multiple arrays can be used in the same script. The size of arrays is limited to 100,000.

Declaring arrays

The following syntax can be used to declare arrays:

    <type>[] <identifier> = <expression>
    var <type>[] <identifier> = <expression>

The [] modifier is appended to the type name when declaring arrays. However, since type-specific functions are always used to create arrays, the <type>[] part of the declaration is redundant, except if you initialize an array variable to na, as in the following example where we declare an array variable named prices. The variable will be used to designate an array containing float values, but no array is created by this declaration yet. For the moment, the array variable contains no valid array id, its value being na:

    float[] prices = na

When declaring an array and the <expression> is not na, one of the array.new_<type>(size, initial_value) functions must be used. The arguments of both the size and initial_value parameters can be series, to allow dynamic sizing and initialization of array elements. The following example creates an array containing zero float elements, and this time, the array id returned by the array.new_float() function call is assigned to prices:

Similar array creation functions exist for the other types of array elements: array.new_int(), array.new_bool(), array.new_color(), array.new_line(), array.new_label() and array.new_string().

When declaring an array, you can initialize all elements in the array using the initial_value parameter. When no argument is supplied for initial_value, the array elements are initialized to na. The following declaration creates and array id named prices. The array is created with two elements, each initialized with the value of the close built-in variable on that bar:

There is currently no way to initialize multiple array elements with different values in one statement, whether upon declaration or post-declaration. One is planned in the near future.

Using the ‘var’ keyword

The var keyword can be used when declaring arrays. It works just as it does for other variables; it causes the declaration to only be executed on the first iteration of the script on the dataset’s bar at bar_index zero. Because the array is never re-initialized on subsequent bars, its value will persist across bars, as the script iterates on them.

When an array declaration is done using var and a new value is pushed at the end of the array on each bar, the array will grow by one on each bar and be of size bar_index plus one (bar_index starts at zero) by the time the script executes on the last bar, as this code will do:

The same code without the var keyword would re-declare the array on each bar. After execution of the array.push() call, the array would thus be of size one on all the dataset’s bars.

Reading and writing array values

Values can be written to existing individual array elements using array.set(id, index, value), and read using array.get(id, index). As is the case whenever an array index is used in your code, it is imperative that the index never be greater than the array’s size, minus one (because array indices start at zero). You can obtain the size of an array by using the array.size(id) function.

The following example uses array.set() to initialize an array of colors to instances of one base color using different transparency levels. It then fetches the proper array element to use it in a bgcolor() call:

Another technique that can be used to initialize the elements in an array is to declare the array with size zero, and then populate it using array.push() to append new elements to the end of the array, increasing the size of the array by one at each call. The following code is functionally identical to the initialization section from the preceding script. Note that we do not use var to declare the array in this case. If we did, the set of pushes would add 5 new elements to the array on each bar, since the array would propagate over successive bars:

The array.fill(id, value, index_from, index_to) function can be used to fill contiguous sets of array elements with a value. Used without the last two optional parameters, the function fills the whole array, so:

and:

are equivalent, but:

only fills the second and third elements (at index 1 and 2) of the array with close. Note how array.fill()‘s last parameter, index_to, needs to be one greater than the last index to be filled. The remaining elements will hold the na value, as no intialization value was provided when the array was declared.

Scope

Arrays can be declared in a script’s global scope, as well as in the local scope of a function or an if branch. One major distinction between Pine arrays and variables declared in the global scope, is that global arrays can be modified from within the local scope of a function. This new capability can be used to implement global variables that can be both read and set from within any function in the script. We use it here to calculate progressively lower or higher levels:

History referencing

Past instances of array id’s or elements cannot be referenced directly using Pine’s [ ] history-referencing operator. One cannot write: array.get(a[1], 0) to fetch the value of the array’s first element on the previous bar.

In Pine, however, each call to a function leaves behind a series trail of function results on previous bars. This series can in turn be used when working with arrays. One can thus write: ma = sma(array.get(a, 0), 20) to calculate the simple moving average of the value returned by the array.get(a, 0) call on the last 20 bars.

To illustrate this, let’s first see how we can fetch the previous bar’s close value in two, equivalent ways. For previousClose1 we use the result of the array.get(a, 0) function call on the previous bar. Since on the previous bar the array’s only element was initialized to that bar’s close (as it is on every bar), referring to array.get(a, 0)[1] returns that bar’s close, i.e., the value of the array.get(a, 0) call on the previous bar.

For previousClose2 we use the history-referencing operator to fetch the previous bar’s close in normal Pine fashion:

In the following example we add two, equivalent calculations of a moving average to our previous code example. For ma1 we use sma() on the series of values returned by the array.get(a, 0) function call on each bar. Since at this point in the script the call returns the current bar’s close, that is the value used for the average’s calculation. We evaluate ma2 using the usual way we would calculate a simple average in Pine:

Notice the last line of this script. It illustrates how even if we set the value of the array’s element to 10.0 at the end of the script, resulting in the final value for the element being committed as 10.0 on the bar’s last execution of the script, the earlier call to array.get(a, 0) nonetheless returned the close value because that was the value of the array element at that point in the script. The series value of the function call will thus be each bar’s close value.

Inserting and removing array elements

Inserting

Three functions can be used to insert new elements in an array.

array.unshift() inserts a new element at the beginning of an array, at index zero, and shifts any existing elements right by one.

array.insert() can insert a new element at any position in the array. Its index parameter is the index where the new element will be added. The element existing at the index used in the function call and any others to its right are shifted one place to the right:

array.push() will add a new element at the end of an array.

Removing

Four functions can be used to remove elements from an array. The first three will return the value of the removed element.

array.remove() removes the element at the index value used, and returns that element’s value.

array.shift() removes the first element from an array and returns its value.

array.pop() removes the last element of an array and returns its value.

array.clear() will remove all elements in the array.

Using an array as a stack

Stacks are LIFO (last in, first out) constructions. They behave somewhat like a vertical pile of books to which books can only be added or removed one at a time, always from the top. Pine arrays can be used as a stack, in which case you will use the array.push() and array.pop() functions to add and remove elements at the end of the array.

array.push(prices, close) will add a new element to the end of the prices array, increasing the array’s size by one.

array.pop(prices) will remove the end element from the prices array, return its value and decrease the array’s size by one.

See how the functions are used here to remember successive lows in rallies:

Using an array as a queue

Queues are FIFO (first in, first out) constructions. They behave somewhat like cars arriving at a red light. New cars are queued at the end of the line, and the first car to leave will be the first one that arrived to the red light.

In the following code example, we let users decide through the script’s inputs how many labels they want to have on their chart. We use that quantity to determine the size of the array of labels we then create, initializing the array’s elements to na.

When a new pivot is detected, we create a label for it, saving the label’s id in the pLabel variable. We then queue the id of that label by using array.push() to append the new label’s id to the end of the array, making our array size one greater than the maximum number of labels to keep on the chart.

Lastly, we de-queue the oldest label by removing the array’s first element using array.shift() and deleting the label referenced by that array element’s value. As we have now de-queued an element from our queue, the array contains i_pivotCount elements once again. Note that on the dataset’s first bars we will be deleting na label id’s until the maximum number of labels has been created, but this does not cause runtime errors. Let’s look at our code:

Calculations on arrays

While series variables can be viewed as a horizontal set of values stretching back in time, Pine’s one-dimensional arrays can be viewed as vertical structures residing on each bar. As an array’s set of elements is not a series, Pine’s usual mathematical functions are not allowed on them. Special-purpose functions must be used to operate on all of an array’s values. The available functions are: array.avg(), array.min(), array.max(), array.median(), array.mode(), array.standardize(), array.stdev(), array.sum(), array.variance(), array.covariance(), array.range().

Note that contrary to the usual mathematical functions in Pine, those used on arrays do not return na when some of the values they calculate on have na values. There are a few exceptions to this rule:

• When all array elements have na value or the array contains no elements, na is returned. array.standardize() however, will return an empty array.
• array.mode() will return na when no mode is found.

Manipulating arrays

Concatenation

Two arrays can be merged---or concatenated---using array.concat(). When arrays are concatenated, the second array is appended to the end of the first, so the first array is modified while the second one remains intact. The function returns the array id of the first array:

Copying

You can copy an array using array.copy(). Here we copy the array a to a new array named _b:

Note that simply using _b = a in the previous example would not have copied the array, but only its id. From thereon, both variables would point to the same array, so using either one would affect the same array.

Joining

Use array.join to concatenate all of the elements in the array into a string and separate these elements with the specified separator:

Sorting

Arrays can be sorted in either ascending or descending order using array.sort(). The order parameter is optional and defaults to order.ascending. As all array.*() function arguments, it is of form series, so can be determined at runtime, as is done here. Note that in the example, which array is sorted is also determined at runtime:

Reversing

Use array.reverse() to reverse an array:

Slicing

Slicing an array using array.slice() creates a shallow copy of a subset of the parent array. You determine the size of the subset to slice using the index_from and index_to parameters. The index_to argument must be one greater than the end of the subset you want to slice.

The shallow copy created by the slice acts like a window on the parent array’s content. The indices used for the slice define the window’s position and size over the parent array. If, as in the example below, a slice is created from the first three elements of an array (indices 0 to 2), then regardless of changes made to the parent array, and as long as it contains at least three elements, the shallow copy will always contain the parent array’s first three elements.

Additionally, once the shallow copy is created, operations on the copy are mirrored on the parent array. Adding an element to the end of the shallow copy, as is done in the following example, will widen the window by one element and also insert that element in the parent array at index 3. In this example, to slice the subset from index 0 to index 2 of array a, we must use _sliceOfA = array.slice(a, 0, 3):

Searching arrays

We can test if a value is part of an array with the array.includes() function, which returns true if the element is found. We can find the first occurrence of a value in an array by using the array.indexof() function. The first occurence is the one with the lowest index. We can also find the last occurrence of a value with array.lastindexof():

Error handling

Malformed array.*() call syntax in Pine scripts will cause the usual compiler error messages to appear in Pine Editor’s console, at the bottom of the window, when you save a script. Refer to the Pine Reference Manual when in doubt regarding the exact syntax of function calls.

Scripts using arrays can also throw runtime errors, which appear in place of the indicator’s name on charts. We discuss those runtime errors in this section.

Index xx is out of bounds. Array size is yy

This will most probably be the most frequent error you encounter. It will happen when you reference an inexistent array index. The “xx” value will be the value of the faulty index you tried to use, and “yy” will be the size of the array. Recall that array indices start at zero---not one---and end at the array’s size, minus one. An array of size 3’s last valid index is thus 2.

To avoid this error, you must make provisions in your code logic to prevent using an index lying outside of the array’s index boundaries. This code will generate the error because the last index we use in the loop is outside the valid index range for the array:

The correct for statement is:

    for _i = 0 to 2

When you size arrays dynamically using a field in your script’s Settings/Inputs tab, protect the boundaries of that value using input()‘s minval and maxval parameters:

Cannot call array methods when id of array is ‘na’

When an array id is initialized to na, operations on it are not allowed, since no array exists. All that exists at that point is an array variable containing the na value rather that a valid array id pointing to an existing array. Note that an array created with no elements in it, as you do when you use a = array.new_int(0), has a valid id nonetheless. This code will throw the error we are discussing:

To avoid it, create an array with size zero using:

    int[] a = array.new_int(0)

or:

    a = array.new_int(0)

Array is too large. Maximum size is 100000

This error will appear if your code attempts to declare an array with a size greater than 100,000. It will also occur if, while dynamically appending elements to an array, a new element would increase the array’s size past the maximum.

Cannot create an array with a negative size

We haven’t found any use for arrays of negative size yet, but if you ever do, we may allow them )

Cannot use [shift()] if array is empty.

This error will occur if array.shift() is called to remove the first element of an empty array.

Cannot use [pop()] if array is empty.

This error will occur if array.pop() is called to remove the last element of an empty array.

Index ‘from’ should be less than index ‘to’

When two indices are used in functions such as array.slice(), the first index must always be smaller than the second one.

Slice is out of bounds of the parent array

This message occurs whenever the parent array’s size is modified in such a way that it makes the shallow copy created by a slice point outside the boundaries of the parent array. This code will reproduce it because after creating a slice from index 3 to 4 (the last two elements of our five-element parent array), we remove the parent’s first element, making its size four and its last index 3. From that moment on, the shallow copy which is still poiting to the “window” at the parent array’s indices 3 to 4, is pointing out of the parent array’s boundaries: