REPLACE( ) Overwrite or replace substring

Domain: String processing

The REPLACE( ) function overwrites or replaces a substring within a string with another string. This can make the original string longer.

Format

REPLACE( )

STRING = string_expression₁

,START = 1 / integer

,REPLACE = string_expression₂

,SUPPRESSED-LENGTH = *REPLACE-LENGTH / integer

Result type

STRING

Input parameters

STRING = string_expression₁
Designates the string in which a substring is to be replaced.

START = 1 / integer
Designates the position from which the (input) string is to be overwritten; “integer” is a positive integer value or an arithmetic expression which is evaluated as a positive integer value.

REPLACE = string_expression₂
Designates the string to be inserted at the start position.

SUPPRESSED-LENGTH =
Specifies whether string_expression₂ overwrites or replaces parts of the (input) string.

SUPPRESSED-LENGTH = *REPLACE-LENGTH
Starting at the position specified with START=.. , the input string is to be overwritten with string_expression₂ (in the length of string_expression₂). If the input string does not contain enough characters for overwriting, the remaining characters of string_expression₂ are appended.

SUPPRESSED-LENGTH = digit
Specifies the number of characters which are to be suppressed and to be replaced by string_expression₂ . Suppression is to start at the position specified with START=.. . If the specified number of characters does not match the length of string_expression2, the length of the result string will differ from the length of the input string.

Result

Modified string.

Error messages

SDP0412     START POSITION OUT OF RANGE
SDP0413     ILLEGAL LENGTH

Examples

/A = 'ABCDEFGHIJ'
/B = REPLACE(STRING = A, REPLACE = '**')
/SHOW-VARIABLE A
A = ABCDEFGHIJ
/SHOW-VARIABLE B
B = **CDEFGHIJ
/C = 10
/B = REPLACE(STRING = A, START = C, REPLACE = 'KLMN')
/SHOW-VARIABLE B
B = ABCDEFGHIKLMN
/B = REPLACE(STRING = A, START = 0, REPLACE = '**')
SDP0412 START POSITION OUT OF RANGE
SDPO431 ERROR 'SDPO412' IN BUILTIN FUNCTION 'REPLACE'
SDP0239 ERROR DURING EVALUATION OF RIGHT SIDE OF ASSIGNMENT
/A = REPLACE(STRING = A, REPLACE = '****')
/SHOW-VARIABLE A
A = ****EFGHIJ

The last assignment to variable B results in error SDP0412 since an incorrect value was entered for START.

/WHILE (INDEX(TESTSTRING,X'00') > 0)
/    TESTSTRING = REPLACE(TESTSTRING,INDEX(TESTSTRING,X'00'),X'40') 
/END-WHILE 

Within the TESTSTRING variable, all X’00’ are replaced by blanks (X’40’).

Examples with the operand SUPPRESSED-LENGTH=..

/A = 'I am the king of the replace()'
/B1= 'developer'              "REPLACE"
/B2 = REPLACE (A,10,B1,4)     " 10th position is 'k' "
/SHOW-VAR B2
B2 = I am the developer of the replace()
/C1 = 'not '                  "INSERT"
/C2 = REPLACE (A,6,C1,0)      " 6th position is 't' "
/SHOW-VAR C2
C2 = I am not the king of the replace()
/D1 = 'replacement'           "OVERWRITE (like before)"
/D2 = REPLACE (A,22,D1)       " 22th position is 'r' "
/SHOW-VAR D2
D2 = I am the king of the replacement