Understanding the array.new_table() Function in Pine Script

The array.new_table() function is a key tool in this domain, allowing script developers to create and manipulate tables dynamically.

Introduction to array.new_table()

The array.new_table() function in Pine Script is designed to create a new array object that holds table type elements. This functionality is particularly useful for scripts that require the display of information in a tabular format directly on the chart.

Syntax

The syntax of the array.new_table() function is as follows:

array.new_table(size, initial_value) → array<table>

Arguments

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

Example

Consider the following example where we create an array of table elements and add a table to it:

//@version=5
indicator("table array demo")
var tableArray = array.new_table()
array.push(tableArray, table.new(position = position.top_left, rows = 1, columns = 2, bgcolor = color.yellow, border_width=1))
plot(1)

Walkthrough of Code

1. //@version=5: Specifies that the script uses version 5 of the Pine Script language, ensuring compatibility and access to the latest features and functionalities.
2. indicator("table array demo"): Declares the script as a custom indicator with the name “table array demo”. This name appears in the indicator list and on the chart when the indicator is added.
3. var tableArray = array.new_table(): Initializes a variable tableArray only once during the indicator’s lifecycle, using the var keyword. The array.new_table() function is called to create a new array that will hold table type elements. Since no arguments are provided, the array is initialized with a default size of 0 and ‘na’ (not available) as the initial value for its elements.
4. array.push(tableArray, table.new(position = position.top_left, rows = 1, columns = 2, bgcolor = color.yellow, border_width=1)): Adds a new table to the tableArray. The table.new() function creates a table with specific properties:
   • position = position.top_left: Sets the table’s position to the top-left corner of the chart.
   • rows = 1: Defines the table to have one row.
   • columns = 2: Specifies the table to have two columns.
   • bgcolor = color.yellow: Sets the background color of the table to yellow.
   • border_width=1: Assigns a border width of 1 to the table.
   The array.push() function is used to add the newly created table to the end of tableArray.
5. plot(1): Plots a constant value of 1 on the chart. This line is not directly related to the table array manipulation but ensures that the indicator displays something on the chart, making it easier to visualize the table’s presence and configuration.

Returns

This function returns the ID of the newly created array object. This ID can be used in other array-related functions to manipulate or access the elements within the array.

Remarks

• Array indexes in Pine Script start from 0. This is a common convention in many programming languages, meaning the first element of an array is accessed with an index of 0.
• The array.new_table() function, combined with other array functions, provides a powerful toolset for creating dynamic and interactive data displays on TradingView charts.

Key Features

• Functionality: Enables dynamic creation and manipulation of table-type arrays in Pine Script.
• Syntax: Straightforward syntax with optional parameters for initial size and value, making it flexible for various use cases.
• Application: Ideal for scripts that require structured data presentation directly on the chart, enhancing the interactivity and informational value of custom indicators and strategies.

Takeaways

• The array.new_table() function is crucial for working with table-type elements in Pine Script, offering significant flexibility in data presentation.
• Understanding and utilizing this function can greatly enhance the visual presentation and informational value of TradingView scripts.
• Remember to consider the initial size and value of the array for optimized script performance and to avoid unnecessary initializations.