This function replaces a substring of text
with the character string specified in new and returns the changed text.
The substring is determined as follows:
The variant with the arguments off
and len replaces
the substring defined by the offset off and the length len. At least one of these additions must be defined.
The variant with the arguments sub or regex scans the text for the occurrence specified
in occ
for a match with the substring specified in substring or with a
regulären Ausdruck specified in regex and replaces the occurrence. If occ
contains the value 0, all occurrences are replaced. If substring is empty,
an exception from the class CX_SY_STRG_PAR_VAL is raised. The search is case-sensitive by default, but
this can be overridden using the parameter case. If no substring is found, the unchanged content of text is returned.
Borderline cases for the variants with the arguments off and len:
If only off is specified or if the value 0 is specified for len,
replace works like insert.
If only len is specified or if off has the value 0, the first segment of the length len is replaced.
If the value of off is equal to the length of text,
the value of len must be equal to 0 or len is
not specified. The character string new is then attached to the end of text.
If a regular expression is used with regex, special
replacement models that allow references to particular
occurrences can be specified in new. Note that, in regular replacement texts,
the associated special characters $, &,
`, and ´ plus the escape character \ must be transformed to literal characters using the prefix \.
Example
The result of the following replacement is "<title>Th<b>i</b>s <b>i</b>s the <i>
T<b>i</b>tle</i> </title>". In an HTML line, a particular letter is placed in format tags if it is not itself in a tag.
DATA(html) = `<title>This is the <i>Title</i></title>`.
DATA(repl) = `i`.
html = replace( val = html regex = repl && `(?![^<>]*>)`
with = `<b>$0</b>`
occ = 0 ).