Understanding str.format() Function in Pine Script

This tutorial will guide you through using str.format() in Pine Script version 5, providing a comprehensive understanding of its functionality, syntax, and application in financial charting scripts.

Introduction to str.format()

str.format() is a function designed to format strings in a more flexible and readable manner. It allows the insertion of variable values into a string template, making it easier to generate dynamic text messages, labels, or annotations on charts. This function is particularly useful for displaying custom text that includes variable data, such as prices, indicator values, or dates.

Syntax of str.format()

The basic syntax of str.format() in Pine Script version 5 is as follows:

formattedString = str.format("Template text {0} more text {1}", variable1, variable2)

• "Template text {0} more text {1}" is the string template where {0}, {1}, etc., are placeholders for variables.
• variable1, variable2, etc., are the variables whose values you want to insert into the string at the placeholders’ positions.

Example Usage

Let’s consider an example where we want to display the current price along with a simple moving average (SMA) value on a chart:

//@version=5
indicator("Price and SMA Label", overlay=true)
price = high
smaValue = ta.sma(close, 20)
labelText = str.format("Current Price: {0}\n20-period SMA: {1}", price, smaValue)
label.new(bar_index, price, labelText, xloc.bar_index, yloc.price, size=size.normal)

In this example:

• We calculate the current price (price) and the 20-period SMA (smaValue).
• We then format a string (labelText) to include these values using str.format().
• Finally, we create a new label on the chart that displays this formatted string.

Detailed Explanation of Each Line

1. indicator("Price and SMA Label", overlay=true): Defines a new indicator with the name “Price and SMA Label” that will be drawn over the main chart (overlay=true).
2. price = close: Assigns the current closing price to the variable price.
3. smaValue = ta.sma(close, 20): Calculates the 20-period Simple Moving Average of the closing prices and assigns it to smaValue.
4. labelText = str.format("Current Price: {0}\n20-period SMA: {1}", price, smaValue): Creates a formatted string with the current price and SMA value inserted into the template.
5. label.new(bar_index, price, labelText, xloc.bar_index, yloc.price, size=size.normal): Creates a new label on the chart that displays the labelText at the current bar’s index and the price level.

Key Features and Takeaways

• Flexibility in Text Formatting: str.format() allows the inclusion of variable values within a string dynamically, making it easier to create informative labels or annotations.
• Enhanced Readability: The use of placeholders ({0}, {1}, etc.) in the string template improves the readability and maintainability of the code, especially when dealing with multiple variables.
• Application in Financial Charting: This function is invaluable for displaying dynamic information, such as indicator values or prices, directly on financial charts, enhancing the analytical capabilities of trading strategies.