REMOVE, REMOVE(), REVREMOVE

The REMOVE statement and REMOVE() function extract characters from a dynamic array up to the next mark character. The REVREMOVE statement extracts items in reverse order.

Format

REMOVE string FROM dyn.array SETTING var

REMOVE(dyn.array, var)

REVREMOVE string FROM dyn.array SETTING var

where

string

is the variable to receive the extracted substring.

dyn.array

is the dynamic array from which string is to be extracted.

var	is the variable to be set according to the delimiter that terminates the extracted substring.

The statement

S = REMOVE(X, Y)

is equivalent to

REMOVE S FROM X SETTING Y

The REMOVE operation associates a remove pointer with the dyn.array from which data is extracted. Whenever a string is assigned to a variable the remove pointer is set to point one character before the start of the string. Subsequent REMOVE operations advance the pointer by one character and then extract characters from the position of the remove pointer up to the next mark character or the end of the string. Because the remove pointer gives immediate access to the position at which the REMOVE should commence, this operation can be much faster than field, value or subvalue extraction.

The value returned in var indicates the delimiter that terminated the REMOVE. The delimiter character is not stored as part of the extracted substring. Values of var are

0 End of string

1 Item mark

2 Field mark

3 Value mark

4 Subvalue mark

5 Text mark

The mark character itself can be reconstructed as CHAR(256 - var) for a non-zero value of var.

Once the end of the dyn.array has been reached, the remove pointer remains positioned one character beyond the end of the string and further REMOVE operations would return a null string.

The RMVD() function is similar to REMOVE() but recognises only the field, value and subvalue marks as delimiters.

The remove pointer may be reset to the start of the string by assigning a new value to string. Where it is required to reset the remove pointer without changing the string, the SETREM statement can be used. Alternatively, applications frequently use a statement such as

S = S

which will assign S to itself thus resetting the remove pointer.

The REVREMOVE statement is similar to REMOVE but extracts items in reverse order. It will be necessary to use SETREM to position the remove pointer prior to first use of REVREMOVE. The value returned in var will identify the mark character that precedes the extracted text, zero after extracting the item at the start of dyn.array.

Note that the REMOVE operations perform a type conversion on dyn.array if it is not already a string. Thus the program

S = 99

REMOVE X FROM S SETTING DELIM

would convert S to be a string "99". Although this is unlikely to have any undesirable effects, it is a side effect to be aware of.

Examples

LOOP

REMOVE BOOK.NO FROM BOOK.LIST SETTING DELIM

PRINT "Book number is " : BOOK.NO

WHILE DELIM

REPEAT

This program fragment extracts entries from the BOOK.LIST dynamic array and prints them. There is an assumption that BOOK.LIST is not a null string (in which case a single null BOOK.NO would be printed).

S = ""

LOOP

REMOVE FLD FROM REC SETTING DELIM

S := FLD

IF DELIM = 2 OR DELIM = 0 THEN

PRINT S

S = ""

END ELSE

S := CHAR(256 - DELIM)

END

WHILE DELIM

REPEAT

This program prints fields from REC. Note the use of the ELSE clause to append the delimiter that terminated the substring if it was not a field mark or the end of the string.

This is equivalent to

N = DCOUNT(REC, @FM)

FOR I = 1 TO N

PRINT REC<I>

NEXT I

but may be much faster where REC is large and has a very large number of fields.