str.tostring function in Pine Script

Pine Script, the language that powers the TradingView platform, comes with a host of built-in functions to facilitate technical analysis, one of which is the versatile str.tostring() function. This function converts different data types to string format, offering a convenient method of manipulating and displaying data.

Understanding str.tostring()

Syntax

The str.tostring() function has two different syntaxes:

str.tostring(value) → series string
str.tostring(value, format) → series string

In the first form, the function simply takes a value argument and returns its string representation. In the second form, an additional format argument can be specified to control how the output string is formatted.

Returns

The function returns the string representation of the provided value argument. If the value is already a string, it is returned as is. If the value is na, the function returns the string “NaN”.

<h3>Arguments</h3>

The value argument can be of various types – int, float, bool, string, matrix, or array. The format argument is a string that accepts these format.* constants: format.mintick, format.percent, format.volume.

<h2>Key Properties of str.tostring()</h2>

For float values, the function rounds them as necessary. For instance, str.tostring(3.99, '#') will return “4”.
To display trailing zeros, use ‘0’ instead of ‘#’. For example, str.tostring(3.99, '#.000') will return “4.000”.
When using format.mintick, the value will be rounded to the nearest number that can be divided by syminfo.mintick without the remainder.
If the value argument is a string, the same string value will be returned.
Bool type arguments return “true” or “false”.
When the value is na, the function returns “NaN”.

Usage of str.tostring()

Example

Let’s dive into a practical example:

//@version=5
indicator("My Script", overlay=true)
value = close
s = str.tostring(value, format.mintick)
plot(value)
label.new(x=bar_index, y=value, text=s , size = size.large)

Code Explanation

//@version=5: This directive tells TradingView to interpret the script using the Pine Script version 5. Each version of Pine Script has different features and capabilities. This should always be the first line in your script.
indicator("My Script", overlay=true): This is the declaration of the script properties. The indicator() function defines the script’s name as displayed in the user interface, in this case, “My Script”. The overlay=true argument means that the plot will be displayed on the main chart area, not in a separate pane below it.
value = close: This line assigns the closing price of the current bar to the value variable.
s = str.tostring(value, format.mintick): This line uses the str.tostring() function to convert the float value to a string. The format.mintick specifies that the value will be rounded to the nearest number that can be divided by the minimum tick size of the current symbol.
plot(value): This line plots the value of the closing price on the chart.
label.new(x=bar_index, y=value, text=s , size = size.large): This line creates a new label at the position specified by x=bar_index (the current bar on the chart) and y=value (the closing price). The text argument sets the text of the label to be the string representation of the closing price. The size argument sets the size of the label to large.

This script, in essence, plots the closing price of the current bar and labels it on the chart using the string representation of the price, formatted according to the minimum tick size of the current symbol.

Key Takeaway

The str.tostring() function is a powerful tool in Pine Script that allows the conversion of various data types to string format. This is incredibly useful when needing to display data on charts or when carrying out operations that require string input. Its ability to format the output and handle different data types makes it a versatile and important

Conclusion

Understanding str.tostring() in Pine Script is essential for effective data manipulation and presentation in TradingView. From floating numbers to boolean values, this function can convert an array of data types into a readable string format, simplifying the display and usage of various data elements.