Methods

Introduction

Pine Script™ methods are specialized functions associated with values of specific built-in types, user-defined types, or enum types. They behave the same as regular functions in most regards while offering a shorter, more convenient syntax. Users can access methods using dot notation syntax on variables of the associated type, similar to accessing the fields of a Pine Script™ object.

Built-in methods

Pine Script™ includes built-in methods for all special types, including array, matrix, map, line, linefill, box, polyline, label, and table. These methods provide users with a more concise way to call specialized routines for these types within their scripts.

When using these special types, the expressions:

<namespace>.<functionName>([paramName =] <objectName>, …)

and:

<objectName>.<functionName>(…)

are equivalent. For example, rather than using:

to get the value from an array id at the specified index, we can simply use:

to achieve the same effect. This notation eliminates the need for users to reference the function’s namespace, as get() is a method of id in this context.

Written below is a practical example to demonstrate the usage of built-in methods in place of functions.

The following script computes Bollinger Bands over a specified number of prices sampled once every n bars. It calls array.push() and array.shift() to queue sourceInput values through the sourceArray, then array.avg() and array.stdev() to compute the sampleMean and sampleDev. The script then uses these values to calculate the highBand and lowBand, which it plots on the chart along with the sampleMean:

Let’s rewrite this code to utilize methods rather than built-in functions. In this version, we have replaced all built-in array.* functions in the script with equivalent methods:

Note that:

• We call the array methods using sourceArray.* rather than referencing the array namespace.
• We do not include sourceArray as a parameter when we call the methods since they already reference the object.

User-defined methods

Pine Script™ allows users to define custom methods for use with objects of any built-in or user-defined type. Defining a method is essentially the same as defining a function, but with two key differences:

• The method keyword must be included before the function name.
• The type of the first parameter in the signature must be explicitly declared, as it represents the type of object that the method will be associated with.

[export] method <functionName>(<paramType> <paramName> [= <defaultValue>], …) =>
    <functionBlock>

Let’s apply user-defined methods to our previous Bollinger Bands example to encapsulate operations from the global scope, which will simplify the code and promote reusability. See this portion from the example:

We will start by defining a simple method to queue values through an array in a single call.

This maintainQueue() method invokes the push() and shift() methods on a srcArray when takeSample is true and returns the object:

Note that:

• Just as with user-defined functions, we use the @function compiler annotation to document method descriptions.

Now we can replace sourceArray.push() and sourceArray.shift() with sourceArray.maintainQueue() in our example:

From here, we will further simplify our code by defining a method that handles all Bollinger Band calculations within its scope.

This calcBB() method invokes the avg() and stdev() methods on a srcArray to update mean and dev values when calculate is true. The method uses these values to return a tuple containing the basis, upper band, and lower band values respectively:

With this method, we can now remove Bollinger Band calculations from the global scope and improve code readability:

Note that:

• Rather than using an if block in the global scope, we have defined a newSample variable that is only true once every n bars. The maintainQueue() and calcBB() methods use this value for their respective takeSample and calculate parameters.
• Since the maintainQueue() method returns the object that it references, we’re able to call calcBB() from the same line of code, as both methods apply to array<float> instances.

Here is how the full script example looks now that we’ve applied our user-defined methods:

Method overloading

User-defined methods can override and overload existing built-in and user-defined methods with the same identifier. This capability allows users to define multiple routines associated with different parameter signatures under the same method name.

As a simple example, suppose we want to define a method to identify a variable’s type. Since we must explicitly specify the type of object associated with a user-defined method, we will need to define overloads for each type that we want it to recognize.

Below, we have defined a getType() method that returns a string representation of a variable’s type with overloads for the five primitive types:

Now we can use these overloads to inspect some variables. This script uses str.format() to format the results from calling the getType() method on five different variables into a single results string, then displays the string in the lbl label using the built-in set_text() method:

Note that:

• The underlying type of each variable determines which overload of getType() the compiler will use.
• The method will append “(na)” to the output string when a variable is na to demarcate that it is empty.

Advanced example

Let’s apply what we’ve learned to construct a script that estimates the cumulative distribution of elements in an array, meaning the fraction of elements in the array that are less than or equal to any given value.

There are many ways in which we could choose to tackle this objective. For this example, we will start by defining a method to replace elements of an array, which will help us count the occurrences of elements within a range of values.

Written below is an overload of the built-in fill() method for array<float> instances. This overload replaces elements in a srcArray within the range between the lowerBound and upperBound with an innerValue, and replaces all elements outside the range with an outerValue:

With this method, we can filter an array by value ranges to produce an array of occurrences. For example, the expression:

copies the srcArray object, replaces all elements between min and val with 1.0, then replaces all elements above val with 0.0. From here, it’s easy to estimate the output of the cumulative distribution function at the val, as it’s simply the average of the resulting array:

Note that:

• The compiler will only use this fill() overload instead of the built-in when the user provides innerValue, outerValue, lowerBound, and upperBound arguments in the call.
• If either lowerBound or upperBound is na, its value is ignored while filtering the fill range.
• We are able to call copy(), fill(), and avg() successively on the same line of code because the first two methods return an array<float> instance.

We can now use this to define a method that will calculate our empirical distribution values. The following eCDF() method estimates a number of evenly spaced ascending steps from the cumulative distribution function of a srcArray and pushes the results into a cdfArray:

Lastly, to ensure that our eCDF() method functions properly for arrays containing small and large values, we will define a method to normalize our arrays.

This featureScale() method uses array min() and range() methods to produce a rescaled copy of a srcArray. We will use this to normalize our arrays prior to invoking the eCDF() method:

Note that:

• This method does not include special handling for divide by zero conditions. If rng is 0, the value of the array element will be na.

The full example below queues a sourceArray of size length with sourceInput values using our previous maintainQueue() method, normalizes the array’s elements using the featureScale() method, then calls the eCDF() method to get an array of estimates for n evenly spaced steps on the distribution. The script then calls a user-defined makeLabel() function to display the estimates and prices in a label on the right side of the chart: