REMOVE
Synopsis
REMOVE value FROM dynarray [AT pos] SETTING delim
Arguments
| value | A variable used to receive the extracted element value. |
| dynarray | A dynamic array from which successive data values are to be extracted. |
| AT pos | Optional — A variable specifying the initial starting position in dynarray as an integer character count. pos must be specified as a local variable, not as a numeric literal. The AT clause is provided for compatibility with D3 and UniData systems. |
| delim | A local variable that resolves to an integer code for the dynamic array delimiter type. delim must be specified as a local variable, not as a numeric literal. delim can accept a single dynamic array reference (A<i>), a single substring reference (A[s,l]), or a substring reference nested inside a dynamic array reference (A<i>[s,l]). |
Description
The REMOVE statement efficiently extracts successive data values from a dynamic array. The extracted element value is placed in the value variable. REMOVE operates on a single dynamic array level; you specify the level delimiter using the delim argument. REMOVE maintains an internal pointer so that repeated calls return successive element values. When the last element value has been extracted, REMOVE sets value to the empty string.
You can use the GETREM function to return the character position in dynarray of the REMOVE pointer.
The REMOVE statement is identical to the REVREMOVE statement, except that REVREMOVE operates in the reverse direction. The REMOVE function, REMOVE statement, and REVREMOVE statement all share the same pointer. It is incremented by a Remove and decremented by a Revremove.
The delim variable resolves to an integer code with one of the following values:
| 0 | End of file |
| 1 | @IM Item Mark CHAR(255) |
| 2 | @FM Field Mark CHAR(254) |
| 3 | @VM Value Mark CHAR(253) |
| 4 | @SM Subvalue Mark CHAR(252) |
| 5 | @TM Text Mark CHAR(251) |
Examples
The following example successively extracts the first 5 Value Mark elements from a dynamic array:
names="Fred":@VM:"Barney":@VM:"Wilma":@VM:"Betty"
delim=3
FOR x=1 TO 5
REMOVE val FROM names SETTING delim
PRINT val
! Returns:
! Fred
! Barney
! Wilma
! Betty
! ""
NEXT
