Understanding the array.binary_search_leftmost Function in Pine Script

One of the powerful features it offers is the array.binary_search_leftmost function. This function can be a handy tool when dealing with sorted arrays, offering an efficient method to locate a specific value or determine where a value should be inserted to maintain the array’s sorted order.

Syntax and Arguments

The syntax for this function is quite straightforward:

array.binary_search_leftmost(id, val) → series int

• id (float[]): This is the array object that you want to search. It must be sorted in ascending order for the binary search to work correctly.
• val (series int/float): This is the value that you’re searching for within the array.

How It Works

The array.binary_search_leftmost function employs the binary search algorithm to find the position of a specified value within a sorted array. If the value is found, the function returns the index of the value. When the value is not found, it returns the index of the next smallest element to the left of where the value would lie if it was in the array.

Example

Consider the following piece of code:

//@version=5
indicator("array.binary_search_leftmost Example")
a = array.from(5, -2, 0, 9, 1)
array.sort(a)
position = array.binary_search_leftmost(a, 3)
plot(position)

Here, we initialize an array a with five integers. We then sort the array in ascending order using the array.sort(a) function, after which we use the array.binary_search_leftmost(a, 3) function to find the position where the number 3 should be in the sorted array. The plot(position) function is then used to plot the position on the chart.

A Unique Use Case

Now, let’s explore another unique example to understand the practical utility of this function. Suppose we are dealing with a series of price data, and we want to determine the position of a specific price level within a sorted array of historical price levels.

//@version=5
indicator("Finding Price Level Position", overlay = true)
priceLevels = array.new_float(0)
for i = 0 to 99
    array.push(priceLevels, close[i])
array.sort(priceLevels)

targetPrice = close[0]
position = array.binary_search_leftmost(priceLevels, targetPrice)
bgcolor(position == 0 ? color.red : na)

plotshape(series=position == 0, style=shape.labeldown, location=location.abovebar, color=color.red, title="Target Price at Lowest Level")

Explanation:

1. We initialize an empty float array named priceLevels to store the historical price levels.
2. We populate this array with the closing prices of the last 100 bars on the chart using a for loop and the array.push() function.
3. The array.sort(priceLevels) function is then used to sort this array in ascending order.
4. We specify a targetPrice, which is the current bar’s closing price, and search for its position within the sorted priceLevels array using the array.binary_search_leftmost() function.
5. We use the bgcolor() function to change the background color to red if the targetPrice is the lowest price level within the sorted array.
6. We also use the plotshape() function to plot a shape on the chart whenever the targetPrice is at its lowest level, for visual indication.

Key Takeaway

The array.binary_search_leftmost function is not just for finding the exact index of a value in a sorted array; it’s also a powerful tool for determining where a value should be inserted to maintain the sorted order of the array. This can be particularly useful in scenarios where you need to quickly assess the relative position of a new value within a sorted dataset, such as identifying whether a current price level is at, above, or below historical levels.

Conclusion

Mastering the array.binary_search_leftmost function can significantly enhance your Pine Script coding skills, especially when dealing with sorted arrays. It offers a swift and efficient method to not only locate specific values but also to analyze and visualize data in the context of its sorted order. By understanding and utilizing this function effectively, you can derive valuable insights from your data and improve the quality of your trading indicators and strategies on the TradingView platform.