str reference

String conversion, formatting, and UTF-8 string helpers, including string methods exposed here as str.* functions.

str.concat

str.concat(values: scalar...) -> string

Joins values into one string.

Pass values directly; they are converted to text using the same rules as str.format and joined in order. A null value appears as the text null.

Text saved in state, collections, labels, tables, or logs counts toward the script's text limit while it is needed. Historical plot labels keep their text for the retained history. For one label showing the latest value, use a label pool with capacity one.

A handler or state initializer can exceed the text limit even if its strings are temporary. Assigning a string to a variable does not reduce that limit.

Example

script "String Concat"
data chart = subscribe(data.ohlcv)
state hud = entities.labelPool(max: 1, anchor: anchor.topLeft)

on chart.update {
  hud.get(0).set(12.0, 12.0, str.concat("close=", chart.close ?? 0.0))
}

str.format

str.format(template: string, values: scalar...) -> string

Inserts values into a text template.

template must be a string literal. values supplies the values for numbered placeholders, starting at {0}. A null value appears as the text null.

For numbers, use {n:[+][,][.digits][%]}:

• + always shows the sign.
• , groups whole-number digits in threes.
• .digits sets the decimal places. Ties round to the nearest even digit.
• % multiplies by 100 before rounding and adds a percent sign.

A plain {n} accepts any scalar value. A numeric format requires a number. Placeholders starting with a digit must have a valid index, format, and matching value, or the script is rejected before it runs. Other text in braces, including an unclosed {, stays unchanged. Named placeholders and {{ escapes are not supported.

Historical plot labels keep their text for the retained history. For one label showing the latest value, use a label pool with capacity one. A single handler can exceed the text limit even when its strings are temporary.

Example

script "String Format"
data chart = subscribe(data.ohlcv)
state hud = entities.labelPool(max: 1, anchor: anchor.topLeft)

on chart.update {
  hud.get(0).set(12.0, 12.0, str.format("close={0:.2}", chart.close ?? 0.0))
}

str.len

str.len: int

Counts the Unicode characters in a string.

Counts Unicode scalar values, not bytes. A visible character made from several Unicode values, such as some emoji, can count as more than one.

Check for null or use ?? to supply a fallback before reading a nullable string.

Example

script "String Length"
data chart = subscribe(data.ohlcv)
plot n = plot.line(title: "Chars")

on chart.update {
  let label = str.concat("C=", chart.close ?? 0.0)
  n.plot(float(label.len))
}

str.isEmpty

str.isEmpty: bool

Reports whether a string is empty.

Returns true when the string has no characters. Whitespace still counts as text.

Check for null or use ?? to supply a fallback before reading a nullable string.

Example

script "String Empty"
data chart = subscribe(data.ohlcv)
plot hit = plot.line(title: "Hit")

on chart.update {
  let label = chart.isNew ? "" : "forming"
  hit.plot(label.isEmpty ? 1.0 : 0.0)
}

str.contains

str.contains(text: string, needle: string) -> bool

Tests whether text contains needle.

Looks for needle anywhere in text. Matching is case-sensitive. An empty needle always returns true.

Check for null or use ?? to supply a fallback before calling with a nullable string.

Example

script "String Contains"
data chart = subscribe(data.ohlcv)
plot hit = plot.line(title: "Hit")

on chart.update {
  let venue = "Binance Perp"
  hit.plot(str.contains(str.lower(venue), "perp") ? 1.0 : 0.0)
}

str.startsWith

str.startsWith(text: string, prefix: string) -> bool

Tests whether text starts with prefix.

Looks for prefix at the start of text. Matching is case-sensitive. An empty prefix always returns true.

Check for null or use ?? to supply a fallback before calling with a nullable string.

Example

script "String Prefix"
data chart = subscribe(data.ohlcv)
plot hit = plot.line(title: "Hit")

on chart.update {
  hit.plot(str.startsWith("BTCUSDT", "BTC") ? chart.close : 0.0)
}

str.endsWith

str.endsWith(text: string, suffix: string) -> bool

Tests whether text ends with suffix.

Looks for suffix at the end of text. Matching is case-sensitive. An empty suffix always returns true.

Check for null or use ?? to supply a fallback before calling with a nullable string.

Example

script "String Suffix"
data chart = subscribe(data.ohlcv)
plot hit = plot.line(title: "Hit")

on chart.update {
  hit.plot(str.endsWith("BTCUSDT", "USDT") ? chart.close : 0.0)
}

str.lower

str.lower(text: string) -> string

Converts text to lowercase.

Uses Unicode lowercase rules.

Check for null or use ?? to supply a fallback before calling with a nullable string.

Example

script "String Lower"
data chart = subscribe(data.ohlcv)
plot hit = plot.line(title: "Hit")

on chart.update {
  let venue = str.lower("İstanbul")
  hit.plot(str.contains(venue, "i") ? chart.close : 0.0)
}

str.upper

str.upper(text: string) -> string

Converts text to uppercase.

Uses Unicode uppercase rules.

Check for null or use ?? to supply a fallback before calling with a nullable string.

Example

script "String Upper"
data chart = subscribe(data.ohlcv)
plot hit = plot.line(title: "Hit")

on chart.update {
  let label = str.upper("ok")
  hit.plot(label.len == 2 ? chart.close : 0.0)
}

str.trim

str.trim(text: string) -> string

Removes whitespace from both ends of text.

Removes Unicode whitespace at either end. Whitespace inside the text stays unchanged.

Check for null or use ?? to supply a fallback before calling with a nullable string.

Example

script "String Trim"
data chart = subscribe(data.ohlcv)
plot hit = plot.line(title: "Hit")

on chart.update {
  let cleaned = str.trim("  signal  ")
  hit.plot(str.startsWith(cleaned, "sig") ? chart.close : 0.0)
}