Array.unshift Function in Pine Script

One of the integral functions in Pine Script is the array.unshift function, which allows developers to insert values at the beginning of an array. In this blog post, we’ll take an in-depth look at this function, its syntax, and how to use it effectively in your code.

Introduction to Arrays in Pine Script

Before we dive into the specifics of the array.unshift function, it’s crucial to understand what arrays are and their role in Pine Script.

What are Arrays?

Arrays are data structures that store multiple values in a single variable. They are particularly useful when dealing with a series of related data. In Pine Script, arrays can hold different types of values such as integers, floats, bools, colors, and lines.

The array.unshift Function

Now that we have a basic understanding of arrays, let’s delve into the array.unshift function.

Syntax and Arguments

The array.unshift function has the following syntax:

array.unshift(id, value)

This function takes two arguments:

id (any array type) – This is an array object where you want to insert the value.
value (series <type of the array’s elements>) – This is the value that you want to add to the start of the array.

This function returns void, meaning it doesn’t return any value but modifies the array directly.

Unique Use Case Example

//@version=5
indicator("Array.unshift Example - High Prices", overlay=true)

highPrices = array.new_float(5)  // Create an array of 10 floats, initialized to na

if barstate.isconfirmed  // If the bar is confirmed...
    array.unshift(highPrices, high)  // Insert the high price at the beginning of the array
    array.pop(highPrices)  // Remove the last element to keep the array size constant
    array.unshift(highPrices, high[1])
    array.pop(highPrices)  // Remove the last element to keep the array size constant
    array.unshift(highPrices, high[2])
    array.pop(highPrices)  // Remove the last element to keep the array size constant
    array.unshift(highPrices, high[3])
    array.pop(highPrices)  // Remove the last element to keep the array size constant
    array.unshift(highPrices, high[4])  
    array.pop(highPrices)  // Remove the last element to keep the array size constant  


plot(array.get(highPrices, 0), "High Price 0", color=color.green)
plot(array.get(highPrices, 1), "High Price 1", color=color.blue)
plot(array.get(highPrices, 2), "High Price 2", color=color.red)
plot(array.get(highPrices, 3), "High Price 3", color=color.purple)
plot(array.get(highPrices, 4), "High Price 4", color=color.orange)
// Continue plotting for the rest of the array elements...
label newLable = na
if barstate.islast
    newLable := label.new(x=bar_index, y=high, style=label.style_label_left, 
     color=#E6E6FA, textcolor=color.black, size=size.large, 
     text="Highs Array =  " + str.tostring(highPrices))
label.delete(newLable[1])

In this example:

highPrices = array.new_float(5, na): We’re creating a new array highPrices of ten float elements, all initialized to na.
if barstate.isconfirmed: This checks if the current bar is confirmed.
array.unshift(highPrices, high): If the bar is confirmed, we use the array.unshift function to add the high price of the bar at the beginning of the array highPrices.
array.pop(highPrices): To keep the array size constant at 5, we remove the last element of the array after inserting a new value at the beginning.
The plot function is used to display the high prices stored in the array on the chart. The array.get(highPrices, 0) fetches the first element of the array (the most recent high price), and we plot this with a green color. We repeat this for the remaining elements of the array, each with a different color.

This example shows how you can use array.unshift to keep track of the high prices of the last 5 bars. Such usage can be particularly useful in trading strategies that rely on historical price data.

Key Takeaways

Here are the crucial points to remember about the array.unshift function in Pine Script:

The array.unshift function is used to insert a value at the beginning of an array.
The syntax for this function is array.unshift(id, value), where id is the array object and value is the value to be added.
This function modifies the array directly and doesn’t return any value.
The array size remains constant after using the array.unshift function. If you want to keep a fixed array size, you should remove the last element after inserting at the beginning.
The array.unshift function can be used with any array type in Pine Script.

Conclusion

The array.unshift function is a powerful tool in Pine Script, allowing you to efficiently manage and manipulate arrays in your code. With a proper understanding of this function, you can handle arrays effectively, making your trading algorithms more sophisticated and robust.

Always remember that arrays in Pine Script, like in many other programming languages, are zero-indexed, which means the first element is at index 0. Therefore, when using array.unshift, the new element will be at index 0.

Hopefully, this tutorial provided you with a clear understanding of the array.unshift function and its usage. Happy coding!