Language version: 2 · Reference version: 2.7 · Date: 2026-10-25 · Compiler build: df7b3b14 · Namespace: str · Entries: 75
str (library)
Definition
Seventeen functions for working with text: tests such as str.contains and str.startswith, transformations such as str.replace and str.substring, conversions in both directions with str.tonumber and str.tostring, and str.format_time for rendering a time.
Use these to build an alert message or a plot’s text, not to alter chart data.
Notes
- A string has no method form:
s.length()is rejected. Call the function with the string as its first argument:str.length(s).
str.contains (function, overload 1)
Definition
Tests whether one string occurs inside another.
Both arguments are required, and the function carries one signature per form of them.
Syntax
Returns
const bool
Example
str.contains (function, overload 2)
Definition
Tests whether one string occurs inside another.
Both arguments are required, and the function carries one signature per form of them.
Syntax
Returns
input bool
Example
str.contains (function, overload 3)
Definition
Tests whether one string occurs inside another.
Both arguments are required, and the function carries one signature per form of them.
Syntax
Returns
simple bool
Example
str.contains (function, overload 4)
Definition
Tests whether one string occurs inside another.
Both arguments are required, and the function carries one signature per form of them.
Syntax
Returns
series bool
Example
str.endswith (function, overload 1)
Definition
Asks whether a string finishes with a given ending.
The suffix is a string, not a pattern, and both arguments are required.
Syntax
Returns
const bool
Example
str.endswith (function, overload 2)
Definition
Asks whether a string finishes with a given ending.
The suffix is a string, not a pattern, and both arguments are required.
Syntax
Returns
input bool
Example
str.endswith (function, overload 3)
Definition
Asks whether a string finishes with a given ending.
The suffix is a string, not a pattern, and both arguments are required.
Syntax
Returns
simple bool
Example
str.endswith (function, overload 4)
Definition
Asks whether a string finishes with a given ending.
The suffix is a string, not a pattern, and both arguments are required.
Syntax
Returns
series bool
Example
str.format_time (function, overload 1)
Definition
Renders a time as text, in a format and a time zone you give.
time_value is in seconds since 1970-01-01 UTC, unlike time, timenow and the other Lipi times, which are in milliseconds: pass math.floor(time / 1000). format is required and is written as a pattern of the reference date 2006-01-02 15:04:05 (for example "2006-01-02 15:04" or "02 Jan 15:04"). timezone defaults to "UTC"; an unknown time zone gives na.
Syntax
Returns
const string
Notes
time_valuetakes an int. A division such astime / 1000gives a float and is rejected; wrap it inmath.floorto get an int.
str.format_time (function, overload 2)
Definition
Renders a time as text, in a format and a time zone you give.
time_value is in seconds since 1970-01-01 UTC, unlike time, timenow and the other Lipi times, which are in milliseconds: pass math.floor(time / 1000). format is required and is written as a pattern of the reference date 2006-01-02 15:04:05 (for example "2006-01-02 15:04" or "02 Jan 15:04"). timezone defaults to "UTC"; an unknown time zone gives na.
Syntax
Returns
input string
Notes
time_valuetakes an int. A division such astime / 1000gives a float and is rejected; wrap it inmath.floorto get an int.
str.format_time (function, overload 3)
Definition
Renders a time as text, in a format and a time zone you give.
time_value is in seconds since 1970-01-01 UTC, unlike time, timenow and the other Lipi times, which are in milliseconds: pass math.floor(time / 1000). format is required and is written as a pattern of the reference date 2006-01-02 15:04:05 (for example "2006-01-02 15:04" or "02 Jan 15:04"). timezone defaults to "UTC"; an unknown time zone gives na.
Syntax
Returns
simple string
Notes
time_valuetakes an int. A division such astime / 1000gives a float and is rejected; wrap it inmath.floorto get an int.
str.format_time (function, overload 4)
Definition
Renders a time as text, in a format and a time zone you give.
time_value is in seconds since 1970-01-01 UTC, unlike time, timenow and the other Lipi times, which are in milliseconds: pass math.floor(time / 1000). format is required and is written as a pattern of the reference date 2006-01-02 15:04:05 (for example "2006-01-02 15:04" or "02 Jan 15:04"). timezone defaults to "UTC"; an unknown time zone gives na.
Syntax
Returns
series string
Notes
time_valuetakes an int. A division such astime / 1000gives a float and is rejected; wrap it inmath.floorto get an int.
str.length (function, overload 1)
Definition
Gives the length of a string as an int.
One argument, required. The length counts bytes of the text (UTF-8), not characters, so a character outside ASCII counts as two or more.
Syntax
Returns
const int
Example
str.length (function, overload 2)
Definition
Gives the length of a string as an int.
One argument, required. The length counts bytes of the text (UTF-8), not characters, so a character outside ASCII counts as two or more.
Syntax
Returns
input int
Example
str.length (function, overload 3)
Definition
Gives the length of a string as an int.
One argument, required. The length counts bytes of the text (UTF-8), not characters, so a character outside ASCII counts as two or more.
Syntax
Returns
simple int
Example
str.length (function, overload 4)
Definition
Gives the length of a string as an int.
One argument, required. The length counts bytes of the text (UTF-8), not characters, so a character outside ASCII counts as two or more.
Syntax
Returns
series int
Example
str.lower (function, overload 1)
Definition
Converts a string to lower case.
It takes the string and nothing else.
Syntax
Returns
const string
Example
str.lower (function, overload 2)
Definition
Converts a string to lower case.
It takes the string and nothing else.
Syntax
Returns
input string
Example
str.lower (function, overload 3)
Definition
Converts a string to lower case.
It takes the string and nothing else.
Syntax
Returns
simple string
Example
str.lower (function, overload 4)
Definition
Converts a string to lower case.
It takes the string and nothing else.
Syntax
Returns
series string
Example
str.match (function, overload 1)
Definition
Returns the first part of source that matches the regular expression pattern.
Patterns are written in RE2 syntax, which has no backreferences and no lookaround. A pattern that will not compile is not an error: the call returns empty text.
Syntax
Returns
const string
Example
str.match (function, overload 2)
Definition
Returns the first part of source that matches the regular expression pattern.
Patterns are written in RE2 syntax, which has no backreferences and no lookaround. A pattern that will not compile is not an error: the call returns empty text.
Syntax
Returns
input string
Example
str.match (function, overload 3)
Definition
Returns the first part of source that matches the regular expression pattern.
Patterns are written in RE2 syntax, which has no backreferences and no lookaround. A pattern that will not compile is not an error: the call returns empty text.
Syntax
Returns
simple string
Example
str.match (function, overload 4)
Definition
Returns the first part of source that matches the regular expression pattern.
Patterns are written in RE2 syntax, which has no backreferences and no lookaround. A pattern that will not compile is not an error: the call returns empty text.
Syntax
Returns
series string
Example
str.pos (function, overload 1)
Definition
Reports the position at which one string sits inside another.
The result is an int: the position of the first match, counted in bytes from 0, or -1 when str does not occur in source. For text outside ASCII a byte position is not a character position, so a result of str.pos passed to str.substring, which counts characters, can cut at the wrong place.
Syntax
Returns
const int
Example
str.pos (function, overload 2)
Definition
Reports the position at which one string sits inside another.
The result is an int: the position of the first match, counted in bytes from 0, or -1 when str does not occur in source. For text outside ASCII a byte position is not a character position, so a result of str.pos passed to str.substring, which counts characters, can cut at the wrong place.
Syntax
Returns
input int
Example
str.pos (function, overload 3)
Definition
Reports the position at which one string sits inside another.
The result is an int: the position of the first match, counted in bytes from 0, or -1 when str does not occur in source. For text outside ASCII a byte position is not a character position, so a result of str.pos passed to str.substring, which counts characters, can cut at the wrong place.
Syntax
Returns
simple int
Example
str.pos (function, overload 4)
Definition
Reports the position at which one string sits inside another.
The result is an int: the position of the first match, counted in bytes from 0, or -1 when str does not occur in source. For text outside ASCII a byte position is not a character position, so a result of str.pos passed to str.substring, which counts characters, can cut at the wrong place.
Syntax
Returns
series int
Example
str.repeat (function, overload 1)
Definition
Produces a string made of repeated copies of another, with the option of something between the copies.
The string and the count are required; the separator is not.
Syntax
Returns
const string
Example
str.repeat (function, overload 2)
Definition
Produces a string made of repeated copies of another, with the option of something between the copies.
The string and the count are required; the separator is not.
Syntax
Returns
input string
Example
str.repeat (function, overload 3)
Definition
Produces a string made of repeated copies of another, with the option of something between the copies.
The string and the count are required; the separator is not.
Syntax
Returns
simple string
Example
str.repeat (function, overload 4)
Definition
Produces a string made of repeated copies of another, with the option of something between the copies.
The string and the count are required; the separator is not.
Syntax
Returns
series string
Example
str.replace (function, overload 1)
Definition
Substitutes one piece of text for another inside a string.
The source, the old text and the new text are required; the count is optional.
Syntax
Returns
const string
Example
str.replace (function, overload 2)
Definition
Substitutes one piece of text for another inside a string.
The source, the old text and the new text are required; the count is optional.
Syntax
Returns
input string
Example
str.replace (function, overload 3)
Definition
Substitutes one piece of text for another inside a string.
The source, the old text and the new text are required; the count is optional.
Syntax
Returns
simple string
Example
str.replace (function, overload 4)
Definition
Substitutes one piece of text for another inside a string.
The source, the old text and the new text are required; the count is optional.
Syntax
Returns
series string
Example
str.replace_all (function, overload 1)
Definition
Substitutes new text for every occurrence of the old text.
It takes no count. That is the difference between it and str.replace, which does.
Syntax
Returns
const string
Example
str.replace_all (function, overload 2)
Definition
Substitutes new text for every occurrence of the old text.
It takes no count. That is the difference between it and str.replace, which does.
Syntax
Returns
input string
Example
str.replace_all (function, overload 3)
Definition
Substitutes new text for every occurrence of the old text.
It takes no count. That is the difference between it and str.replace, which does.
Syntax
Returns
simple string
Example
str.replace_all (function, overload 4)
Definition
Substitutes new text for every occurrence of the old text.
It takes no count. That is the difference between it and str.replace, which does.
Syntax
Returns
series string
Example
str.split (function, overload 1)
Definition
Splits string wherever separator occurs and returns the pieces as an array of strings. The separator itself is not included in the pieces.
Syntax
Returns
series array<string>
Example
str.split (function, overload 2)
Definition
Splits string wherever separator occurs and returns the pieces as an array of strings. The separator itself is not included in the pieces.
Syntax
Returns
series array<string>
Example
str.split (function, overload 3)
Definition
Splits string wherever separator occurs and returns the pieces as an array of strings. The separator itself is not included in the pieces.
Syntax
Returns
series array<string>
Example
str.split (function, overload 4)
Definition
Splits string wherever separator occurs and returns the pieces as an array of strings. The separator itself is not included in the pieces.
Syntax
Returns
series array<string>
Example
str.startswith (function, overload 1)
Definition
The counterpart of str.endswith, looking at the front of the string instead of the back.
Both arguments are required.
Syntax
Returns
const bool
Example
str.startswith (function, overload 2)
Definition
The counterpart of str.endswith, looking at the front of the string instead of the back.
Both arguments are required.
Syntax
Returns
input bool
Example
str.startswith (function, overload 3)
Definition
The counterpart of str.endswith, looking at the front of the string instead of the back.
Both arguments are required.
Syntax
Returns
simple bool
Example
str.startswith (function, overload 4)
Definition
The counterpart of str.endswith, looking at the front of the string instead of the back.
Both arguments are required.
Syntax
Returns
series bool
Example
str.substring (function, overload 1)
Definition
Cuts a piece out of a string. There are two forms: one takes a start and an end, the other takes a start alone.
Positions are ints, counted in characters from 0, not in bytes. start is inclusive and end is exclusive. Without end, the result runs to the end of source. A start at or beyond the end of the text gives an empty string, and an end beyond it stops at the end. With end, a negative start or end, or an end before start, is refused with the error “Invalid argument passed to Subsctring” by the check that runs when the script is added to the chart (the editor’s check does not report it); on a later bar the same invalid range gives na. Without end, a negative start gives an empty string.
Syntax
Returns
const string
Example
str.substring (function, overload 2)
Definition
Cuts a piece out of a string. There are two forms: one takes a start and an end, the other takes a start alone.
Positions are ints, counted in characters from 0, not in bytes. start is inclusive and end is exclusive. Without end, the result runs to the end of source. A start at or beyond the end of the text gives an empty string, and an end beyond it stops at the end. With end, a negative start or end, or an end before start, is refused with the error “Invalid argument passed to Subsctring” by the check that runs when the script is added to the chart (the editor’s check does not report it); on a later bar the same invalid range gives na. Without end, a negative start gives an empty string.
Syntax
Returns
input string
Example
str.substring (function, overload 3)
Definition
Cuts a piece out of a string. There are two forms: one takes a start and an end, the other takes a start alone.
Positions are ints, counted in characters from 0, not in bytes. start is inclusive and end is exclusive. Without end, the result runs to the end of source. A start at or beyond the end of the text gives an empty string, and an end beyond it stops at the end. With end, a negative start or end, or an end before start, is refused with the error “Invalid argument passed to Subsctring” by the check that runs when the script is added to the chart (the editor’s check does not report it); on a later bar the same invalid range gives na. Without end, a negative start gives an empty string.
Syntax
Returns
simple string
Example
str.substring (function, overload 4)
Definition
Cuts a piece out of a string. There are two forms: one takes a start and an end, the other takes a start alone.
Positions are ints, counted in characters from 0, not in bytes. start is inclusive and end is exclusive. Without end, the result runs to the end of source. A start at or beyond the end of the text gives an empty string, and an end beyond it stops at the end. With end, a negative start or end, or an end before start, is refused with the error “Invalid argument passed to Subsctring” by the check that runs when the script is added to the chart (the editor’s check does not report it); on a later bar the same invalid range gives na. Without end, a negative start gives an empty string.
Syntax
Returns
series string
Example
str.substring (function, overload 5)
Definition
Cuts a piece out of a string. There are two forms: one takes a start and an end, the other takes a start alone.
Positions are ints, counted in characters from 0, not in bytes. start is inclusive and end is exclusive. Without end, the result runs to the end of source. A start at or beyond the end of the text gives an empty string, and an end beyond it stops at the end. With end, a negative start or end, or an end before start, is refused with the error “Invalid argument passed to Subsctring” by the check that runs when the script is added to the chart (the editor’s check does not report it); on a later bar the same invalid range gives na. Without end, a negative start gives an empty string.
Syntax
Returns
const string
Example
str.substring (function, overload 6)
Definition
Cuts a piece out of a string. There are two forms: one takes a start and an end, the other takes a start alone.
Positions are ints, counted in characters from 0, not in bytes. start is inclusive and end is exclusive. Without end, the result runs to the end of source. A start at or beyond the end of the text gives an empty string, and an end beyond it stops at the end. With end, a negative start or end, or an end before start, is refused with the error “Invalid argument passed to Subsctring” by the check that runs when the script is added to the chart (the editor’s check does not report it); on a later bar the same invalid range gives na. Without end, a negative start gives an empty string.
Syntax
Returns
input string
Example
str.substring (function, overload 7)
Definition
Cuts a piece out of a string. There are two forms: one takes a start and an end, the other takes a start alone.
Positions are ints, counted in characters from 0, not in bytes. start is inclusive and end is exclusive. Without end, the result runs to the end of source. A start at or beyond the end of the text gives an empty string, and an end beyond it stops at the end. With end, a negative start or end, or an end before start, is refused with the error “Invalid argument passed to Subsctring” by the check that runs when the script is added to the chart (the editor’s check does not report it); on a later bar the same invalid range gives na. Without end, a negative start gives an empty string.
Syntax
Returns
simple string
Example
str.substring (function, overload 8)
Definition
Cuts a piece out of a string. There are two forms: one takes a start and an end, the other takes a start alone.
Positions are ints, counted in characters from 0, not in bytes. start is inclusive and end is exclusive. Without end, the result runs to the end of source. A start at or beyond the end of the text gives an empty string, and an end beyond it stops at the end. With end, a negative start or end, or an end before start, is refused with the error “Invalid argument passed to Subsctring” by the check that runs when the script is added to the chart (the editor’s check does not report it); on a later bar the same invalid range gives na. Without end, a negative start gives an empty string.
Syntax
Returns
series string
Example
str.tonumber (function, overload 1)
Definition
Reads a number out of a string.
The result is a float in every form, so a string holding a whole number still comes back as a float.
Syntax
Returns
const float
Example
str.tonumber (function, overload 2)
Definition
Reads a number out of a string.
The result is a float in every form, so a string holding a whole number still comes back as a float.
Syntax
Returns
input float
Example
str.tonumber (function, overload 3)
Definition
Reads a number out of a string.
The result is a float in every form, so a string holding a whole number still comes back as a float.
Syntax
Returns
simple float
Example
str.tonumber (function, overload 4)
Definition
Reads a number out of a string.
The result is a float in every form, so a string holding a whole number still comes back as a float.
Syntax
Returns
series float
Example
str.tostring (function, overload 1)
Definition
Renders a value as a string.
Overload on float or bool alone: a float is rounded to 4 decimal places and trailing zeros are trimmed, so a smaller difference is lost (0.00004 gives 0); to keep more digits, use the overload with format, for example str.tostring(price, "#.########"). Bools become true or false; na becomes "NA".
Overload on float with format (and optional mintick): supports mintick, volume, and percent, plus custom patterns made of # and 0 (for example #.##). Default format is #.##########.
Syntax
Returns
simple string
String representation of the input.
Example
str.tostring (function, overload 2)
Definition
Renders a value as a string.
Overload on float or bool alone: a float is rounded to 4 decimal places and trailing zeros are trimmed, so a smaller difference is lost (0.00004 gives 0); to keep more digits, use the overload with format, for example str.tostring(price, "#.########"). Bools become true or false; na becomes "NA".
Overload on float with format (and optional mintick): supports mintick, volume, and percent, plus custom patterns made of # and 0 (for example #.##). Default format is #.##########.
Syntax
Returns
series string
String representation of the input.
Example
str.tostring (function, overload 3)
Definition
Renders a value as a string.
Overload on float or bool alone: a float is rounded to 4 decimal places and trailing zeros are trimmed, so a smaller difference is lost (0.00004 gives 0); to keep more digits, use the overload with format, for example str.tostring(price, "#.########"). Bools become true or false; na becomes "NA".
Overload on float with format (and optional mintick): supports mintick, volume, and percent, plus custom patterns made of # and 0 (for example #.##). Default format is #.##########.
Syntax
Returns
simple string
String representation of the input.
Example
str.tostring (function, overload 4)
Definition
Renders a value as a string.
Overload on float or bool alone: a float is rounded to 4 decimal places and trailing zeros are trimmed, so a smaller difference is lost (0.00004 gives 0); to keep more digits, use the overload with format, for example str.tostring(price, "#.########"). Bools become true or false; na becomes "NA".
Overload on float with format (and optional mintick): supports mintick, volume, and percent, plus custom patterns made of # and 0 (for example #.##). Default format is #.##########.
Syntax
Returns
series string
String representation of the input.
Example
str.tostring (function, overload 5)
Definition
Renders a value as a string.
Overload on float or bool alone: a float is rounded to 4 decimal places and trailing zeros are trimmed, so a smaller difference is lost (0.00004 gives 0); to keep more digits, use the overload with format, for example str.tostring(price, "#.########"). Bools become true or false; na becomes "NA".
Overload on float with format (and optional mintick): supports mintick, volume, and percent, plus custom patterns made of # and 0 (for example #.##). Default format is #.##########.
Syntax
Returns
simple string
String representation of the input.
Example
str.tostring (function, overload 6)
Definition
Renders a value as a string.
Overload on float or bool alone: a float is rounded to 4 decimal places and trailing zeros are trimmed, so a smaller difference is lost (0.00004 gives 0); to keep more digits, use the overload with format, for example str.tostring(price, "#.########"). Bools become true or false; na becomes "NA".
Overload on float with format (and optional mintick): supports mintick, volume, and percent, plus custom patterns made of # and 0 (for example #.##). Default format is #.##########.
Syntax
Returns
series string
String representation of the input.
Example
str.trim (function, overload 1)
Definition
Removes whitespace from around a string and hands back the result.
It removes the white space that Unicode defines at both ends: spaces, tabs, line breaks and the other characters Unicode marks as white space.
Syntax
Returns
const string
Example
str.trim (function, overload 2)
Definition
Removes whitespace from around a string and hands back the result.
It removes the white space that Unicode defines at both ends: spaces, tabs, line breaks and the other characters Unicode marks as white space.
Syntax
Returns
input string
Example
str.trim (function, overload 3)
Definition
Removes whitespace from around a string and hands back the result.
It removes the white space that Unicode defines at both ends: spaces, tabs, line breaks and the other characters Unicode marks as white space.
Syntax
Returns
simple string
Example
str.trim (function, overload 4)
Definition
Removes whitespace from around a string and hands back the result.
It removes the white space that Unicode defines at both ends: spaces, tabs, line breaks and the other characters Unicode marks as white space.
Syntax
Returns
series string
Example
str.upper (function, overload 1)
Definition
Converts a string to upper case; the other half of the pair with str.lower.
It takes the string and nothing else.
Syntax
Returns
const string
Example
str.upper (function, overload 2)
Definition
Converts a string to upper case; the other half of the pair with str.lower.
It takes the string and nothing else.
Syntax
Returns
input string
Example
str.upper (function, overload 3)
Definition
Converts a string to upper case; the other half of the pair with str.lower.
It takes the string and nothing else.
Syntax
Returns
simple string
Example
str.upper (function, overload 4)
Definition
Converts a string to upper case; the other half of the pair with str.lower.
It takes the string and nothing else.
Syntax
Returns
series string
Example