NEW FEATURE: User-Defined Types in Pine Script

 hey Traders welcome back to the blog first of all happy New Year I hope your Year is off to a great start uh before I took some time off for the holiday period the trading view developers released a sneaky update here to the pinescript language which is what I want to cover today in this year's first video I've already recorded this lesson I recorded a half hour lesson on this and then I just realized that my microphone wasn't recording for some reason and so that's a great start of the Year for me so let's do take two so what is the new feature that trading view have added to Pine scripts it is user defined types so what is a user-defined type well experienced programmers can think of these as methodless classes so if you've ever worked with other programming languages you'll be familiar with what a class is it's basically a object that contains functions and variables usually well this type this Pine script user defined type does not contain functions it only contains variables or Fields so now instead of using independent variables like pivot time and pivot level to track pivot data you can define a a pivot type with two fields to hold all of those values so in today's example we're just going to demonstrate how to use this new feature it's not a super practical example I couldn't really think of one to be honest to show you guys but basically all this does it's just a quality of life feature update particularly to help keep more complex scripts better organized and more efficient and so what this user-defined type does is it just holds a bunch of data types values variables grouped under a user-defined type value so before we jump into the pine Editor to break down this new feature let's look at the official documentation so before we start I should note here that this is Advanced material so if you're a beginner to Pine script this video is probably not for you and if you are a beginner to partnership make sure to go and check out my free panel script Basics course that will help jump start you on your path to mastering plan script it's completely free it's a couple of hours of content in that course and I also have tons of content on this YouTube channel just check out the pinescript Mastery playlist if you go through the majority of those lessons by the time time you're done with that you should be able to wrap your head around what we're doing here but for those of you who are not new to plan script and our experience let's jump into the documentation here so pint script user-defined objects are the equivalent of variables containing Parts called fields and each field is able to hold independent values that can be of various data types so here's an example of creating a user-defined type here we create a pivot point type that contains a bar index or timestamp a price value and the x-lock value so we'll explain what this all means in a moment but first let me find a more simple example here so this is just defining a simple user-defined type called bar info and this bar info type holds a bar index a bar timestamp and a Bar's closing price value and the VAR and varip keywords apply to all of the objects Fields so let's copy this code jump into the pane editor and break down what we're doing so here's our code I'll add it to the chart and break down what happening here so we've got two plots here two lanes plotting onto our chart the first one is plotting first bars index value this value here and the second one is plotting the current bars index value so let's add another plot on here let's add in Uh current bar will be more interesting let's do current bar dot C now this plot will be plotting the closing price I'll change the color to color dot green save our code and now we'll have a third line drawing here this green value is the current bars closing price and we're retrieving that closing price from our user-defined type so this line of code here is declaring a persistent data type and this data type is a bar info data type and this first bar variable is assigned to barinfo.new now because we are defining the default values for each field in this type we don't need to pass anything into this new function in order to create this type this first bar will contain the bar index the timestamp and the closing price of whichever bar this is called on and so in this case because this is a persistent variable it's only created once and then it does not update on every new bar on our chart if we want to change any values in this we need to override them so what's happening here if I go to the very first bar on our chart if I change this to firstbar.c save my code it's annoying that this pops up now every time you save your script that annoys me but anyway whatever it's worse things in the world so what's happening here is we're declaring first bar we're assigning first bar to a new bar info type and this new bar info type is being populated with these values here so when I hover my mouse over all these bars on my chart the first plot is going to remain zero because that's the first bar index on our chart we start counting bar indexes from zero and the green number is going to be the closing price of that very first bar on our chart now if I wanted to change first bars values for whatever reason there's two ways I can do this uh the first way let me get rid of these plots first of all and change this to firstbar dot T so now we're plotting all three values from our first bar data type and the second value is a timestamp that's why that number is massive so now what we could do is we could override these values if we wanted to so I could say firstbar dot I is assigned 33 for example let's assign all the values to 33. save my code now all these numbers will say 3 3. so that's how you can override a custom user-defined types of values that's one way you can do it the other way is when you're creating it so instead of allowing this bar info data type to populate its Fields with the default values here we can override them by specifying them in the parameters when creating this object so now when I save my code these numbers will all say 3 3 as well and if I wanted to only override one of these values let's say we want to override the time for whatever reason I can say t equals 3 3 well let's make it 4 4. Lewis Hamilton and uh there you go so the first value is still our bar index the second value is now 4 4 and the third value is still the closing price so that's how we deal with user-defined types it's pretty simple the main advantage of using these would be in more complex scripts it can help make your script more readable for one thing and in some cases it can make your script or your code more efficient for example the documentation says you can use these bar types to request data from the security function so instead of having like 10 values like say we wanted to get the ATR value and we wanted to get the RSI value and we wanted to get the volume value and the high value um instead of having these three uh these four different parameters and requesting them from the security function we could just declare a type here and we could have um indicator values equals float ATR value float RSI value float volume value and Float high value and what we could do is we could create a new variable here called bar ta for bar technical analysis and this could be set to indicator values dot new and then we could pass in the ATR over the past 14 bars the RSI over the past 14 bars the current bars volume and the current bars high and now we have all of these values contained within a single type and if we wanted to plot or or analyze any one of these values we could just simply pass in bar ta Dot RSI value and there we go we are plotting the RSI value and we're getting that value from our user-defined type and so you can see how this can just tidy up and better organize complex scripts with simple scripts you're probably never going to have any reason to use these but in more complex scripts they can be quite useful so let's cover a more complex example of using this new feature so there's a few examples in the documentation here let's copy the code from this one first so here we're using user-defined types to track pivot Points so each label on my chart here is a pivot high and I'll explain how we're tracking this data using this new user-defined type so first of all when you're detecting pivots using the inbuilt pivot function you need to tell pinescript how many bars to look left and how many bars to look right to detect That Swing high so this pivot here is not detected until 10 bars after the fact so legs input is how many legs how many bars look left and right the next thing we do is we Define our custom type this custom type has three fields or three values three parameters within it the first is an integer type the second a float the third a string the first value is a either a bar index or a bar timestamp the second value is a price value and the third value is an x-lock value I'm not sure what x-lock stands for I always think of it as X location but I could be wrong about that but it's not really important the next thing we do here is we detect any pivot high points so the TA dot pivot high will detect any swing highs that occur over a 10 bar look back to the left and a 10 bar look back technically it's a look back but think of it as a look forward from the pivot 10 bars to the right as well so 10 bars after this swing High the script will loop back 10 bars and loop forward 10 bars from this bar here and if it is the swing High the highest value over those 10 bars it's assigned to this value here the high price is assigned to Pivot high price if a pivot high is not detected so as you can see this impulsive move down here there is no swing highs that occur where the bar is the highest bar 10 bars left and right so pivot high price during this sort of price action will be set to n a or null and so what we can do is we can use an if statement here to check if pivot high price is not an a that means we have a legitimate pivot price value detected and this code here gets executed and what we do in this code here is we check if a new pivot high was found display a label where it occurred so first of all we use our custom user-defined type to store these values so we use Pivot Point dot new to define a new pivot point and we pass in the timestamp of the pivot high so remember that needs to be 10 bars back so we pass in our legs input into the historical operator here so we get the time stamp from the pivot point 10 bars back and then we also pass in the high price of that bar and now we can use found point to tell the label where to draw itself and what text to put on the label so first of all if I bring up the documentation for the label the arguments this label function takes is an X parameter so that's a bar index or a timestamp the Y value is the price of the label position and then we need to give it some text and there's some other optional parameters here we also need to tell it what our x value is is it a bar index or is it a bar timestamp so by default our Pivot Point type tells this label that we want x-lock to be a timestamp we could override this if we wanted to as I showed you in the previous example we could change this to xlog.bar index and now x-lock is going to specify X as a bar index but we'll leave the default parameter here as bar time and so for our label we're passing in the bars timestamp stored within our custom object here our found Point object we're passing in the Y value which is the pivot high price where converting that pivot High into a string and rounding off the decimal places to the minimum decimal place here that's what mintech is it's the minimum tick value that shaves off any excess decimal places after the decimal and then we tell this label that we want our x-lock value to be a bar timestamp and we pass in our text color now in this particular example this is just showing you how to use user-defined types if you were doing something like this you probably wouldn't use a user-defined type it's just unnecessary we could achieve exactly the same thing by getting rid of all this changing this to this and this to this get rid of that and change this to x-lock dot bar time now this will achieve exactly the same thing whoops I've got an excess comma there this will achieve exactly the same thing but with less lines of code but as you can see it is slightly less readable so the main advantage of using these user-defined types is one to make your scripts more readable when dealing with lots of parameters that can get a bit confusing to the eye or to make your script more efficient when dealing with a lot of parameters in a more complex script but for the most part you're not going to be using user-defined types very often but the beauty of panscript is it allows you to do these sorts of things if you need to you can make your scripts as complex and sophisticated as you want or as simple and stripped back as you want there's many different ways to achieve things in pan script this just gives us another way of organizing our variables and so before I wrap up this lesson let's look at a slightly more complex application of this new user-defined type so back on the documentation here I'm going to scroll down to this example here where we're doing exactly the same thing we're detecting pivot Highs but we're also drawing a line between them so I'm going to copy all of this code here and we'll break down what's Happening Here We Go save the script we'll be getting exactly the same thing but now we have a line drawing connecting our pivots so same look back period 10 bars left and right now our Pivot Point type is changed a little bit here this version of the Pivot Point type does not explicitly Define what our x-lock is because we're just going to hard code our script to treat x-lock as a bar timestamp and we don't need to store that in the pivot point but we still need the bar timestamp of our pivot so that's the opening time of the pivot bar and the price level so this could also be called price but I'll leave it as level for now so in this example the documentation is demonstrating how to use user-defined types in an array so what we're doing here is we're creating an empty Pivot Point array so we're creating an array with the data type pivot point and then what we're doing just like the previous example we are detecting pivot highs over our look back period of 10 bars left and right and if a pivot high is detected then we we create a new Pivot Point data type so Pivot Point dot new creates a new Pivot Point type we pass in the bar time of that pivot so remember this gets to detected 10 bars after the fact so we need to pass in our historical operator here and our look back value so we're getting the timestamp 10 bars back once that pivot is confirmed and we're also passing in the high price of that pivot once we've created our new pivot data type we push that or insert that into our array so the array.push function takes an array ID then once we have that new pivot data type we push or insert that into our array using the array.push function we need to pass in an array ID so we're passing in our pivot array and we're inserting or pushing our new pivot object into that array and so we're collecting and storing these pivot Points as they occur and then here on the very last confirmed bar on our chart so the last closed bar if we are on that bar then this code gets executed and what this code is doing is we're declaring a persistent variable it's a pivot point data type how custom Pivot Point data type and this stores the previous pivot point so that we can draw a line from there to the current Pivot Point and how we do that is we Loop through our array so this is what is called a for each Loop so there's two different types of for Loops in pi in most languages so for example we could make a counter so 4i equals 0 to 10 would loop from 0 to 10 and whatever code is in here uh can reference that Loop counter another option for looping is the for each Loop so what this for Loop does is it says four each value of x within our array do something with x so in this case X is a pivot point data type and so for each Loop in this for Loop we can reference each pivot so this will start from the first object in our array and loop all the way to the last object in our array and so this code here is creating first it's creating a label and then drawing a line between those two points so to display the label we're creating a new label we pass in our bars open type for each value in our array each object in our array so this will draw a label at the pivots open Time bar timestamp and the pivots price value we're passing in the price value as a string we're telling Pines script that we want our x value to be a timestamp and not a bar index in most cases you can use bar indexes and bar time stamps interchangeably but for this example we're using bar time and we're specifying the text color to be white now for our y value if you wanted to make this label draw a bit higher right now it's drawing right on that high value but if you wanted to raise this by let's say 100 points or 10 Pips in Forex we could add in a addition here we can add Sim info dot minimum tick multiplied by 100 that would raise our label by 100 points so if I save my code the label jumps up by 100 points or in 4X that would be one pip but anyway the next thing we do is we check if our previous pivot point is not n a so when our very first pivot point is detected this will be n a because we don't have a previous pivot point and so that is not the case that means we have more than one pivot point so previous pivot point is not n a then we want to create a new line and this line is drawing from the previous pivot Points open time so using this as an example the line starts on this Bar's timestamp and it starts from this Bar's swing high price and it draws to the current pivot Points Bar times down and the current pivot Points swing High and again just like the label we need to specify what our x value is in this case our x value is not a bar index but a timestamp and then notice that this is not within the scope of our if statement here it's not indented or tabbed and so on each for Loop we assign previous point to the current object in our loop from our array and so as we Loop through all of the pivots that we've detected on our chart we connect the line from the previous pivot to the current pivot over and over and over again that's how we get this joining line anyway that will about do it for today's lesson as I mentioned this is not a particularly practical example of how to use user-defined types because we can achieve this exact same thing with less lines of Code by simply referencing our pivot high price and the time value explicitly without needing to store them within a custom data type but this is just a simple example of how to use data types user defined data types obviously if you've got a complex script it would make more sense to use this new feature or if you've got a script where the variables you're working with the values you're working with are sort of hard for you to interpret very quickly at a glance so if you're dealing with like 10 different values that all have parameter names that are not super intuitive to the eye you can group them all under a user data type that might make it a little bit easier to read your script when dealing with complex code that would be the main reason I would use something like this personally would be to better organize a complex script so that I can read it easier other than that there's not really any major advantage to using these user defined data types as I said at the beginning of the video this is just a quality of life update to make coding in some cases more efficient but mostly just easier to read it does say in the documentation that you can use these custom data types to request data from the security function that could be quite useful for example if you wanted to get the the higher time for let's say the daily chart we wanted to get the daily charts RSI value ATR value adx value and the macd value let's say we wanted to get like 10 different indicator values from the security function we could Define all of those values within a user-defined data type and then pass that data type into the security function to request all of those values and then we could reference those values as I showed you at the start of this lesson we could reference all of those values in a more intuitive way instead of having all of those values written out individually as variables we could just have one data type that stores all of those different values that would be a good example of when you might want to use user-defined data types however I haven't quite figured out how to use the user to find data types to pass into the security function yet so perhaps in a future lesson when we're dealing with the security function I'll include an example of how to do that then but for now I'm going to wrap this video up here if you have a creative reason why you personally would want to use these data types in your scripts please let me know in the comments section I would love to know your thoughts on how best to apply this new feature personally I can't really think of many ways I would use it but I'm sure some of you out there will have some great suggestions with that said I will speak with you in the next video take care best of luck with your trading and I hope 2023 is your best year yet