Understanding the array.new_linefill() Function in Pine Script

This article provides a comprehensive guide to utilizing the array.new_linefill() function effectively in your Pine Script projects.

Syntax

array.new_linefill(size, initial_value) → array<linefill>

Arguments

• size (series int): Specifies the initial size of the array.
• initial_value (series linefill): Determines the initial value of all array elements.

Returns

The function returns the ID of an array object. This ID is crucial as it is used in other array-related functions to manipulate or access the array elements.

Remarks

• Array indices in Pine Script start from 0, following the convention of many programming languages. This means the first element of an array can be accessed using an index of 0.

Example: Using array.new_linefill()

Let’s consider a practical example to understand how to implement the array.new_linefill() function in Pine Script:

//@version=5
indicator("My Linefill Array Example", overlay=true)

// Define initial parameters
initialSize = 3
start = line.new(x1=bar_index[20], y1=close[20], x2=bar_index, y2=close, width=2, color=color.blue)
end = line.new(x1=bar_index[10], y1=close[10], x2=bar_index, y2=close, width=2, color=color.red)
fillColor = color.new(color.green, 90)
initialLinefill = linefill.new(line1=start, line2=end, color=fillColor)

// Create an array of linefill type
myLinefillArray = array.new_linefill(initialSize, initialLinefill)

// Usage demonstration
if bar_index % 100 == 0
    line1 = line.new(x1=bar_index[15], y1=close[15], x2=bar_index, y2=close, width=2, color=color.purple)
    line2 = line.new(x1=bar_index[5], y1=close[5], x2=bar_index, y2=close, width=2, color=color.orange)
    newFill = linefill.new(line1=line1, line2=line2, color=color.new(color.yellow, 90))
    array.push(myLinefillArray, newFill)

Walkthrough:

1. Script Initialization:
   • //@version=5: Specifies that the script uses version 5 of Pine Script.
   • indicator("My Linefill Array Example", overlay=true): Declares the script as an indicator named “My Linefill Array Example” and overlays its output on the price chart.
2. Initial Parameters Setup:
   • initialSize = 3: Sets the initial size of the linefill array to 3 elements.
   • Lines start and end creation:
     • start: Creates a new line starting 20 bars ago from the current bar and ending at the current bar. This line is styled with a width of 2 and colored blue.
     • end: Creates another line starting 10 bars ago from the current bar and ending at the current bar, with a width of 2 and colored red.
   • fillColor = color.new(color.green, 90): Generates a semi-transparent green color with 90% opacity to fill between the start and end lines.
   • initialLinefill = linefill.new(line1=start, line2=end, color=fillColor): Creates a new linefill object between the start and end lines using the semi-transparent green color.
3. Array of Linefill Type Creation:
   • myLinefillArray = array.new_linefill(initialSize, initialLinefill): Initializes a new array named myLinefillArray with a size of 3, where each element is filled with the initial linefill object created earlier.
4. Usage Demonstration:
   • The if condition checks if the current bar index is a multiple of 100.
   • Inside the if block:
     • line1 and line2 creation:
       • line1: Creates a new line starting 15 bars ago from the current bar to the current bar, styled with a width of 2 and colored purple.
       • line2: Creates another line starting 5 bars ago from the current bar to the current bar, with a width of 2 and colored orange.
     • newFill = linefill.new(line1=line1, line2=line2, color=color.new(color.yellow, 90)): Generates a new linefill object between line1 and line2 with a semi-transparent yellow color.
     • array.push(myLinefillArray, newFill): Adds the new linefill object newFill to the end of the myLinefillArray, dynamically increasing its size by 1 each time this code block executes.

Key Features and Takeaways

• Function Usability: The array.new_linefill() function is specifically designed for creating arrays that store linefill objects, making it easier to manage multiple fills between lines dynamically in a script.
• Syntax and Application: Understanding the syntax and correct application of initial values ensures that the array is initialized correctly and can be manipulated as needed.
• Enhanced Chart Visualization: By using arrays of linefills, you can create complex and dynamic visualizations on your charts, enhancing analysis and decision-making.
• Performance Considerations: Efficient use of arrays and linefills can help manage script performance, especially important in dynamic and data-intensive scripts.