Standard XBase Functions

[This HELP section is not complete yet: read the respective section in STARLING for DOS Help].

In the expressions that are passed to STARLING you can use the following function names (parameters are included within round brackets).

You can use all of them in your expressions. If you make some mistake (forget about parentheses, brackets or misspell some string or variable), the system will display an error message - it is up to you to correct your expression.

SEE ALSO

?, Syntax of XBase expressions, StarLing functions.

AAdd(aArray, expr, [nElement]) --> xValue

Adds one element to an array. The new element is the last element in the array or the element at the position nElement. The new element has the value associated with expr. The length of the array is not limited. AAdd() is used to manage dynamic lists. The function ASize() has a similar purpose, allowing the size of any array to be set. The advantage of AAdd() is that the value expr is also assigned to the new element.

When the value of expression is an array, the new element in aArray contains a reference to the array specified in expr. aArray then becomes a multidimensional array.

SEE ALSO

Array functions, ADel, AEval, AIns, ASize

Abs(nExpr) --> nPositive

Returns a number >= 0 which represents the absolute value of nExpr.

SEE ALSO

Numeric functions, Exp, Log, Max, Min, Mod

AClone(aArray) --> aClonedArray

Used to create copies of multidimensional arrays. Since the function ACopy() only copies the elements in the first dimension of an array and does not consider subarrays, it cannot be used to copy a multidimensional array. AClone(), on the other hand, also creates copies of subarrays if array references are contained in the elements of aArray.

SEE ALSO

Array functions, ACopy, ADel, AIns, ASize

ACopy(aSource, aTarget, [nStartSource], [nCount], [nStartTarget]) --> aTarget

Copies elements of an array into another array.

PARAMETERS

aSource

The array whose elements are copied

aTarget

The array into which elements of aSource are copied

nStartSource

A numeric value specifying the starting position in the array aSource to copy. The default value is 1.

nCount

A numeric value specifying the number of elements to copy, starting from position nStartSource. If nCount is missing, the elements are copied from nStartSource to the last element of aSource.

nStartTarget

A numeric value specifying the starting position in the array aTarget to which copies are transferred. The default value is 1.

NOTE

Only values in the first dimension of aSource are copied. If aSource has subarrays (is a multidimensional array), only the array references and not the content of the subarrays are copied into aTarget. In this case, both arrays have the reference to the same subarrays. To completely copy a multidimensional array, the function AClone() must be used.

The array aTarget must be large enough to hold the copied values. If aSource is greater than aTarget, all the elements are not copied.
The array aTarget can be identical to aSource. When this is the case, elements in aSource may be moved in blocks.

SEE ALSO

Array functions, AClone, ADel, AEval, AFill, AIns, ASort

ADel(aArray, nElement) --> aSource

Deletes the contents of nElementth element from array aArray. The content (or value) of the element is lost and all subsequent elements shift up one position. The value of the last element becomes NIL. The number of array elements Len(aArray) remains unchanged by ADel(). To remove the last element after ADel(), the function ASize() must be used.

SEE ALSO

Array functions, AAdd, ACopy, AFill, AIns, ASize

AEval(aArray, bBlock, [nStart], [nCount], [lAssign]) --> aArray

Allows operations to be performed on the contents of array elements. The operations are programmed in a code block which is executed nCount times beginning with array element nStart. The contents of the current array element are passed to the code block as the first argument and the element index is passed as the second argument. After each execution, the index is incremented and the code block is evaluated with the next array element. If lAssign equals .T., the array element is passed to the code block by reference. If an assignment to the first code block parameter is made, it is reflected in the corresponding array element.

NOTE

The contents of the array elements are not relevant to AEval(), since the function merely passes the contents of each element on to the code block. However, the code block must assure that only correct data types are processed.

SEE ALSO

Array functions, Code block functions, DbEval, Eval

AFill(aArray, [expr], [nStart], [nCount]) --> aArray

Fills nCount (all by default) elements of array aArray with a single value expr (NIL by default), starting with array element nStart (1 by default). The value can be of any data type. If the value is an object or an array, all the elements of the filled array contain the same reference to the object or subarray. The function assigns the value only to the elements of the first dimension. Multidimensional arrays cannot be filled with AFill().

SEE ALSO

Array functions, AAdd, AEval, DbStruct, Directory, stDbStruct, stRecordStruct

AIns(aArray, nElement, [expr]) --> aArray

Inserts the value expr at the position nElement within the array. All array elements, starting with this position, are shifted down one element and the content of the last element is lost. The number of array elements Len(aArray) remains unchanged by AIns(). To avoid losing the value in the last element the function AAdd() can be used. AAdd() adds an element to the end of the array prior to the insertion.

SEE ALSO

Array functions, AAdd, ACopy, ADel, AEval, AFill, ASize

AllTrim(s) --> sTrimmed

Removes all blank spaces (Chr(32)) at the beginning and end of a character string. The similar functions LTrim() and RTrim()|Trim() remove blank spaces only at the beginning or end of a character string. The counterpart to AllTrim() is the function PadC(), which adds blank spaces to the beginning and end of a character string.

SEE ALSO

Character functions, PadC|PadL|PadR

Array(nDimension1 [, nDimensionN...]) --> aArray

Creates an array which contains the value NIL in all elements (except for Array(0) which creates an empty array which has no elements). If the argument nDimensionX is included, an array with nDimensionX elements is assigned to each array element of the dimension nDimension1. These arrays also have the value NIL in all elements. Neither the number of dimensions nor the number of elements per array is limited.

SEE ALSO

Array functions, AAdd, AClone, ACopy, ADel, AEval, AFill, AIns

Asc(s) --> n

Returns the ASCII code for the first character of string s. The counterpart of Asc() is the function Chr(), which converts an ASCII code to an ASCII character.

SEE ALSO

Conversion functions, Chr, Str, Val

AScan(aArray, bxSeekExpr, [nStart], [nCount]) --> nElement

Search an array for a value. If bxSeekExpr is not a code block, the value of bxSeekExpr is compared with the value of each array element. The search begins with the element nStart (1 by default) and compares nCount (all by default) array elements. As soon as a match is found, AScan() terminates the search, returning the position of this array element as a numeric value. AScan() uses the simple equals operator (=) for the comparison. Because of this, the search of character strings is dependent on the settings SET EXACT, SET LEXICAL and SET COLLATION.

When bxSeekExpr is a code block, the search occurs as just described, except that AScan() evaluates the code block passing it the contents of each array element. The code block must perform a comparison and return a logical value. As soon as the code block returns .T., AScan() terminates and returns the position of this element. The code block is necessary when a complex search condition must be used or when the search is performed on a multidimensional array.
Returns 0 if the search is unsuccessful.

SEE ALSO

Array functions, AEval, Eval

ASize(aArray, nElements) --> aArray

Increases or decreases the number of elements in an array. When the array is lengthened, the new elements are at the end of the array and have the value NIL. If the array is shortened, the elements at the end of the array are deleted and their contents are lost.

NOTE

Another function which changes the size of an array is AAdd() which attaches a single array element at the end and optionally assigns it a value. The contents of array elements can also be manipulated with the functions AIns() and ADel(), which do not change the size of the array.

SEE ALSO

Array functions, AAdd, ADel, AFill, AIns

ASort(aArray, [nStart], [nCount], [bOrder]) --> aArray

Sorts the elements of an array. One dimensional arrays are sorted in ascending order by default. This means that smaller values are placed at the beginning of the array, with larger values at the end. Sorting in descending order or sorting multidimensional arrays requires that a code block bOrder be specified. The code block must contain a logical expression comparing two values. Two values x1 and x2 are passed to the code block from ASort(). To create ascending order, the code block must return the result of evaluating whether x1 < x2. To create descending order, the code block must return the result of evaluating whether x1 > x2.

NOTE

Character strings are sorted according to their lexical order. Sorting depends on the settings SET EXACT, SET LEXICAL and SET COLLATION. Logical values are sorted with .F. being less than .T.. Date values are sorted chronologically and numeric values according to their size.

SEE ALSO

Array functions, AEval, AScan, DbSort, Eval