StrArray Class

Navigation: PGMs ➔ Classes ➔ StrArray Class

Global Pre-Defined Class Instances			SysCAD Pre-Defined Classes
Sp Database SDB Class	Particle Size Defn PSD Class	Plant Model PM Class	Array Class	StrArray Class	Matrix Class	TagSelect Class	Time Class	Noise Class

Latest SysCAD Version: 25 October 2024 - SysCAD 9.3 Build 139.36522

Related Links: Defining a Class, Example PGM Files

---

Description

The String Array class allows user to Get / Set String values. Please see Array Class for getting/setting numeric values.

The StrArray (String Array) class provides member functions to create a dynamic string array and manipulate its elements.

• The StrArray is zero indexed, i.e. the index of the first element in the StrArray is zero, and NOT 1. Therefore, the final element in a StrArray of length n will have an index = n-1.
• If the index is out of range (length <= index) then a " PGM class execution error " will occur and the StrArray operation will be ignored.

Note: the initial length of the array is zero.

Data Members

None

Member Functions

Call	Functionality	Return Type	Parameters	Example
SetLen(length)	Sets the size of the StrArray to length		length : the required length of the array, is of data type INTEGER	a.SetLen(5)
GetLen()	The function returns the length of the StrArray.	integer	None	x = TagGroup.GetLen()
SetSize(length) Available from Build 139.30807.	Sets the size of the StrArray to length. SetSize() function is an equivalent alternative to SetLen()		length : the required size of the StrArray, is of data type INTEGER	a.SetSize(5)
Size() Available from Build 139.30807.	The function returns the length of the StrArray. Size() function is an equivalent alternative to GetLen().	integer	None	x = TagGroup.Size()
SetAt(index, String)	This sets the element of the array, which corresponds to the given index to the specified String.		index : data type INTEGER. The index of the required entry in the StrArray (index starts at zero). String : data type STRING. The value to which the specified element in the StrArray will be set.	TagGroup.SetAt(0, "Variable Name")
GetAt(index)	This retrieves the value (type real) of the element from the array, which corresponds to the given index.	String	index : data type INTEGER, the index of the required entry in the array (index starts at zero).	Required_Tag = TagGroup.GetAt(0)
SetAll(String)	This sets all the elements of the StrArray to the specified String.		String : data type STRING.	TagGroup.SetAll("Variable Name")
Reverse() Available from Build 139.30807.	This reverses the sequence of all elements in the StrArray .		None	TagGroup.Reverse()
Sort(CaseSensitive) Available from Build 139.30807.	This re-arranges all elements in the StrArray in ascending order.		0: Case Insensitive sort, c 1: Case Sensitive sort	TagGroup.Sort(1)
Load(strArrayFileName)	This creates a new StrArray from a file. The first element on each line, of the specified file, is read in as an element of the array, until either an empty line or end-of-file character is reached. The function returns the value, True if the file was read or, False if the file was not read. Note: if any elements exist in the StrArray, prior to calling Load, these elements will be overridden.	Bit	strArrayFileName: either the actual filename and path in quotations or a STR variable, which refers to the file. If no path is specified, then it is assume the file is stored in the project folder. Use $Prj in the folder string for folders relative to the project folder.	ArrayFileName = "c:\SysCAD\StrArray.csv" OK = b.Load(strArrayFileName) OR OK = c.Load("$Prj\Controls\InputTags.txt")
Save(strArrayFileName)	This saves the StrArray data to a comma separated text file. If the specified file exists it is overwritten. The function returns, True if the file was saved or, False if the file was not saved. This could fail for any file access reason, for example: invalid folder, invalid filename, file access error, file already open in another application, etc.	Bit	strArrayFileName: either the actual filename and path in quotations or a STR variable, which refers to the file. If no path is specified, then it is the file is to be saved to the project folder. Use $Prj in the folder string for folders relative to the project folder.	OK = a.Save("OutputTags.txt") OR OK = a.Save("$Prj\Controls\OutputTags.txt")
Copy(StrArray) Available from Build 139.30807.	All the elements of the specified array are copied into the new array.		StrArray: the name of the array to copy from. This is a STRARRAY class.	PreVals.Copy(a) - The values in Array "a" are copied into the Array "PreVals".
Append(StrArray) Available from Build 139.30807.	All the elements of the specified array are added to the end of the existing array. The new length of the array will be the sum of the original length plus the length of the specified array.		StrArray: the name of the array to append. This is an STRARRAY class.	PreVals.Append(a) - The values in Array "a" are appended to the end of the Array "PreVals".
AppendItem(String) Available from Build 139.30874.	Increase the length of the array by one with the supplied value.		String: the value to which the last element in the array will be set. Data type STRING.	a.AppendItem("OneMore")
InsertAt(index, String) Available from Build 139.32112.	Increase the length of the array by one inserting the supplied value at the specified index.		index: the zero based index in array where the value must be inserted. Index data type is INTEGER and must be in range for Array length. String: the value to be set at the new inserted element in the array.	a.InsertAt(0, "AtFront") - Inserts "AtFront" at start of StrArray.
RemoveAt(index, count) Available from Build 139.32112.	Decrease the length of the array by removing count (or less) values starting at the specified index.		index: the zero based index in array where values must be deleted. Index data type is INTEGER and must be in range for Array length. count: the number of elements to be removed. The value of count may be large, exceeding the current array length in which case all elements from the specified index are removed. Count data type is INTEGER.	a.RemoveAt(5, 1) - Removes one element at index 5.
SetFromStr(Str s, Str Separ) Available from Build 139.35544.	This function enables the unpacking of a string into a StrArray, converting each element into a string. The StrArray’s length is determined by the number of items derived from unpacking the string.	STRING	s is the string that requires unpacking. Separ is the separator used within the string ‘s’ to define the divisions.	x.SetFromStr("A,B,C", ",") will unpack the three numbers into the StrArray ‘x’, resulting in x[0]=A, x[1]=B, and x[2]=C.
CopyToStr(Str Separ) Available from Build 139.35544.	This function enables the consolidation of a ‘strArray’ into a single string.	STRING	Separ denotes the delimiter used within the string ‘s’ to demarcate its segments.	x.CopyToStr(",") will combine the elements of the 'strArray' named 'x' into the string "A,B,C".

Watch

To make the StrArray variables visible in the access window the Watch command can be used.

• Individual elements in the array can be made visible - e.g. "Watch TagGroup[2]" or "Watch TagGroup@[2]".
• A range of StrArray elements can be made visible - e.g. "Watch TagGroup[All,5]" which would show the first 5 elements of the StrArray.
• If the "@" symbol is included, then the StrArray elements will be read only fields in the access window.

StrArray with Constant Values

The user may declare a string array with a set of constant strings. Implemented in Build139.32112. This allows the user to set up a StrArray with known values for direct use. The contents or size of this constant StrArray cannot be changed. Where a string is not specified for an entry, an empty string is assumed. The contents of the array are not saved as they are defined in the code. From Build 139.32325 the const keyword should be used, otherwise a load warning (or error) is given.

The syntax is:

CONST STRARRAY a = {s1,s2,s3,....} ;Syntax from Build 139.32325
STRARRAY a = {s1,s2,s3,....} ;Syntax before Build 139.32325
;where s1, s2 etc. are literal strings.
;Example
const StrArray Countries = {"Australia", "Canada", "USA", "South Africa", "Sweden"}

Caution

Using a GetAt within a SetAt can sometimes fail.

;For example:
TagGroup.SetAt(i, TagGroup.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:
STRING   TmpString
TmpString = TagGroup.GetAt(i+1)
TagGroup.SetAt(i, TmpString)

Example

PageLabel("StrArray")	
  TextLabel()
  STRING     Tag1@, Tag2@, Tag3@, Required_Tag@
  LONG       x@
  StrARRAY   TagGroup
  Watch TagGroup[All,5]

  Sub InitialiseSolution()
    TagGroup.SetLen(5)             ;sets the StrArray length
  EndSub
 
  Tag1 = "P_4.To (C)"
  Tag2 = "P_5.To (C)"
  Tag3 = "P_6.To (C)"

  x = TagGroup.GetLen()
  TagGroup.SetAt(0, Tag1)
  TagGroup.SetAt(1, Tag2)
  TagGroup.SetAt(2, Tag3)
  TagGroup.SetAt(4, "P_7.To (C)")
  Required_Tag= TagGroup.GetAt(1)

See also Example PGM to create a Unit Tag List