Array Utility Routines
The following routines provide commands for manipulating, searching and sorting arrays. These commands are analogous to the array commands in 4D.
OT DeleteElement version 2
OT DeleteElement(inObject; inTag; inWhere {; inHowMany})
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the array item to change
→
inWhere Number Element to delete
→
inHowMany Number How many elements to delete
→
Discussion
OT DeleteElement deletes one or more elements from an array in inObject.
If inObject is not a valid object handle, if no item in the object has the given tag, or if the item’s type is not an array type, an error is generated and OK is set to zero.
Elements are deleted starting at the element specified by inWhere. The inHowMany parameter is the number of elements to delete. If inHowMany is not specified or zero, then one element is deleted. The size of the array shrinks by inHowMany elements.
See Also
OT FindInArray version 2
OT FindInArray(inObject; inTag; inValue {; inStart}) Longint
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the array item to change
→
inValue Text Value to search for
→
inStart Number Element at which to start search
→
Function result Number The index of the first element found
←
Discussion
OT FindInArray searches an array in inObject for the value inValue.
If inObject is not a valid object handle, if no item in the object has the given tag, or if the item’s type is not an array type, an error is generated, OK is set to zero, and -1 is returned.
If inStart is not specified or is zero, it defaults to 1. The text inValue is converted to the type appropriate for the array being searched. For example, for a Longint array or Real array, inValue is converted as if it where passed to the 4D Num command. The formats used to convert values are as follows:
Array type Example inValue
| Boolean array | "true" or "1" = true, "false" or "0" = false |
| Date array | String(!08/27/31!) |
| Longint array | String(7) |
| Real array | String(13.27) |
The result of the command is the index of the first matching element, or -1 if no match is found.
Note Wildcards may be used when searching string/text arrays just as in 4D.
OT InsertElement version 2
OT InsertElement(inObject; inTag; inWhere {; inHowMany})
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the array item to change
→
inWhere Number Where to insert
→
inHowMany Number How many elements to insert
→
Discussion
OT InsertElement inserts one or more elements into an array in inObject.
If inObject is not a valid object handle, if no item in the object has the given tag, or if the item’s type is not an array type, an error is generated and OK is set to zero.
The new elements are inserted before the element specified by inWhere, and are initialized to an empty value for the array type. All elements beyond inWhere are moved up to make room for the new elements.
If inWhere is greater than the size of the array, the elements are added to the end of the array.
See Also
OT ResizeArray version 2
OT ResizeArray(inObject; inTag; inSize)
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the array item to change
→
inSize Number New array size
→
Discussion
OT ResizeArray resizes an array in inObject.
If inObject is not a valid object handle, if no item in the object has the given tag, or if the item’s type is not an array type, an error is generated and OK is set to zero.
If inSize is greater than the current size of the array, empty elements are added to the end of the array. If inSize is less than the current size of the array, elements from inSize + 1 to the end of the array are deleted.
See Also
OT DeleteElement , OT InsertElement, OT SizeOfArray
OT SizeOfArray version 1
OT SizeOfArray(inObject; inTag) Number
→
Parameter Type Description
inObject Longint A handle to an object
→
inTag String Tag of the item to query
→
Function result Number The size of the item’s array
←
Discussion
OT SizeOfArray returns the number of elements in an array item within an object.
If inObject is not a valid object handle, if no item in the object has the given tag, or if the item’s type is not an array type, an error is generated, OK is set to zero, and zero is returned.
See Also
OT SortArrays version 1
OT SortArrays(inObject; inTag1; inDirection1 {; ...inTag7; inDirection7})
Parameter Type Description
inObject Longint A handle to an object
→
inTag1 String Tag of the array to sort
→
inDirection1 String Direction of sort
→
Discussion
OT SortArrays performs a multilevel sort on one or more arrays in inObject. You may sort up to seven arrays at once with this command.
If inObject is not a valid object handle, if no item in the object has the given tag, if the item’s type is not a sortable array type, if all of the arrays do not have the same number of elements, or if a direction is not valid, an error is generated and OK is set to zero.
The direction should be one of three values to indicate how to sort the array:
Value Sort direction
| ">" | Ascending |
| "<" | Descending |
| "*" | Move with previous array |
For example, to sort parallel arrays of names and associated ids, you would use something like this:
OT SortArrays($object;"names";">";"ids";"*")
To sort a group of addresses by state and then city within each state, you would use something like this:
OT SortArrays($object;"states";">";"cities";">")