Support

        Equilla Quick Start

Arrays

The following article offers an introduction to arrays in Equilla.

Arrays in Equilla are similar to those in other programming languages. They are data fields designed to contain large quantities of data. Each piece of data can be retrieved via the unique position (index) in the array. With the help of additional functions delivered with Tradesignal, a wide range of applications can be covered with arrays.

Arrays are set to replace the Equilla Vectors of earlier Tradesignal versions. Any current script with vectors can easily be modified to use arrays instead.

 

What is an Array?

In the basic Equilla article, variables were introduced as being "containers with an identification number". Via the name of the variable, existing contents can be called up or new contents can be assigned to the variable. 

While you can only save one value per variable, arrays are a lot more flexible - an infinite number of values can be put into an array. To expand the container comparison: arrays are containers that include an unlimited number of storage spaces, like boxes in a container. Each box can be retrieved by its index (unique position in the array).

By taking this container analogy one step further to a stack of containers, we get to multidimensional arrays, most commonly described as arrays of arrays.

 

Array Declaration

An array is treated similar to a variable. They are declared in a special declaration block starting with the keyword Arrays. The name of the array variable has to be followed by a pair of square brackets.

Arrays: 
    myVeryFirstArray[];

This array is initally empty and can later be resized to hold as many items as you wish to store in it.

If you know in advance how many items you want to store in your array and don't want to be able to resize it at a later time, you can declare it in this way.

Arrays: 
    myFixedSizeArray[10];

This creates an array with a maximum valid index of 10, but since indices start at 0, you can store 11 items in this array. Builtin functions ignore index 0, so you should not use this place if you plan to use the builtin functions.

The declaration of a multidimensional array looks like this:

Arrays: 
    my2DArray[3,4];

This array can be interpreted as a spreadsheet having rows and columns.

[0,0] [0,1] [0,2] [0,3] [0,4]

[1,0] [1,1] [1,2] [1,3] [1,4]

[2,0] [2,1] [2,2] [2,3] [2,4]

[3,0] [3,1] [3,2] [3,3] [3,4]

A builtin function would ignore any index containing a 0, but you are free to use these items to store e.g. sums per row and column.

As with variables, you can create a global array. This way it is possible to call up the array from several scripts. Global array are defined just like global variables by adding a namespace for your global variables and :: in front of the array name.

Arrays: 
    myGlobals::myGlobalArray[];

Accessing Items in an Array

The storage places inside an array are adressed using the array name followed by the unique index in square brackets.

Arrays: 
    myArray[10];
// assigns 23 to the storage place with index 1
myArray[1= 23;
// prints the value contained in storage place with index 1, i.e. 23
Print( myArray[1] );

Arrays can include all data types available in Equilla.

Output Catenated Data

If you want to output the complete content of a array in a quick and easy way, you can use several builtin functions. You can just use the print command and all items stored in the array will be printed.

Arrays: 
    myArray[];
// fill the array with some values
FillArray( myArray, 12, 4, 2, 23 );
// output all values using the print command
Print( myArray );
// Print( myArray ) does the same as
// Print( myArray[1], myArray[2], myArray[3], myArray[4] )

In the output window appears

12 4 2 23

Or you can use Join() and have all items printed on a separate line using the string constant NewLine.

Arrays: 
    myArray[];
// fill the array with some values
FillArray( myArray, 12, 4, 2, 23 );
// output all values separated by a newline
PrintJoinNewLine, myArray ) );

Output window shows

12

4

2

23

Reading the Array Properties

Some useful functions are available for reading the array properties. For example, by using the ArrayLength( ) function, you receive the array size, i.e. the number of items in it. 

With other functions you gain information about the highest or lowest value in an array (and their unique index in the array).

  • ArrayLength( ArrayName ) - Returns the size of the array.
  • HighestArray( ArrayName ) - Returns the highest value in the array.
  • IndexOfHighestArray( ArrayName ) - Returns the index of the highest value in the array.
  • LowestArray( ArrayName ) - Returns the lowest value in the array.
  • IndexOfLowestArray( ArrayName ) - Returns the index of the lowest value in the array.

With the following little routine you can test the functions listed above. When you change the content of the FillArray( ) function, different values will be output.

Variables: 
    OutputText;
Arrays: 
    myArray[];
If isLastBar Then
    Begin
        //Fill the array with values
        FillArray( myArray, 2, 4, 6, 8, 10, 2, 3, 5 );
        //Output array contents
        Print"Array Contents: " + Join", ", myArray ) );
        //Read the number of elements
        OutputText = "Number of Elements: " + ArrayLength( myArray);
        //Output in the output window
        Print( OutputText);
        //Retrieve the highest value
        OutputText = "Highest Value: " + HighestArray( myArray);
        //Retrieve unique ID / position of highest value
        OutputText = OutputText + " - at position No.: " + 
IndexOfHighestArray( myArray);
        //Output in the output window
        Print( OutputText);
        //Retrieve the lowest value
        OutputText = "Lowest Value: " + LowestArray( myArray);
        //Retrieve unique ID / position of lowest value
        OutputText = OutputText + " - at position No.: " + 
IndexOfLowestArray( myArray);
        //Output in the output window
        Print( OutputText);
    End;

In the output window, the following appears:

Array contents: 2, 4, 6, 8, 10, 2, 3, 5

Number of elements: 8

Highest value: 10 - at position No.: 5

Lowest value: 2 - at position No.: 1

Overview of all Array Functions

In the following you can find a list of all array functions in Equilla. More information and examples for each function you can find in the Tradesignal help under Equilla Formula Language, menu entry Arrays. 

To open the Tradesignal help, click on the button with the yellow question mark in the toolbox or in the header bar. In the Equilla editor, you can also right-click on an Equilla function and select Lookup Equilla Function. 

 

Function Description
AppendArrayApppends an array or a single variable to another array.
ArrayLengthReturns the length (and maximum index) of an array.
Array_CopyCopies some elements from one array to another.
Array_GetTypeReturns the type of the array elements.
Array_SortSorts a range of elements in an array.
Array_SumReturns the sum of all elements or the number of true values in case of booleans.
AverageArrayReturns the (mean) average of all or some elements of the array.
AvgDeviationArrayReturns the average deviation of all or some elements of the array.
BinarySearchArrayReturns the position of a given value using a binary search.
ClearArrayClears an array and resets it to its initial state.
CompareArrayCompares one array to another.
CopyArrayCopy all or some elements from one array to another.
CreateSortedIndexArrayCreates a sorted index into another array.
FillArrayFills an array with the given values.
GetArrayDimensionsReturns the number of dimensions of an array.
HarmonicMeanArrayReturns the harmonic mean of all or some elements of the array.
HighestArrayReturns the highest value in the array.
IndexOfHighestArrayReturns the index of the highest value in the array.
IndexOfLowestArrayReturns the lowest value in the array.
InsertAtArrayInserts a value into an array at a given index.
InsertSortedArrayInserts a value into an array keeping it sorted.
KurtosisArrayReturns the Kurtosis value of all or some elements of the array.
LowestArrayReturns the lowest value in the array.
MedianArrayReturns the median of all or some elements of the array.
RemoveAtArrayRemoves an element at a given index from the array.
SearchArrayReturns the position of a given value.
SetArrayLengthShrinks or grows a dynamic array.
SetValRangeArraySets a range of elements to a given value.
SkewnessArrayReturns the skewness of all or some elements of the array.
Sort2DArraySorts a 2-dimensional array by columns.
SortArraySorts some or all elements of an array.
StdDeviationArrayReturns the standard deviation of all or some elements of the array.
StdErrorArrayReturns the standard error of all or some elements of the array.
SummationArrayReturns the sum of all or some elements of the array.
SummationRecArrayReturns the sum of reciprocals of all or some elements of the array.
SummationSqrArrayReturns the sum of squares of all or some elements of the array.
VarianceArrayReturns the variance of all or some elements of the array.

 

BACK TO OVERVIEW      Introductions to Functions, Indicators and Strategies