StrArray Class

From SysCAD Documentation
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

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: 23 April 2024 - SysCAD 9.3 Build 139.35250

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)
Implemented in Build139.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()
Implemented in Build139.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()
Implemented in Build139.30807		 This reverses the sequence of all elements in the StrArray . None TagGroup.Reverse()
Sort(CaseSensitive)
Implemented in Build139.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)

Implemented in Build138

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)

Implemented in Build138

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)
Implemented in Build139.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)
Implemented in Build139.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)
Implemented in Build139.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)
Implemented in Build139.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)
Implemented in Build139.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.

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

Retrieved from "https://help.syscad.net/index.php?title=StrArray_Class&oldid=76359"