Multivalue Functions

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.

Note that the implementation of the multivalue operations differs across multivalue products with regard to whether the text mark is treated as a data character or as a delimiter. QM treats the text mark as a delimiter character in these functions, processing each text mark delimited item separately.

For example, if we have two dynamic arrays

A contains

ABCFMDEFFMGHI

and

B contains

123FM456FM789

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()

MATCHES()

Multivalued application of pattern matching (MATCHES operator)

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()

For compatibility with other multivalue products, QM supports four multivalued arithmetic functions that are equivalent to the implied value by value execution of the arithmetic operators. For example,

X = ADDS(A, B)

is equivalent to

X = A + B

ADDS()

Add corresponding elements of two dynamic arrays

DIVS()

Divide corresponding elements of two dynamic arrays

MULS()

Multiply corresponding elements of two dynamic arrays

SUBS()

Subtract corresponding elements of two dynamic arrays

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 contains

11FM0VM17VMPQRFM2

and B contains

12FM0VM14VMACBFM2

C = GTS(A, B)

Returns C as 0FM0VM1VM1FM0

The multivalued logical functions are

ANDS()

Multivalued logical AND

EQS()

Multivalued equality test

GES()

Multivalued greater than or equal to test

GTS()

Multivalued greater than test

LES()

Multivalued less than test

LTS()

Multivalued less than or equal to test

NES()

Multivalued inequality test

NOTS()

Multivalued logical NOT

ORS()

Multivalued 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.array

is a dynamic array of True / False values.

true.array

holds values to be returned where the corresponding element of control.array is True.

false.array

holds 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

Used in combination, and often with REUSE(), these functions can give very elegant solutions to apparently complex problems. For example, to determine how many elements of a dynamic array contain a value greater than four:

N = SUM(GTS(X, REUSE(4))