Multivalue Functions

Top  Previous  Next

 

The QMBasic language has many functions that provide multivalued equivalents of their more commonly used single valued counterparts. In each case, these work element by element through the dynamic arrays passed into the functions, performing the operation on each element in turn to produce an equivalent dynamic array of results.

 

For example, if we have two dynamic arrays

 

A containsABCFMDEFFMGHI

and

B contains123FM456FM789

 

We can concatenate these two dynamic arrays in two ways:

 

C = A : B        sets C to ABCFMDEFFMGHI123FM456FM789

C = CATS(A, B)        sets C to ABC123FMDEF456FMGHI789

 

 

The main multivalued string functions are

CATS()Concatenate elements of a dynamic array
COUNTS()Multivalued variant of COUNT()
FIELDS()Multivalued variant of FIELD()
FMTS()Format elements of a dynamic array
ICONVS()Perform input conversion on a dynamic array
INDEXS()Multivalued equivalent of INDEX()
NUMS()Multivalued variant of NUM()
OCONVS()Perform output conversion on a dynamic array
SPACES()Multivalued variant of SPACE()
STRS()Multivalued variant of STR()
SUBSTRINGS()Multivalued substring extraction
TRIMBS()Multivalued variant of TRIMB()
TRIMFS()Multivalued variant of TRIMF()
TRIMS()Multivalued variant of TRIM()

 

There are also a number of multivalued logical functions.  These provide equivalents to the relational operators and other functions that return boolean values.

 

For example, the GTS(arr1, arr2) function takes two dynamic arrays and returns a new dynamic array of true / false values indicating whether the corresponding elements of arr1 are greater than those of arr2.

 

Thus, if A contains11FM0VM17VMPQRFM2
and B contains12FM0VM14VMACBFM2

 

C = GTS(A, B)

 

Returns C as  0FM0VM1VM1FM0

 

 

The multi-valued logical functions are

 

ANDS()Multi-valued logical AND
EQS()Multi-valued equality test
GES()Multi-valued greater than or equal to test
GTS()Multi-valued greater than test
LES()Multi-valued less than test
LTS()Multi-valued less than or equal to test
NES()Multi-valued inequality test
NOTS()Multi-valued logical NOT
ORS()Multi-valued logical OR

 

 

The IFS() function returns a dynamic array constructed from elements chosen from two other dynamic arrays depending on the content of a third dynamic array.

 

IFS(control.array, true.array, false.array)

 

where

 

control.arrayis a dynamic array of true / false values.

 

true.arrayholds values to be returned where the corresponding element of control.array is true.

 

false.arrayholds values to be returned where the corresponding element of control.array is false.

 

 

The IFS() function examines successive elements of control.array and constructs a result array where elements are selected from the corresponding elements of either true.array or false.array depending on the control.array value.

 

Example

 

A contains  1VM0VM0VM1VM1VM1VM0

B contains  6VM2VM3VM4VM9VM6VM3

C contains  2VM8VM5VM0VM3VM1VM3

 

D = IFS(A, B, C)

 

D now contains  6VM8VM5VM4VM9VM6VM3