DrawZigZag

🟩 OVERVIEW

This library draws zigzag lines for existing pivots. It is designed to be simple to use. If your script creates pivots and you want to join them up while handling edge cases, this library does that quickly and efficiently. If you want your pivots created for you, choose one of the many other zigzag libraries that do that.

🟩 HOW TO USE

Pine Script libraries contain reusable code for importing into indicators. You do not need to copy any code out of here. Just import the library and call the function you want.
For example, for version 1 of this library, import it like this:

import SimpleCryptoLife/DrawZigZag/1

See the EXAMPLE USAGE sections within the library for examples of calling the functions.
For more information on libraries and incorporating them into your scripts, see the Libraries section of the Pine Script User Manual.


🟩 WHAT IT DOES

I looked at every zigzag library on TradingView, after finishing this one. They all seemed to fall into two groups in terms of functionality:
 • Create the pivots themselves, using a combination of Williams-style pivots and sometimes price distance.
 • Require an array of pivot information, often in a format that uses user-defined types.

My library takes a completely different approach.
Firstly, it only does the drawing. It doesn't calculate the pivots for you. This isn't laziness. There are so many ways to define pivots and that should be up to you. If you've followed my work on market structure you know what I think of Williams pivots.

Secondly, when you pass information about your pivots to the library function, you only need the minimum of pivot information -- whether it's a High or Low pivot, the price, and the bar index. Pass these as normal variables -- bools, ints, and floats -- on the fly as your pivots confirm. It is completely agnostic as to how you derive your pivots. If they are confirmed an arbitrary number of bars after they happen, that's fine.

So why even bother using it if all it does it draw some lines?
Turns out there is quite some logic needed in order to connect highs and lows in the right way, and to handle edge cases. This is the kind of thing one can happily outsource.


🟩 THE RULES

 • Zigs and zags must alternate between Highs and Lows. We never connect a High to a High or a Low to a Low.
 • If a candle has both a High and Low pivot confirmed on it, the first line is drawn to the end of the candle that is the opposite to the previous pivot. Then the next line goes vertically through the candle to the other end, and then after that continues normally.
 • If we draw a line up from a Low to a High pivot, and another High pivot comes in higher, we *extend* the line up, and the same for lines down. Yes this is a form of repainting. It is in my opinion the only way to end up with a correct structure.
 • We ignore lower highs on the way up and higher lows on the way down.


🟩 WHAT'S COOL ABOUT THIS LIBRARY

 • It's simple and lightweight: no exported user-defined types, no helper methods, no matrices.
 • It's really fast. In my profiling it runs at about ~50ms, and changing the options (e.g., trimming the array) doesn't make very much difference.
 • You only need to call one function, which does all the calculations and draws all lines.
 • There are two variations of this function though -- one simple function that just draws lines, and one slightly more advanced method that modifies an array containing the lines. If you don't know which one you want, use the simpler one.


🟩 GEEK STUFF

 • There are no dependencies on other libraries.
 • I tried to make the logic as clear as I could and comment it appropriately.
 • In the `f_drawZigZags` function, the line variable is declared using the `var` keyword *inside* the function, for simplicity. For this reason, it persists between function calls *only* if the function is called from the global scope or a local if block. In general, if a function is called from inside a loop, or multiple times from different contexts, persistent variables inside that function are re-initialised on each call. In this case, this re-initialisation would mean that the function loses track of the previous line, resulting in incorrect drawings. This is why you cannot call the `f_drawZigZags` function from a loop (not that there's any reason to). The `m_drawZigZagsArray` does not use any internal `var` variables.
 • The function itself takes a Boolean parameter `_showZigZag`, which turns the drawings on and off, so there is no need to call the function conditionally. In the examples, we do call the functions from an if block, purely as an illustration of how to increase performance by restricting the amount of code that needs to be run.


🟩 BRING ON THE FUNCTIONS

f_drawZigZags(_showZigZag, _isHighPivot, _isLowPivot, _highPivotPrice, _lowPivotPrice, _pivotIndex, _zigzagWidth, _lineStyle, _upZigColour, _downZagColour)
  This function creates or extends the latest zigzag line. Takes real-time information about pivots and draws lines. It does not calculate the pivots. It must be called once per script and cannot be called from a loop.
  Parameters:
    _showZigZag (bool): Whether to show the zigzag lines.
    _isHighPivot (bool): Whether the current bar confirms a high pivot. Note that pivots are confirmed after the bar in which they occur.
    _isLowPivot (bool): Whether the current bar confirms a low pivot.
    _highPivotPrice (float): The price of the high pivot that was confirmed this bar. It is NOT the high price of the current bar.
    _lowPivotPrice (float): The price of the low pivot that was confirmed this bar. It is NOT the low price of the current bar.
    _pivotIndex (int): The bar index of the pivot that was confirmed this bar. This is not an offset. It's the `bar_index` value of the pivot.
    _zigzagWidth (int): The width of the zigzag lines.
    _lineStyle (string): The style of the zigzag lines.
    _upZigColour (color): The colour of the up zigzag lines.
    _downZagColour (color): The colour of the down zigzag lines.
  Returns: The function has no explicit returns. As a side effect, it draws or updates zigzag lines.

method m_drawZigZagsArray(_a_zigZagLines, _showZigZag, _isHighPivot, _isLowPivot, _highPivotPrice, _lowPivotPrice, _pivotIndex, _zigzagWidth, _lineStyle, _upZigColour, _downZagColour, _trimArray)
  Namespace types: array<line>
  Parameters:
    _a_zigZagLines (array<line>)
    _showZigZag (bool): Whether to show the zigzag lines.
    _isHighPivot (bool): Whether the current bar confirms a high pivot. Note that pivots are usually confirmed after the bar in which they occur.
    _isLowPivot (bool): Whether the current bar confirms a low pivot.
    _highPivotPrice (float): The price of the high pivot that was confirmed this bar. It is NOT the high price of the current bar.
    _lowPivotPrice (float): The price of the low pivot that was confirmed this bar. It is NOT the low price of the current bar.
    _pivotIndex (int): The bar index of the pivot that was confirmed this bar. This is not an offset. It's the `bar_index` value of the pivot.
    _zigzagWidth (int): The width of the zigzag lines.
    _lineStyle (string): The style of the zigzag lines.
    _upZigColour (color): The colour of the up zigzag lines.
    _downZagColour (color): The colour of the down zigzag lines.
    _trimArray (bool): If true, the array of lines is kept to a maximum size of two lines (the line elements are not deleted). If false (the default), the array is kept to a maximum of 500 lines (the maximum number of line objects a single Pine script can display).
  Returns: This function has no explicit returns but it modifies a global array of zigzag lines.