STR_SUBSTITUTE

Use the STR_SUBSTITUTE script function to replace specific characters or strings within a target string. You can also use this function to entirely delete a specific string by setting the New parameter to two consecutive quotation marks ("") without any spaces.

Syntax

STR_SUB[STITUTE] (String [, [Old] [, New]])

Parameters

Parameter	Description	Format	Default Value
String	Specifies the alphanumeric string in which the replacement occurs.	Script literal or script variable	n.a.
Old	(Optional) Defines the alphanumeric string to be replaced. The length of this parameter is unlimited. If omitted, the function targets every individual empty space.	Script literal or script variable	" " (empty space)
New	(Optional) Defines the alphanumeric string that replaces the Old string. The length of this parameter is unlimited. If omitted, the function replaces the Old parameter with a single empty space.	Script literal or script variable	" " (empty space)

Parameter

Description

Format

Default Value

String

Specifies the alphanumeric string in which the replacement occurs.

Script literal or script variable

n.a.

Old

(Optional) Defines the alphanumeric string to be replaced. The length of this parameter is unlimited.

If omitted, the function targets every individual empty space.

Script literal or script variable

" " (empty space)

New

(Optional) Defines the alphanumeric string that replaces the Old string. The length of this parameter is unlimited.

If omitted, the function replaces the Old parameter with a single empty space.

Script literal or script variable

" " (empty space)

Return Codes

The function returns the newly generated string reflecting the applied replacements.
If the Old string is not found within the String parameter, the function returns the original string unchanged.

Examples

The following script replaces the string "environment" with the string "system". The result is the new string "AE system":

:SET &STRING# = STR_SUBSTITUTE("AE environment", "environment", "system")

The following example replaces the character "A" with the character "B". The result is "BBBBB", which is then printed in the activation report:

: SET &RET# = STR_SUBSTITUTE("AAAAA", "A", "B")

:PRINT &RET#

The following example replaces the entire string "AAAAA" with the character "B". The result "B" is printed in the activation report:

: SET &RET# = STR_SUBSTITUTE("AAAAA", "AAAAA", "B")

:PRINT &RET#

The following example replaces the string "AA" with the string "BB". The result "BBBBA" is printed in the activation report:

: SET &STR1# = "AA"

:SET &STR2# = "BB"

:SET &RET# = STR_SUB("AAAAA", &STR1#, &STR2#)

:PRINT &RET#

The following example demonstrates how to delete empty spaces from a string. The result "AE" is printed in the activation report:

: SET &RET# = STR_SUB("A E", " ", "")

:PRINT &RET#