Array Class
Navigation: PGMs > Classes > Predefined Classes
Species Database Class  Particle Size Definition Class  Array Class  StrArray Class  Matrix Class  Tag Select Class  Plant Model Class  Noise Class  TimeClass 

Contents
Description
The ARRAY class provides member functions to create a dynamic array and manipulate its elements.
 The user may read in an array from a file. The file may be either a CSV file, created using Excel, or a TXT file, created using a test editor such as Notepad++.
 The user may set constant values into an array when it is declared.
Notes:
 The initial length of the array is zero.
 The array is zero indexed, i.e. the index of the first element in the array is zero, and NOT 1. Therefore, the final element in an array of length n will have an index = n1.
 If the index is out of range (0 <= index < length) then a runtime "PGM class execution error" will occur and the ARRAY operation will be ignored.
 The Array class allows user to Get / Set numeric values only. Please see StrArray Class for getting/setting String values.
Data Members
None
Member Functions
The examples in the table below is based on the following variables and array declarations.
STRING FileName REAL e, DotProduct LONG d BIT [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected] ARRAY a, b, c, NewA, A1, A2, PreVals, z ;declares array instances
Call  Functionality  Return Type  Parameters  Example 
SetLen (length) 
The length of the array is set to the size of length 
length : the required length of the array, is of data type INTEGER 
a.SetLen(5)  
GetLen() 
The function returns the length of the array. 
Long 
None 
d = a.GetLen() 
SetAt (index,value) 
This sets the element of the array, which corresponds to the given index to the specified value. 
index : the index of the required entry in the array (Note: index starts at zero). This is of data type, INTEGER. value : the value to which the specified element, in the array, will be set. This is of data type, REAL. 
a.SetAt(0, 3)  
GetAt (index) 
This retrieves the value (type real) of the element from the array, which corresponds to the given index. 
Real 
index : the index of the required entry in the array (Note: index starts at zero). This is of data type INTEGER. 
e = a.GetAt(0) 
IncAt(Index, value) 
This increases the element of the array by the specified value. 
index : the index of the required entry in the array (Note: index starts at zero). This is of data type INTEGER. value : the value to which the specified element, in the array, will be increased. This is of data type REAL. 
"a.IncAt(3, 10)" is equivalent to:  
DecAt(Index, value) 
This decreases the element of the array by the specified value. 
index : the index of the required entry in the array (Note: index starts at zero). This is of data type INTEGER. value : the value to which the specified element, in the array, will be decreased. This is of data type REAL. 
"a.DecAt(3, 5)" is equivalent to:  
Sum() 
This calculates the sum of all elements in the array. 
Real 
None 
a.Sum() 
Avg() 
This calculates the average of all elements in the array. 
Real 
None 
a.Avg() 
Min() 
This returns the minimum value of all elements in the array. 
Real 
None 
a.Min() 
MinIndex() 
This returns the index of the minimum value in the array. Return value is 1 for empty array. 
integer 
None 
a.MinIndex() 
Max() 
This returns the maximum value of all elements in the array. 
Real 
None 
a.Max() 
MaxIndex() 
This returns the index of the maximum value in the array. Return value is 1 for empty array. 
integer 
None 
a.MaxIndex() 
Sort (Ascending/Descending) Implemented in Build137 
This rearranges all elements in the array in ascending / descending order. 
0: Descending order, 
a.Sort(1)  
IsSorted(Ascending/Descending) Implemented in Build137 
This checks if the array is sorted in ascending / descending order. Returns True if array is sorted in the specified order. 
Bit 
0: Descending order, 
SortOK = a.IsSorted(1) 
Load(arrayfilename) 
This creates a new array from a file.
Note: if any elements exist in the array, prior to calling Load, these elements will be overridden. 
Bit 
arrayfileName : either the actual filename and path in quotations or a STR variable, which refers to the file. Use $Prj in the folder string for folders relative to the project folder. 
ArrayFileName = "c:\SysCAD\array.csv" 
Save(arrayfilename) 
This saves the array data to a comma separated text file.

Bit 
arrayfileName : either the actual filename and path in quotations or a STR variable, which refers to the file. Use $Prj in the folder string for folders relative to the project folder. 
OK = a.Save("$Prj\data_output.txt") 
CopyToClipboard () 
This saves the array data to the clipboard. The function returns the value, True. 
Bit 
None 
OK = a.CopyToClipboard() 
SetAll (value) 
This sets all the elements of the array to the specified value. 
value : the required initialising value. This is of data type REAL. 
a.SetAll(0)  
Scale (value) Implemented in Build137 
All the elements of the array are scaled by the specified value 
value : the required scaling factor. This is of data type REAL. 
a.Scale(2)  
Offset(value) Implemented in Build137 
All the elements of the array are offset by the specified value 
value : the required offset value. This is of data type REAL. 
a.Offset(5)  
Copy(Array) Implemented in Build137 
All the elements of the specified array are copied into the new array. 
Array: the name of the array to copy from. This is an ARRAY class. 
PreVals.Copy(a)  
IsEqual(Array) Implemented in Build137 
This compares the current array with the specified array data, if each element of the array are equal, the function returns the value, True. 
Bit 
Array: the name of the array to compare with. This is an ARRAY class. 
EqualOK = PreVals.IsEqual(a) 
Add(Array) Implemented in Build137 
This function performs addition between current array and a specified array. New value for each element in current array = value in current array + specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. 
Bit  Array: the name of the specified array. This is an ARRAY class.  AddOK = NewA.add(A1) (each element in NewA = NewA + A1) 
Sub(Array) Implemented in Build137 
This function performs subtraction between current array and a specified array. New value for each element in current array = value in current array  specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. 
Bit  Array: the name of the specified array. This is an ARRAY class.  SubOK = NewA.Sub(A1) (each element in NewA = NewA  A1) 
Mult(Array) Implemented in Build137 
This function performs multiplication between current array and a specified array. New value for each element in current array = value in current array x specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. 
Bit  Array: the name of the specified array. This is an ARRAY class.  MultOK = NewA.Mult(A1) (each element in NewA = NewA * A1) 
Div(Array) Implemented in Build137 
This function performs division between current array and a specified array. New value for each element in current array = value in current array / specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. 
Bit  Array: the name of the specified array. This is an ARRAY class.  DivOK = NewA.Div(A1) (each element in NewA = NewA / A1) 
CopyAdd(Array1, Array2) Implemented in Build137 
This function performs addition between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 + array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. 
Bit  Array1: the name of the first specified array. This is an ARRAY class. Array2: the name of the second specified array. This is an ARRAY class. 
AddOK = NewA.CopyAdd(A1, A2) (each element in NewA = A1 + A2) 
CopySub(Array1, Array2) Implemented in Build137 
This function performs subtraction between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1  array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. 
Bit  Array1: the name of the first specified array. This is an ARRAY class. Array2: the name of the second specified array. This is an ARRAY class. 
AddOK = NewA.CopySub(A1, A2) (each element in NewA = A1  A2) 
CopyMult(Array1, Array2) Implemented in Build137 
This function performs multiplication between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 x array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. 
Bit  Array1: the name of the first specified array. This is an ARRAY class. Array2: the name of the second specified array. This is an ARRAY class. 
AddOK = NewA.CopyMult(A1, A2) (each element in NewA = A1 * A2) 
CopyDiv(Array1, Array2) Implemented in Build137 
This function performs division between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 / array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. 
Bit  Array1: the name of the first specified array. This is an ARRAY class. Array2: the name of the second specified array. This is an ARRAY class. 
AddOK = NewA.CopyDiv(A1, A2) (each element in NewA = A1 / A2) 
Inner(Array) Implemented in Build137 
This returns the Sum of Element i (Current Array * Specified Array). The two arrays must have the same length, otherwise error is returned. 
REAL 
Array: the name of the second array. This is an ARRAY class. 
DotProduct = a.Inner(PrevVal) 
Watch
To make the array variables visible in the access window the Watch command can be used.
 Individual elements in the array can be made visible  e.g. "Watch A[2]" or "Watch [email protected][2]".
 A range of array elements can be made visible  e.g. "Watch A[All,5]" which would show the first 5 elements of the array.
 If the "@" symbol is included, then the array elements will be read only fields in the access window.
Array with Constant Values
The user may declare an array with a set of constant values. This allows the user to set up an array with known values, without having to read them into the array via a CSV file.
The syntax is:
ARRAY a = {n1,n2,n3,....} where n1, n2 etc are real numbers.
Caution
Using a GetAt within a SetAt can sometimes fail.
;For example: a.SetAt(i, a.GetAt(i+1)) ;This can sometimes fail ;The solution is to use a temporary variable to first retrieve the GetAt value and then call SetAt as follows: Real Tmp Tmp = a.GetAt(i+1) a.SetAt(i, Tmp)
Example
STRING ArrayFileName REAL d, e, f, [email protected], [email protected], [email protected], [email protected], [email protected] BIT [email protected], [email protected], [email protected], [email protected], [email protected] ARRAY a ;declares array instance. ARRAY b{e}, c{e} ;declares array instances that are excluded from save (for efficiency). ARRAY x = {60,35,25,62,105} ;declares an array z with constant values. ARRAY y, y1, y2 ARRAY y3 = {20,35,45,62,105,150} ;declares an array y3 with constant values. ARRAY z = {20,35,45,62,105} ;declares an array z with constant values. Sub InitialiseSolution() ArrayFileName = "c:\SysCAD\array.csv" OK = b.Load(ArrayFileName) OK = c.Load("$Prj\data.txt") a.SetLen(5) ;sets the array length y.copy(x) ;array x is copied into array y, returns {60,35,25,62,105} CopyOK = y.isEqual(x) ;compares array y with array x, returns true y.sort(1) ;sorts array y in ascending order, returns {25,35,60,62,105} SortOK = y.IsSorted(1) ;checks if array y is sorted in ascending order, returns true y1.copy(y) ;copies y, returns {25,35,60,62,105} y1.scale(2) ;multiplies each element by scaling factor of 2, returns {50, 70, 120, 124, 210} y2.copy(y) ;copies y, returns {25,35,60,62,105} y2.offset(5) ;adds each element by offset factor of 5, returns {30, 40, 65, 67, 110} AddOK = y.add(y2) ;Adds each element of y to elements of y2, y now becomes {55, 75, 125, 129, 215}, returns true SubOK = y1.sub(y3) ;returns false since array length of y1 does not equal to y3. Array y1 unchanged. DotProduct = y.inner(y2) ;sum of each element y_i * y2_i, returns 45068 EndSub ;Logic d = a.GetLen() ;gets the array length a.SetAll(2.2/2) ;sets all elements a.IncAt(0, 7.0) ;increments the first element a[d1] = 3.3 ;sets last element e = a[0] ;gets first element f = z[3] ;gets the fourth element of array z, so f = 62 Total = z.Sum() ;gets the sum of all the values in array z, Total = 267 Average = z.Avg() ;gets the average of all the values in array z, Average = 53.4 Minimum = z.Min() ;gets the minimum of all the values in array z, Minimum = 20 Maximum = z.Max() ;gets the maximum of all the values in array z, Maximum = 105 $
See also Example PGM  Species Check. Also this Optimisation Example shows using these Array tools in a real example for plant tuning calculating an objective funtion.