CHANGE(), SWAP()

The CHANGE() function replaces occurrences of a substring within a string by another substring. The synonym SWAP() can be used.

Format

CHANGE(string, old, new{, occurrence{, start}})

where

string

is the string in which the replacement is to occur.

old	evaluates to the substring to be replaced.

new	evaluates to the substring with which old is to be replaced.

occurrence

evaluates to the number of occurrences of old to be replaced. If omitted or specified as a value of less than one, all occurrences are replaced.

start

specifies the first occurrence to be replaced. If omitted or specified as a value of less than one it defaults to one.

The CHANGE() function replaces the specified occurrences of old within string by new.

If old is a null string, the function returns string unchanged. The CHANGE() function is identical to EREPLACE() if old is not a null string.

If new is a null string, all occurrences of old are removed.

If the $MODE NOCASE.STRINGS compiler directive is used, matching of old against string is case insensitive.

The default behaviour of the CHANGE() and SWAP() functions is that overlapping substrings are allowed when searching string for the desired occurrence of old. Thus

X = CHANGE("aaaaaaaaa", "aa", "xx", 0, 3)

yields a result of "aaxxxxxxa"

The CHANGE.NO.OVERLAP setting of the $MODE compiler directive can be used to select an alternative behaviour in which substrings do not overlap. The same example would then yield a result of "aaaaxxxa".

Examples

PRINT CHANGE("ABRACADABRA", "A", "a", 3, 2)

This statement results in printing the string "ABRaCaDaBRA".