String Manipulation Framework [PineCoders FAQ]

22 sty 2021

█ OVERVIEW

This script provides string manipulation functions to help Pine coders.
                                
                              
█ FUNCTIONS PROVIDED

Pine Script®

Function returning the leftmost `_n` characters in `_str`.

Pine Script®

Function returning the rightmost `_n` characters in `_str`.

Pine Script®

Function returning the substring of `_str` from character position `_from` to `_to` inclusively.

Pine Script®

Function returning the sub-string of `_str` to the left of the `_of` separating character.

Pine Script®

Function returning the sub-string of `_str` to the right of the `_of` separating character.

Pine Script®

Function returning the position of the first occurrence of `_chr` in `_str`, where the first character position is 0. Returns -1 if the character is not found.

Pine Script®

Function that replaces a character at position `_pos` in the `_src` string with the `_str` character or string.

Pine Script®

Function returning a format string usable with `tostring()` to round a value to the symbol's tick precision.

Pine Script®

Function returning a string representation of a numeric `_val` using a special `_fmt` string allowing all strings to be of the same width, to help align columns of values.

`f_tostringPad()`
Using the functions should be straightforward, but `f_tostringPad()` requires more explanations. Its purpose is to help coders produce columns of fixed-width string representations of numbers which can be used to produce columns of numbers that vertically align neatly in labels, something that comes in handy when, for example, you need to center columns, yet still produce numbers of various lengths that nonetheless align.

While the formatting string used with this function resembles the one used in tostring(), it has a few additional characteristics:
 • The question mark (" ? ") is used to indicate that padding is needed.
 • If negative numbers must be handled by the function, the first character of the formatting string must be a minus sign ("-"),
  otherwise the unary minus sign of negative numbers will be stripped out.
 • You will produce more predictable results by using "0" rather than "#" in the formatting string.

You can experiment with `f_tostringPad()` formatting strings by changing the one used in the script's inputs and see the results on the chart.
These are some valid examples of formatting strings that can be used with `f_tostringPad()`:

Pine Script®

█ CHART

The information displayed by this indicator uses the values in the script's Inputs, so you can use them to play around.
The chart shows the following information:
 • Column 0: The numeric input values in a centered column, converted to strings using tostring() without a formatting argument.
 • Column 1: Shows the values formatted using `f_tostringPad()` with the formatting string from the inputs.
 • Column 2: Shows the values formatted using `f_tostringPad()` but with only the part of the formatting string left of the decimal point, if it contains one.
 • Column 3: Shows the values formatted using `f_tostringPad()` but with the part of the formatting string left of the decimal point,
  to which is added the right part of the `f_tostringPad()` formatting string, to obtain the precision in ticks of the symbol the chart is on.
 • Column 4: Shows the result of using the other string manipulation functions in the script on the source string supplied in the inputs.
  It also demonstrates how to split up a label in two distinct parts so that you can vertically align columns when the leftmost part contains strings with varying lengths.
  You will see in our code how we construct this column in two steps.


█ LIMITATIONS

The Pine runtime is optimized for number crunching. Too many string manipulations will take a toll on the performance of your scripts, as can readily be seen with the running time of this script. To minimize the impact of using string manipulation functions in your scripts, consider limiting their calculation to the first or last bar of the dataset when possible. This can be achieved by using the var keyword when declaring variables containing the result of your string manipulations, or by enclosing blocks of code in if blocks using barstate.isfirst or barstate.islast.


█ NOTES

To understand the challenges we face when trying to align strings vertically, it is useful to know that:
 • As is the case in many other places in the TadingView UI and other docs, the Pine runtime uses the MS Trebuchet font to display label text.
 • Trebuchet uses proportionally-spaced letters (a "W" takes more horizontal space than an "I"), but fixed-space digits (a "1" takes the same horizontal space as a "3").
  Digits all use a figure space width, and it is this property that allows us to align numbers vertically.
  The fact that letters are proportionally spaced is the reason why we can't vertically align columns using a "legend" + ":" `+ value structure when the "legend" part varies in width.
 • The unary minus sign is the width of a punctuation space. We use this property to pad the beginning of numbers
  when you use a "-" as the first character of the `f_tostringPad()` formatting string.

Our script was written using the PineCoders Coding Conventions for Pine.
The description was formatted using the techniques explained in the How We Write and Format Script Descriptions PineCoders publication.


█ THANKS

Thanks to LonesomeTheBlue for the `f_strReplace()` function.



Look first. Then leap.