Understanding the str.pos() Function in Pine Script

In this article, we’ll delve into the str.pos() function in Pine Script, a powerful tool for string manipulation within the Pine Script programming language. This function is particularly useful for locating substrings within a larger string, a common task in text processing and analysis.

Syntax

The str.pos() function comes with a straightforward syntax that allows it to be utilized in various contexts within Pine Script. This function can be called in three different forms, each returning an integer value representing the position of a specified substring within a given source string. If the substring is not found, the function returns na.

1. Constant Integer Return:

   str.pos(source, substring) → const int

2. Simple Integer Return:

   str.pos(source, substring) → simple int

3. Series Integer Return:

   str.pos(source, substring) → series int

Arguments

• source (const string): This is the main string within which you are searching for the substring.
• substring (const string): This is the sequence of characters you are trying to locate within the source string.

Returns

• Position: The function returns the zero-based index position of the first occurrence of the substring within the source string. If the substring is not found, it returns na.

Remarks

A crucial aspect to remember is that string indexing in Pine Script starts at 0. This means that if your substring is found at the very beginning of the source string, the function will return 0, not 1.

Practical Example

Let’s consider a practical example to see how str.pos() can be applied. Suppose we want to find the position of the substring “code” within the string “Pine Script code is powerful”.

//@version=5
indicator("Find Substring Example", overlay=true)

sourceString = "Pine Script code is powerful"
substring = "code"

position = str.pos(sourceString, substring)

plotchar(position, "Position of Substring", "•", location.top)

In this example, str.pos() will return 12, indicating that the substring “code” starts at the 12th position of the source string (remembering that indexing starts at 0).

Walkthrough of Code

1. Script Declaration and Version:
   • //@version=5: This line specifies that the script is using version 5 of the Pine Script language.
2. Indicator Settings:
   • indicator("Find Substring Example", overlay=true): This line declares a new indicator titled “Find Substring Example”.
3. Defining the Source String:
   • sourceString = "Pine Script code is powerful": Here, a variable named sourceString is defined, holding the string “Pine Script code is powerful”.
4. Defining the Substring:
   • substring = "code": This line defines another variable named substring, containing the string “code”.
5. Finding the Position of the Substring:
   • position = str.pos(sourceString, substring): The str.pos() function is used here to find the first occurrence of substring within sourceString.
6. Plotting the Substring’s Position:
   • plotchar(position, "Position of Substring", "•", location.top): This command uses the plotchar() function to visually mark the position of the substring on the chart. The parameters passed to plotchar() are as follows:
     • position: The variable that holds the position index of the substring. This determines where on the x-axis (time) the character will be plotted.
     • "Position of Substring": A label for the plot, helping identify what this mark represents.
     • "•": The character to be plotted. In this case, a bullet point (•) is used as the marker.
     • location.top: This specifies the vertical location of the plot. location.top places the marker at the top of the chart pane.

Key Features

• Versatility: The str.pos() function supports constant, simple, and series integer returns, making it adaptable for a range of scenarios in Pine Script programming.
• Zero-based Indexing: It uses zero-based indexing, aligning with common programming conventions and ensuring consistency across string manipulation functions in Pine Script.
• Search Efficiency: It provides a straightforward method to locate the presence and position of substrings within larger strings, enhancing text analysis capabilities within Pine Script.

Takeaways

• The str.pos() function is essential for substring search operations in Pine Script.
• It offers three overloads to accommodate different programming needs.
• Understanding zero-based indexing is crucial for interpreting the results accurately.
• This function enriches Pine Script’s text processing and manipulation capabilities, opening up possibilities for advanced analysis and strategy development.

By mastering str.pos() and other string manipulation functions, Pine Script programmers can efficiently perform text analysis, data parsing, and dynamic label creation, further enhancing their trading strategies and analysis tools.