REMOVE

REMOVE, REMOVE()

Top  Previous  Next

 

The REMOVE statement and REMOVE() function extract characters from a dynamic array up to the next mark character.

 

 

Format

 

REMOVE string FROM dyn.array SETTING var

REMOVE(dyn.array, var)

 

where

 

stringis the variable to receive the extracted substring.

 

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

 

varis 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.

 

 

Note that the REMOVE operation performs 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.

 

 

See also:

GETREM(), REMOVEF(), RMVD(), SETREM