str namespace

str

Overview

The str namespace helps you assemble and analyze textual data. Pine uses strings for labels, table cells, debug readouts, and alert messages, so being able to format numbers, pad values, and search within text is essential for polished scripts.

Most str.* functions accept either const, simple, or series strings. When you pass a series argument, the result will also be a series string that can vary per bar.

Common helpers

Helper	Purpose
str.format(formatString, arg0, ...)	Substitute numbered placeholders ({0}) with values, similar to Python’s format.
str.tostring(value, format)	Convert numbers, bools, or colors to strings with formatting options.
str.length(text)	Return the number of UTF-16 code units in text.
str.substring(text, start, end)	Extract a slice using zero-based indexes (end exclusive).
str.replace(text, target, replacement)	Replace occurrences of target with replacement.
str.split(text, delimiter)	Break a string into an array of substrings.
str.contains(text, needle) / str.startswith(text, needle) / str.endswith(text, needle)	Test for substrings.

Remarks

• str.format() and str.tostring() are preferred for presenting numbers in status lines, labels, or table cells because they honour formatting specs like "#.##" or format.percent.
• Many helpers have overloads for const, simple, and series inputs. Use the appropriate variant when working inside loops or with dynamic data to avoid type-mismatch errors.
• String operations are relatively inexpensive, but excessive concatenation inside loops can still impact performance—consider building strings once per bar or using var buffers.

Example

//@version=5
indicator("str namespace demo", overlay=false, max_labels_count=1)

profitPct = (close / nz(close[1], close) - 1.0) * 100
description = str.format("Change: {0}%\nSymbol: {1}",
    str.tostring(profitPct, "#.00"),
    syminfo.ticker)

isPositive = str.contains(description, "-") == false

plot(profitPct, "Change %", color=isPositive ? color.green : color.red)

if barstate.islast
    label.new(bar_index, profitPct,
        text=description,
        textcolor=color.white,
        bgcolor=color.new(isPositive ? color.green : color.red, 70),
        style=label.style_label_left)

See Also

• string()
• float()
• int()
• array