Skip to main content
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).
Example

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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters Returns const string Notes
  • time_value takes an int. A division such as time / 1000 gives a float and is rejected; wrap it in math.floor to get an int.
Example

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
Parameters Returns input string Notes
  • time_value takes an int. A division such as time / 1000 gives a float and is rejected; wrap it in math.floor to get an int.
Example

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
Parameters Returns simple string Notes
  • time_value takes an int. A division such as time / 1000 gives a float and is rejected; wrap it in math.floor to get an int.
Example

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
Parameters Returns series string Notes
  • time_value takes an int. A division such as time / 1000 gives a float and is rejected; wrap it in math.floor to get an int.
Example

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
Parameters 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
Parameters 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
Parameters 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
Parameters Returns series int Example

str.lower (function, overload 1)

Definition Converts a string to lower case. It takes the string and nothing else. Syntax
Parameters Returns const string Example

str.lower (function, overload 2)

Definition Converts a string to lower case. It takes the string and nothing else. Syntax
Parameters Returns input string Example

str.lower (function, overload 3)

Definition Converts a string to lower case. It takes the string and nothing else. Syntax
Parameters Returns simple string Example

str.lower (function, overload 4)

Definition Converts a string to lower case. It takes the string and nothing else. Syntax
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters 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
Parameters Returns series string Example