ReplaceTextWithPattern

Examines a string in search of a specific sub-string. It replaces all found instances of the sub-string with a different sub-string, before returning the modified string. This function can be used both with literal string values or regular expressions (RegEx).

Syntax

Parameters

Parameter Name	Type	Description	Optional?	Default Value
SourceText	String	The string to interrogate.	No	n/a
SearchText	String	The sub-string to replace wherever it is found in SourceText.	No	n/a
ReplacementText	String	The sub-string to replace every instance of SearchText.	No	n/a
IsCaseSensitive	Boolean	Determines if the search should be case sensitive. If left as an empty string, the function will not consider case when looking for sub-strings.	Yes	0/False

Output

The updated string with all instances of the specified sub-strings replaced with the replacement string.

Use Case

You can use the ReplaceTextWithPattern function with literal values to easily make alterations to a string. Consider that you are working with the following CSV-formatted list, which is stored in a variable called VARCustomerData:

Each row in this CSV data is currently separated with hashes (#). Unfortunately, before the data can be used by a particular application, it must be reformatted to use pipe symbols (|) instead of hashes. The quickest way to replace these characters is to call the ReplaceTextWithPattern function, using VARCustomerData as its SourceText argument:

The string returned by this expression will be identical to the contents of VARCustomerData, except that any hashes will have been replaced by pipes.

Using regular expressions instead of literal sub-strings allows you to make replacements based on formatting rather than specific values.

For example, you might want to write an online order form that asks users for their credit card details, but when it displays those details back to them, you want the first 12 digits of their card number to be replaced with asterisks.

To do this, you could write a regular expression that checks the format of the credit card number string, rather than the string's literal contents. This is an example of a regular expression you might use:

Each instance of \d{4} tells the expression to look for four digits in a row. There are three of these in our regular expression, each of which is followed by a dash. In other words, this regular expression equates to "three consecutive four-digit numbers, each followed immediately by a dash".

Although every person's credit card number is unique, this regular expression can be used to confirm that the first twelve digits are found no matter what they are, as long as each one is followed by a dash.

To replace the sub-string located by our regular expression, we're going to use a literal string that uses the same format, but replaces all numbers with asterisks.

We're using a variable called VARUserCardDetails to store the user's credit card number; to get the string we need, we'd write an expression like this:

Now, if the user were to enter a credit card number ending in 9876, our expression will replace the first twelve digits in VARUserCardDetails, returning the following string:

Because the function searches the entire string, VARUserCardDetails can contain any number of characters and - as long as at least one credit card number in the correct format is found - its first twelve digits will be replaced with asterisks. This could be useful when a lot of numbers need to be anonymised, for example a CSV containing dozens or hundreds of values. The function will replace all instances matching our regular expression, meaning the CSV could be completely converted without having to search for each literal credit card number individually.