Understanding the array.new_box() Function in Pine Script

In this tutorial, we delve into the array.new_box() function in Pine Script, a crucial tool for developers working with dynamic data structures, particularly when dealing with graphical objects like boxes on TradingView charts. We’ll break down its syntax, arguments, and provide a practical example to illustrate its application.

Syntax and Arguments

The array.new_box() function is designed to create a new array object that can hold elements of the box type. Its syntax is as follows:

array.new_box(size, initial_value) → array<box>

Let’s dissect the parameters:

• size (series int): Specifies the initial size of the array. This argument is optional, with a default value of 0.
• initial_value (series box): Determines the initial value for all elements of the array. This too is optional, with a default being ‘na’ (not applicable).

Example

To better understand how to use array.new_box(), let’s analyze a simple example:

//@version=5
indicator("array.new_box example")
container = array.new_box()
array.push(container, box.new(time, close, time+2, low, xloc=xloc.bar_time))
plot(1)

Line-by-Line Explanation:

1. Indicator Declaration: Begins with specifying the script version and declaring the script as an indicator with the title “array.new_box example”.
2. Array Creation: Initializes an empty array named container using array.new_box(). Since no arguments are provided, it creates an empty array of box type elements.
3. Adding a Box to the Array: Utilizes array.push() to add a new box to container. The box is created with box.new(), which requires parameters for position and dimensions:

• The box’s starting point on the x-axis is time, and its ending point is time+2, creating a box that spans over two bars.
• The vertical dimensions are set from close to low, meaning the box’s height varies based on the closing and lowest price of the current bar.
• xloc.bar_time is used to ensure the box is positioned according to the bar’s time on the x-axis.

1. Plot Statement: Simply plots a constant value of 1 to ensure the indicator has graphical output. This is unrelated to the array but necessary for the script to display on the chart.

Returns

The function returns the ID of the newly created array object. This ID can then be used with other array functions (array.*()) to manipulate or access the array’s elements.

Key Features and Takeaways

• Function Usability: array.new_box() is invaluable for creating dynamic arrays that store graphical objects, enabling complex data visualizations and manipulations on TradingView charts.
• Syntax and Application: The function’s flexible syntax allows for initializing arrays with specific sizes and values, though both parameters are optional.
• Practical Example: The provided example showcases a basic use case—initializing an empty array and adding a single box to it, demonstrating the function’s integration with graphical elements in Pine Script.

By understanding and utilizing array.new_box(), developers can enhance their trading strategies and indicators with dynamic, graphical data structures, opening up new possibilities for analysis and visualization on TradingView.