Understanding the array.binary_search_rightmost() Function in Pine Script

In this article, we delve into the array.binary_search_rightmost() function in Pine Script, a powerful tool designed for technical analysis and financial charting. This function plays a critical role in optimizing searches within arrays, especially when working with sorted data in ascending order. Our focus will be on understanding its syntax, application, and the subtleties of its behavior with practical examples.

Syntax and Arguments

The array.binary_search_rightmost() function follows a straightforward syntax:

array.binary_search_rightmost(id, val) → series int

Parameters:

• id (array<int/float>): Specifies the array object in which the search is to be conducted. This array must be pre-sorted in ascending order for the function to operate correctly.
• val (series int/float): Denotes the value that the function attempts to locate within the array.

How It Works

This function is designed to return the index of the specified value if found within the array. However, its unique utility shines when the specified value is absent from the array. In such cases, instead of returning a null or undefined value, it provides the index of the element immediately to the right of where the missing value would theoretically be placed if it were part of the array. This behavior ensures that the function always returns a meaningful value, aiding in decision-making processes within scripts.

Practical Examples

Example 1: Searching for a Non-Existent Element

Let’s explore the function through an illustrative example:

//@version=5
indicator("Find Position with binary_search_rightmost")
numList = array.from(5, -2, 0, 9, 1)
array.sort(numList) // Sorts the array to [-2, 0, 1, 5, 9]
targetPosition = array.binary_search_rightmost(numList, 3) // Returns 3
plot(targetPosition)

Walkthrough of Code

1. Declaration of numList Array: An array named numList is created with the elements [5, -2, 0, 9, 1]. This array contains a mix of positive and negative integers in no particular order.
2. Sorting the Array: The array.sort(numList) function is called to sort the array in ascending order. After sorting, the array becomes [-2, 0, 1, 5, 9]. Sorting is a prerequisite for performing a binary search since binary search algorithms rely on the array being sorted to efficiently find elements or their appropriate positions.
3. Binary Search for Rightmost Position: The function array.binary_search_rightmost(numList, 3) is used to find the rightmost position where the number 3 could be inserted into the sorted array without breaking its order. The binary search algorithm quickly narrows down the search space by comparing the target value (3 in this case) with the middle element of the array and then repeatedly narrowing the search to the left or right half of the array until the correct position is found.
4. Return Value – targetPosition: The function returns 3, which is stored in the variable targetPosition. This value represents the index position where 3 could be inserted in the sorted array [-2, 0, 1, 5, 9]. The index 3 is correct because 3 would come after 1 (at index 2) and before 5 (at index 3) in the sorted array, maintaining the sorted order.
5. Plotting targetPosition: The plot(targetPosition) statement suggests plotting the found position (3 in this case) on a graph. This could be useful for visualizing where the target number would fit within the sorted array, although the specific implementation of the plot function is not detailed here.

Example 2: Handling Repetitive Elements

//@version=5
indicator("Find Rightmost in Repetitive")
valueArray = array.from(4, 5, 5, 5) // An array with repetitive elements
// Searches for the rightmost occurrence of '5'
lastPosition = array.binary_search_rightmost(valueArray, 5) 
plot(lastPosition) // Plots 3

Walkthrough of Code

1. Initialize valueArray: Creates an array [4, 5, 5, 5] with repetitive elements.
2. Find Rightmost Occurrence: Uses array.binary_search_rightmost(valueArray, 5) to find the index of the rightmost occurrence of 5 in the array.
3. Result: The function returns 3, indicating the rightmost 5 is at the fourth position (index 3, considering zero-based indexing).
4. Plot Result: plot(lastPosition) plots the index 3 on a graph, visualizing the position of the rightmost 5.

Remarks and Key Takeaways

• The array.binary_search_rightmost() function is an efficient tool for working with sorted arrays, leveraging the binary search algorithm’s power to minimize search times.
• It uniquely provides valuable index information even when the searched value is not present in the array, enhancing its utility in various scripting scenarios.
• Remember, for the function to work correctly, the array must be sorted in ascending order prior to calling the function.

By incorporating this function into your Pine Script toolbox, you can significantly enhance data searching and decision-making processes in your trading strategies. Its ability to handle both exact matches and hypothetical placements makes it indispensable for data-driven financial analysis.