REPLACE function

Syntax

REPLACE (expression, field#, value#, subvalue# { , | ; } replacement)
REPLACE (expression [ ,field# [ ,value#] ] ; replacement)
variable < field# [ ,value# [ ,subvalue#] ] >

Description

Use the REPLACE function to return a copy of a dynamic array with the specified field, value, or subvalue replaced with new data.

expression specifies a dynamic array.

The expressions field#, value#, and subvalue# specify the type and position of the element to be replaced. These expressions are called delimiter expressions.

replacement specifies the value that the element is given.

The value# and subvalue# are optional. However, if either subvalue# or both value# and subvalue# are omitted, a semicolon ( ; ) must precede replacement, as shown in the second syntax.

You can use angle brackets to replace data in dynamic arrays. Angle brackets to the left of an assignment operator change the specified data in the dynamic array according to the assignment operator. Angle brackets to the right of an assignment operator indicate that an EXTRACT function is to be performed (for examples, see the EXTRACT function).

variable specifies the dynamic array containing the data to be changed.

The three possible results of delimiter expressions are described as case 1, case 2, and case 3.

Case 1:
Both value# and subvalue# are omitted or are specified as 0. A field is replaced by the value of replacement.
  • If field# is positive and less than or equal to the number of fields in the dynamic array, the field specified by field# is replaced by the value of replacement.
  • If field# is negative, a new field is created by appending a field mark and the value of replacement to the last field in the dynamic array.
  • If field# is positive and greater than the number of fields in the dynamic array, a new field is created by appending the proper number of field marks, followed by the value of replacement; thus, the value of field# is the number of the new field.
Case 2:
subvalue# is omitted or is specified as 0, and value# is nonzero. A value in the specified field is replaced with the value of replacement.
  • If value# is positive and less than or equal to the number of values in the field, the value specified by the value# is replaced by the value of replacement.
  • If value# is negative, a new value is created by appending a value mark and the value of replacement to the last value in the field.
  • If value# is positive and greater than the number of values in the field, a value is created by appending the proper number of value marks, followed by the value of replacement, to the last value in the field; thus, the value of value# is the number of the new value in the specified field.
Case 3:
field#, value#, and subvalue# are all specified and are nonzero. A subvalue in the specified value of the specified field is replaced with the value of replacement.
  • If subvalue# is positive and less than or equal to the number of subordinate values in the value, the subordinate value specified by the subvalue# is replaced by the value of replacement.
  • If subvalue# is negative, a new subordinate value is created by appending a subvalue mark and the subordinate value of replacement to the last subordinate value in the value.
  • If the subvalue# is positive and greater than the number of subordinate values in the value, a new subordinate value is created by appending the proper number of subvalue marks followed by the value of replacement to the last subordinate value in the value; thus, the value of the expression subvalue# is the number of the new subordinate value in the specified value.

In IDEAL, PICK, PIOPEN, and REALITY flavor accounts, if replacement is an empty string and an attempt is made to append the new element to the end of the dynamic array, field, or value, the dynamic array, field, or value is left unchanged; additional delimiters are not appended. Use the EXTRA.DELIM option of the $OPTIONS statement to make the REPLACE function append a delimiter to the dynamic array, field, or value.

If replacement is the null value, the stored representation of null (CHAR(128)) is inserted into dynamic.array. If dynamic.array evaluates to the null value, it remains unchanged by the replacement. If the REPLACE statement references a subordinate element of an element whose value is the null value, the dynamic array is unchanged.

INFORMATION and IN2 Flavors

In INFORMATION and IN2 flavor accounts, if expression is an empty string and the new element is appended to the end of the dynamic array, the end of a field, or the end of a value, a delimiter is appended to the dynamic array, field, or value. Use the -EXTRA.DELIM option of the $OPTIONS statement to make the REPLACE function work as it does in IDEAL, PICK, and REALITY flavor accounts.

Examples

In the following examples a field mark is shown by F, a value mark is shown by V, and a subvalue mark is shown by S.

The first example replaces field 1 with # and sets Q to #FAVBVDSEFDFFF:

R=@FM:"A":@VM:"B":@VM:"D":@SM:"E":@FM:"D":@FM:@FM:"F"
Q=R
Q=REPLACE(Q,1;"#")

The next example replaces the first subvalue of the third value in field 2 with # and sets Q to FAVBV#SEFDFFF:

Q=R
Q<2,3,1>="#"

The next example replaces field 4 with # and sets Q to FAVBVDSEFDF#FF:

Q=R
Q=REPLACE(Q,4,0,0;"#")

The next example replaces the first value in fields 1 through 4 with # and sets Q to #F#VBVDSEF#F#FF:

Q=R
FOR X=1 TO 4
Q=REPLACE(Q,X,1,0;"#")
NEXT

The next example appends a value mark and # to the last value in field 2 and sets Q to FAVBVDSEV#FDFFF:

Q=R
Q=REPLACE(Q,2,-1;"#")
Parent topic: BASIC Statements and Functions