COMPARE(), COMPARES()

The COMPARE() function compares two strings using the same rules as the LOCATE statement. The COMPARES() function is similar but operates on a multivalued list of strings.

Format

COMPARE(string1, string2 {, justification})

COMPARES(string1, string2 {, justification})

where

string1, string2

evaluate to the strings to be compared.

justification

evaluates to a string where the first character is "L" for left justified comparison or "R" for right justified comparison. If omitted or invalid, left justification is used. An optional second character of "I" causes the function to compare strings in a case insensitive manner.

The COMPARE() function compares the two strings and returns

1	string1 is greater than string2

0	string1 is equal to string2

-1	string1 is less than string2

For a left justified comparison, characters are compared one by one and the function return value is determined by the relative ASCII character set positions of the characters at which the first mismatch occurs. If the strings are of different lengths and match up to the end of the shorter, the longer string is treated as the greater.

For a right justified comparison, the COMPARE() function behaves as though sufficient spaces were inserted at the start of the shorter string to match the length of the longer string. Characters are then compared one by one and the function return value is determined by the relative ASCII character set positions of the characters at which the first mismatch occurs.

The COMPARE() statement always compares the two items as character strings unlike a simple relational operator that will perform a numeric comparison if both items can be treated as numbers:

X = COMPARE("0", "00")

will indicate that the two items are not equal whereas

X = ("0" = "00")

will indicate that the two items are equal.

The COMPARE() function is not affected by the setting of the $MODE NOCASE.STRINGS compiler directive and can therefore be used to force a case sensitive comparison in otherwise case insensitive programs. The optional I code in the justification argument causes case insensitive comparison.

The COMPARES() function treats string1 as a dynamic array, comparing each element in turn with string2 and returning a similarly structured dynamic array of results.

Use of the == operator

IF A == B THEN

is equivalent to

IF COMPARE(A, B) = 0 THEN

Examples

DIM ITEM(100)

ITEMS = 0

LOOP

INPUT NEW.ITEM

WHILE LEN(NEW.ITEM)

* Find position to insert new item

I = 1

LOOP

WHILE I <= ITEMS

IF COMPARE(NEW.ITEM, ITEM(I)) < 0 THEN EXIT

I += 1

REPEAT

* Insert item at position I

FOR J = ITEMS TO I STEP - 1

ITEM(J + 1) = ITEM(J)

NEXT J

ITEM(I) = NEW.ITEM

ITEMS += 1

REPEAT

This program fragment creates a matrix, ITEMS, and then enters a loop to read NEW.ITEM values from the keyboard until a blank line is entered. Each item read is inserted into the matrix in its correct position to maintain the matrix in ascending collating sequence order. Additional statements to detect and handle matrix overflow would be useful in a full application.

A = 'AAA':@VM:'BBB':@FM:'CCC'

X = COMPARES(A, 'BBB')

The above program fragment returns X as "-1VM0FM1". Note how the mark characters used to delimit A have been replicated in X.