Pinescript - Common String Functions Library by RRB

2 mar 2021

Common String Functions Library by RagingRocketBull 2021
Version 1.0

Pinescript now has strong support for arrays with many powerful functions, but still lacks built-in string functions. Luckily you can easily process and manipulate strings using arrays.
This script provides a library of common string functions for everyday use, such as: indexOf, substr, replace, ascii_code, str_to_int etc. There are 100+ unique functions (130 including all implementations)
It should serve as building blocks to speed up the development of your custom scripts. You should also be able to learn how Pinescript arrays works and how you can process strings.
Similar libraries for Array and Statistical Functions are in the works. You can find the full list of functions below.

Features:
- 100+ unique string functions (130 including all implementations) in categories: lookup, testing, conversion, modification, extraction, type conversion, date and time, console output
- Live Output for all/selected functions based on User Input. Test any function before using in script.
- Live Unit Test Output for several functions based on pre-defined inputs.
- Output filters: show unique functions/all implementations, grouping
- Console customization options: set custom text size, color, page length
- Support for Pages - auto splits output into pages with fixed length, use pages in your scripts
- Several easy to use console output functions to speed up debugging/output.

WARNING:
- Compilation Time: 1 min

Notes:
- uses Pinescript v3 Compatibility Framework
- this script is packed to the max and sets a new record in testing of Pinescript's limits: 500 local scopes, 4000+ lines, 180kb+ source size. It's not possible to add more ifs/fors/functions without reducing functionality
- to fit the max limit of local scopes = 500 all ifs were replaced with ?: where possible, the number of function calls was reduced, some calls replaced with inline function code
- ifs are faster (especially when lots of them are used in a for cycle), more readable, but ifs/fors/functions increase local scopes (+1) and compiled file size, have max nesting limit = 10.
- ?: are slower (especially in for cycles), hard to read when nested, don't affect local scopes, reduce compiled file size, can't contain plots, for statements (break/continue) and sets of statements
- for most array functions to work (except push), an array must be defined with at least 1 pre-existing dummy element 0.
- if you see "String too long" error - enable Show Pages, reduce Max Chars Per Page < Max String Length limit = 4096.
- if you see "Loop too long" error - hide/unhide or reattach the script
- some functions have several implementations that can be faster/slower, use internal code/ext functions
- <function>1 is manual string processing using for cycles (array.get) and ext functions - provided in case you want to implement your own logic, may sometimes be slower
- <function>2 is a 2nd alternate implementation mostly done using built-in functions (array.indexof, array.slice, array.insert, array.remove, str.replace_all),
attempts to minimize local scopes and dependency on ext functions, should generally be faster
- <function>3 is a 3rd alternate (array.includes, array.fill) or a more advanced implementation (datetime3_str) with lots of params, giving you the most control over output
- most functions have dependencies, such as const names, global arrays, inputs, other functions.

P.S. Strings of Time may be closed unto themselves or have loose ends; they can vibrate, stretch, join or split.

Function Groups:

1. Char Functions
- repeat(str, num)
- ascii_char(code)
- ascii_code(char)
- is_digit(char)
- is_letter(char)
- digit_to_int(char)
- is_space_char(char)

2. Char Test and Lookup Functions
- char_at(str, pos)
- char_code_at(str, pos)
- indexOf_char(str, char)
- lastIndexOf_char(str, char)
- nth_indexOf_char(str, char, num)
- includes_char(str, char)

3. String Lookup Functions
- indexOf(str, target)
- lastIndexOf(str, target)
- nth_indexOf(str, target, num)
- indexesOf(str, target)
- numIndexesOf(str, target)

4. String Conversion Functions
- lowercase(str)
- uppercase(str)

5. String Modification and Extraction Functions
- split(str, separator)
- insert(str, pos, new_str)
- remove(str, pos, length)
- insert_char(str, pos, char)
- remove_char(str, pos)
- reverse(str)
- fill_char(str, char, start_pos, end_pos)
- replace(str, target, new_str)
- replace_first(str, target, new_str)
- replace_last(str, target, new_str)
- replace_nth(str, target, new_str, num)
- replace_left(str, new_str)
- replace_right(str, new_str)
- replace_middle(str, pos, new_str)
- left(str, num)
- right(str, num)
- first_char(str)
- last_char(str)
- truncate(str, max_len)
- truncate_middle2(str, trunc_str, pos, max_len)
- truncate_from2(str, trunc_str, pos, max_len, side)
- concat(str1, str2, trunc_str, max_len, mode)
- concat_from(str1, str2, trunc_str, max_len, side, mode)
- trim(str)
- substr(str, pos, length)
- substring(str, start_pos, end_pos)
- strip(str, mask, target, is_allowed)
- extract_groups(str)
- extract_numbers(str, d1, d2, mode)
- str_to_float(str, d1, d2)
- str_to_int(str)
- extract_ranges(str, d1, d2, d3, type)

6. String Test Functions
- includes(str, target)
- starts_with(str, target)
- ends_with(str, target)
- str_compare(str1, str2)

7. Type Conversion Functions
- tf_check2(tf)
- tf_to_mins()
- convert_tf(tf)
- period_to_mins(tf)
- convert_tf2(tf)
- convert_tf3(tf)
- bool_to_str(flag)
- get_src(src_str)
- get_size(size_str)
- get_style(style)
- get_bool(bool_str)
- get_int(str)
- get_float(str, d1, d2)
- get_color(str, def_color)
- color_tr2(col_str, transp)
- get_month(str)
- month_name(num, format)
- weekday_name(num, format)
- dayofweek_name(t)

8. Date and Time Functions
- date_str(t, d)
- time_str(t, d)
- datetime_str(t, d1, d2)
- date2_str(t, d, type)
- time2_str(t, d, type)
- datetime2_str(t, d1, d2, format1, format2)
- date3_str(t, template)
- time3_str(t, template)
- datetime3_str(t, template)

9. Console Output & Helper Functions
- echo1(con, str)
- echo2(x, y, con, str)
- echo3(v_shift, con, str, msg_color, text_size)
- echo4(x, y, con, str, msg_style, msg_color, text_size, text_align, msg_xloc)
- echo5(x, y, con, str, msg_style, msg_color, text_size, text_align, msg_xloc)
- echo6(x, y, con, str)
- echo7(v_shift, con, str, msg_color, text_size)
- echo8(x, y, con, str, msg_style, msg_color, text_size, text_align, msg_xloc)
- echo9(x, y, con, str, msg_style, msg_color, text_size, text_align, msg_xloc)
- new_page(str, line_str, trunc_str, header_str, footer_str, length, page_count, page, mode)

6 mar 2021

Informacje o Wersji

Version 2.0

Changes in ver 2.0:
- new_page replaced with new_page2 - new pagination engine based on array of strings instead of a single large str
- pagination is now optional - when show_pages is disabed output can now exceed the string max_length = 4096 limit - everything is shown on a single page using array.join
- fixed pagination of unit test output
- fixed dividers for empty groups
- last page marker
- localized function processing in output loop - should facilitate tracing errors to a specific function
- new implementations of insert*, remove*, replace*, reverse* using array.slice and array.fill
- insert*, replace*, trim* now return source str by default if operation fails
- changed lowercase/uppercase{1,2} implementations to remove ext functions and minimize local scopes
- support for negative pos, length, num in all functions - invert function logic
- concat, concat_from replaced with concat2, concat_from2
- removed tf_check*, convert_tf{1,2}, number_to_str as deprecated - use convert_tf3 instead
- using base_str to shorten output ifs

Notes on Pagination Engine:
- single string pagination:
- old engine required new_page on every string concat inside for because str buffer must be cleared when max_length limit is reached to continue processing without triggering a "String Too Long" error
- another reason for new_page inside for - to exit loop early as soon as the target page is reached to speed up processing, however, each function call increases local scopes
- string array pagination:
- new engine is based on str_arr array of strings as opposed to a single large str and provides more flexibility
- it lets you precisely manipulate output by individual strings, not just the last string
- it can exceed the string max_length = 4096 limit making pagination optional
- it doesn't requre new_page2 to be used on every string concat inside for because string array buffer is virtually limitless, we can even call it only once after the loop, thus also reducing local scopes.
- new_page2 is still inside for providing early exit as soon as the target page is reached to speed up processing but it's not required.

12 mar 2021

Informacje o Wersji

Version 3.0

Changes in ver 3.0:
- completely reworked user/test output processing section
- added pre-generated live unit test output for many functions to show how they work with different params
- changes in truncate_middle2, truncate_from2, concat2, concat_from2. concat_from2 now returns the rejected part of str2.
- changes in replace*, nth_indexOf*, indexesOf*, replace_nth* to process target = "" as an in-between char existing before and after every char in str like in Javascript
- added set_char_at, replace_char
- changed new_page2 to dynamically update page footer

Notes:
- number of local scopes was dramatically reduced by grouping functions and merging user and test output into several large cycles, with user output being processed on the 1st iteration of each cycle
- this allowed to add test output for many key functions in script
- when dealing with extremely large scripts you have to cannibalize and rewrite already working code multiple times to try to squeeze in more features.
- Pinescript ultimately forces you to make bad decisions, such as:
- forget about good practices, creating perfect code, focus on creating potentially bad code that works instead - you will have to scrap/rewrite it to achieve even 75% of your goals anyway.
- remove/replace ifs with ?: degrading code logic, structure, readability and speed to reduce local scopes
- remove/replace functions with inline code and rely on redundant code in global scope instead of having a nice hierararchy of calls to reduce local scopes
- process/merge everything into a single huge cycle with complex logic prone to errors to reduce local scopes
- have many side projects to develop custom workarounds to overcome common language limitations
- have parts of code developed individually as test scripts that are incorporated into the main script to reduce 1 min compilation time
- this is what makes Pinescript development such a daunting task and leads to a giant waste of time, unlike in any other language
- nevertheless, I must say that Pinescript is getting better. I see huge improvements and more robust compilation engine, can now use the full power of arrays.
only 6 months ago it choked on 100kb 2000 lines and refused to compile all the time. Now I don't experience such things until maybe just these past few days with 5000 lines and 220kb size.
- typeof function is not possible