Pinescript - Common Label & Line Array Functions Library by RagingRocketBull 2021 Version 1.0
This script provides a library of common array functions for arrays of label and line objects with live testing of all functions. Using this library you can easily create, update, delete, join label/line object arrays, and get/set properties of individual label/line object array items. You can find the full list of supported label/line array functions below.
There are several libraries: - Common String Functions Library - Standard Array Functions Library - Common Fixed Type Array Functions Library - Common Label & Line Array Functions Library - Common Variable Type Array Functions Library
Features: - 30 array functions in categories create/update/delete/join/get/set with support for both label/line objects (45+ including all implementations) - Create, Update label/line object arrays from list/array params - GET/SET properties of individual label/line array items by index - Join label/line objects/arrays into a single string for output - Supports User Input of x,y coords of 5 different types: abs/rel/rel%/inc/inc% list/array, auto transforms x,y input into list/array based on type, base and xloc, translates rel into abs bar indexes - Supports User Input of lists with shortened names of string properties, auto expands all standard string properties to their full names for use in functions - Live Output for all/selected functions based on User Input. Test any function for possible errors you may encounter before using in script. - Output filters: hide all excluded and show only allowed functions using a list of function names - Output Panel customization options: set custom style, color, text size, and line spacing
Usage: - select create function - create label/line arrays from lists or arrays (optional). Doesn't affect the update functions. The only change in output should be function name regardless of the selected implementation. - specify num_objects [0..7] for both label/line arrays (default is 7) - specify common anchor point settings x,y base/type for both label/line arrays and GET/SET items in Common Settings - fill lists with items to use as inputs for create label/line array functions in Create Label/Line Arrays section - specify label/line array item index and properties to SET in corresponding sections - select label/line SET function to see the changes applied live
Code Structure: - translate x,y depending on x,y type, base and xloc as specified in UI (required for all functions) - expand all shortened standard property names to full names (required for create/update* from arrays and set* functions, not needed for create/update* from lists) to prevent errors in label.new and line.new - create param arrays from string lists (required for create/update* from arrays and set* functions, not needed for create/update* from lists) - create label/line array from string lists (property names are auto expanded) or param arrays (requires already expanded properties) - update entire label/line array or - get/set label/line array item properties by index
Transforming/Expanding Input values: - for this script to work on any chart regardless of price/scale, all x*,y* are specified as % increase relative to x0,y0 base levels by default, but user can enter abs x,price values specific for that chart if necessary. - all lists can be empty, contain 1 or several items, have the same/different lengths. Array Length = min(min(len(list*)), mum_objects) is used to create label/line objects. Missing list items are replaced with default property values. - when a list contains only 1 item it is duplicated (label name/tooltip is also auto incremented) to match the calculated Array Length - since this script processes user input, all x,y values must be translated to abs bar indexes before passing them to functions. Your script may provide all data internally and doesn't require this step. - at first int x, float y arrays are created from user string lists, transformed as described below and returned as x,y arrays. - translated x,y arrays can then be passed to create from arrays function or can be converted back to x,y string lists for the create from lists function if necessary. - all translation logic is separated from create/update/set functions for the following reasons: - to avoid redundant code/dependency on ext functions/reduce local scopes and to be able to translate everything only once in one place - should be faster - to simplify internal logic of all functions - because your script may provide all data internally without user input and won't need the translation step - there are 5 types available for both x,y: abs, rel, rel%, inc, inc%. In addition to that, x can be: bar index or time, y is always price. - abs - absolute bar index/time from start bar0 (x) or price (y) from 0, is >= 0 - rel - relative bar index/time from cur bar n (x) or price from y0 base level, is >= 0 - rel% - relative % increase of bar index/time (x) or price (y) from corresponding base level (x0 or y0), can be <=> 0 - inc - relative increment (step) for each new level of bar index/time (x) or price (y) from corresponding base level (x0 or y0), can be <=> 0 - inc% - relative % increment (% step) for each new level of bar index/time (x) or price (y) from corresponding base level (x0 or y0), can be <=> 0 - x base level >= 0 - y base level can be 0 (empty) or open, close, high, low of cur bar - single item x1_list = "50" translates into: - for x type abs: "50, 50, 50 ..." num_objects times regardless of xloc => x = 50 - for x type rel: "50, 50, 50 ... " num_objects times => x = x_base + 50 - for x type rel%: "50%, 50%, 50% ... " num_objects times => x_base * (1 + 0.5) - for x type inc: "0, 50, 100 ... " num_objects times => x_base + 50 * i - for x type inc%: "0%, 50%, 100% ... " num_objects times => x_base * (1 + 0.5 * i) - when xloc = xloc.bar_index each rel*/inc* value in the above list is then subtracted from n: n - x to convert rel to abs bar index, values of abs type are not affected - x1_list = "0, 50, 100, ..." of type rel is the same as "50" of type inc - x1_list = "50, 50, 50, ..." of type abs/rel/rel% produces a sequence of the same values and can be shortened to just "50" - single item y1_list = "2" translates into (ragardless of yloc): - for y type abs: "2, 2, 2 ..." num_objects times => y = 2 - for y type rel: "2, 2, 2 ... " num_objects times => y = y_base + 2 - for y type rel%: "2%, 2%, 2% ... " num_objects times => y = y_base * (1 + 0.02) - for y type inc: "0, 2, 4 ... " num_objects times => y = y_base + 2 * i - for y type inc%: "0%, 2%, 4% ... " num_objects times => y = y_base * (1 + 0.02 * i) - when yloc != yloc.price all calculated values above are simply ignored - y1_list = "0, 2, 4" of type rel% is the same as "2" with type inc% - y1_list = "2, 2, 2" of type abs/rel/rel% produces a sequence of the same values and can be shortened to just "2" - you can enter shortened property names in lists. To lookup supported shortened names use corresponding dropdowns in Set Label/Line Array Item Properties sections - all shortened standard property names must be expanded to full names (required for create/update* from arrays and set* functions, not needed for create/update* from lists) to prevent errors in label.new and line.new - examples of shortened property names that can be used in lists: bar_index, large, solid, label_right, white, left, left, price - expanded to their corresponding full names: xloc.bar_index, size.large, line.style_solid, label.style_label_right, color.white, text.align_left, extend.left, yloc.price - all expanding logic is separated from create/update* from arrays and set* functions for the same reasons as above, and because param arrays already have different types, implying the use of final values. - all expanding logic is included in the create/update* from lists functions because it seemed more natural to process string lists from user input directly inside the function, since they are already strings.
Creating Label/Line Objects: - use study max_lines_count and max_labels_count params to increase the max number of label/line objects to 500 (+3) if necessary. Default number of label/line objects is 50 (+3) - all functions use standard param sequence from methods in reference, except style always comes before colors. - standard label/line.get* functions only return a few properties, you can't read style, color, width etc. - label.new(na, na, "") will still create a label with x = n-301, y = NaN, text = "" because max default scope for a var is 300 bars back. - there are 2 types of color na, label color requires color(na) instead of color_na to prevent error. text_color and line_color can be color_na - for line to be visible both x1, x2 ends must be visible on screen, also when y1 == y2 => abs(x1 - x2) >= 2 bars => line is visible - xloc.bar_index line uses abs x1, x2 indexes and can only be within 0 and n ends, where n <= 5000 bars (free accounts) or 10000 bars (paid accounts) limit, can't be plotted into the future - xloc.bar_time line uses abs x1, x2 times, can't go past bar0 time but can continue past cur bar time into the future, doesn't have a length limit in bars. - xloc.bar_time line with length = exact number of bars can be plotted only within bar0 and cur bar, can't be plotted into the future reliably because of future gaps due to sessions on some charts - xloc.bar_index line can't be created on bar 0 with fixed length value because there's only 1 bar of horiz length - it can be created on cur bar using fixed length x < n <= 5000 or - created on bar0 using na and then assigned final x* values on cur bar using set_x* - created on bar0 using n - fixed_length x and then updated on cur bar using set_x*, where n <= 5000 - default orientation of lines (for style_arrow* and extend) is from left to right (from bar 50 to bar 0), it reverses when x1 and x2 are swapped - price is a function, not a line object property
Variable Type Arrays: - you can't create an if/function that returns var type value/array - compiler uses strict types and doesn't allow that - however you can assign array of any type to another array of any type creating an arr pointer of invalid type that must be reassigned to a matching array type before used in any expression to prevent error - create_any_array2 uses this loophole to return an int_arr pointer of a var type array - this works for all array types defined with/without var keyword and doesn't work for string arrays defined with var keyword for some reason - you can't do this with var type vars, only var type arrays because arrays are pointers passed by reference, while vars are actual values passed by value. - you can only pass a var type value/array param to a function if all functions inside support every type - otherwise error - alternatively values of every type must be passed simultaneously and processed separately by corresponding if branches/functions supporting these particular types returning a common single type result - get_var_types solves this problem by generating a list of dummy values of every possible type including the source type, tricking the compiler into allowing a single valid branch to execute without error, while ignoring all dummy results
Notes: - uses Pinescript v3 Compatibility Framework - uses Common String Functions Library, Common Fixed Type Array Functions Library, Common Variable Type Array Functions Library - has to be a separate script to reduce the number of local scopes/compiled file size, can't be merged with another library. - lets you live test all label/line array functions for errors. If you see an error - change params in UI - if you see "Loop too long" error - hide/unhide or reattach the script - if you see "Chart references too many candles" error - change x type or value between abs/rel*. This can happen on charts with 5000+ bars when a rel bar index x is passed to label.new or line.new instead of abs bar index n - x - create/update_label/line_array* use string lists, while create/update_label/line_array_from_arrays* use array params to create label/line arrays. "from_lists" is dropped to shorten the names of the most commonly used functions. - create_label/line_array2,4 are preferable, 5,6 are listed for pure demonstration purposes only - don't use them, they don't improve anything but dramatically increase local scopes/compiled file size - for this reason you would mainly be using create/update_label/line_array2,4 for list params or create/update_label/line_array_from_arrays2 for array params - all update functions are executed after each create as proof of work and can be disabled. Only create functions are required. Use update functions when necessary - when list/array params are changed by your script. - both lists and array item properties use the same x,y_type, x,y_base from common settings - doesn't use pagination, a single str contains all output - why is this so complicated? What are all these functions for? - this script merges standard label/line object methods with standard array functions to create a powerful set of label/line object array functions to simplify manipulation of these arrays. - this library also extends the functionality of Common Variable Type Array Functions Library providing support for label/line types in var type array functions (any_to_str6, join_any_array5) - creating arrays from either lists or arrays adds a level of flexibility that comes with complexity. It's very likely that in your script you'd have to deal with both string lists as input, and arrays internally, once everything is converted. - processing user input, allowing customization and targeting for any chart adds a whole new layer of complexity, all inputs must be translated and expanded before used in functions. - different function implementations can increase/reduce local scopes and compiled file size. Select a version that best suits your needs. Creating complex scripts often requires rewriting your code multiple times to fit the limits, every line matters.
P.S. Don't rely too much on labels, for too often they are fables.
List of functions*: * - functions from other libraries are not listed
@LonesomeTheBlue, thank you, I appreciate it, a new version is coming soon
PineCoders
⋅
JavierFL
⋅
This is great! Does it work for version 5?
kurtsmock
⋅
Whew... I made it to the comment section. I'm exhaused.... think I need to sit down. That was a lot of scrolling =P Is there a longest script badge we can give you for this? Amazing work. Ha! I came all this way just to say it.
Pinescript now supports large ~250kb scripts with 5000-6000 lines of code without major problems. The script must compile to max 60000 bytes size and have max 500 local scopes (total number of ifs, functions and fors) - these are the main bottlenecks now. Considering that just 6 month ago the compiler chocked on/refused to compile 100kb scripts with only 2000 lines even when many of those were used for comments, not to mention the lack of arrays of any kind - that's a major improvement. The compiler ignores all unused functions, so you can get away with large file sizes to some extent.
- The primary reason for a large size is the lack of support for modules/libraries - you must include all the code from external libraries in you script. And when you have 5-6 libraries x 5000 lines each ~= 30000 lines of code just to, say, create a label array!
- Another reason is different versions of the same functions all having different footprint in local scopes and compiled file size with ranging execution speed, full/reduced functionality, better/worse readability. When dealing with complex scripts a developer MUST rewrite the already working code at least several times to fit the limits of Pinescript and make it compile together with the new code. That's why you'd have to improvise and come up with at least 5-7 different versions of all your functions anyway, or even remove some functions - move function code into global scope as extreme measure to free a few local scopes. That's the reality of the language you're dealing with, so the sooner you develop a habit of writing code variations the better. I'm simply saving you some time and showing how this can be done.
On a bright side - a new even larger version is coming with get/set support for entire arrays, varip and random values. So, keep your coffee hot and expectations high.
kurtsmock
⋅
@RagingRocketBull, These are all amazing points. I would get so frustrated in the past when my 1,600 line script would timeout. Then you hide, unhide, let load, fail.. Hide, unhide, load, fail. It really made me give up on certain ideas. One that that would be amazing is to get libraries like you have in EL. Historical intrabar data would also be REALLY nice. not necessary because we're not trading historical bars, but still nice for backtesting and stuff. I appreciate your work. Very nice
RagingRocketBull
⋅
@kurtsmock, yes, that's the cost of development. I agree, but that's entirely up to TradingView. It's not possible to backtest varip strategies as there is no intrabar tick data for history. I hope that some of your ideas are now a possibility. I plan to revive a few of my own, but I can't keep up with all my scripts as the devs keep rolling out more and more new features :)