Name: replaceText

Type: function

Syntax: replaceText(<stringToChange>, <matchExpression>, <replacementString>)

Summary:
Searches for a <regular expression> and replaces the portions that match
the <regular expression>.

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Example:
put replaceText("malformed","mal","well") -- returns "wellformed"

Example:
-- change return-delimited text to comma-delimited
put replaceText(field "Stats",return,comma) into field "Stats"

Example:
put replaceText("colour or color","colou?r","culler")
-- returns "culler or culler"

Example:
-- escape RegEx metacharacter using backslash
put replaceText ( "ABC|DEV" , "\|" , CR )

Parameters:
stringToChange (string): A container reference or literal value.

matchExpression:
A regular expression.

replacementString (string): A container reference or literal value.


Returns:
The <replaceText> function returns the changed <string>.

Description:
Use the <replaceText> function to search for and replace text that
matches a particular pattern.

The <replaceText> function replaces all the occurrences of the
<matchExpression> with the <replacementString>. If more than one
matching substring is found, the <replaceText> function replaces all of
them. 

The <replaceText> function is not as fast as the <replace> <command>,
but is more flexible because you can search for any text that matches a
<regular expression>.

The <stringToChange> and <matchExpression> are always case-sensitive,
regardless of the setting of the <caseSensitive> <property>. (If you
need to make a case-insensitive comparison, use "(?i)" at the start of
the <matchExpression> to make the match case-insensitive.)

>*Note:* A number of characters in regular expressions have special
> meanings and these need to be 'escaped' using backslashes ("\"). For example
> period (".") matches any character, so in order to replace period characters
> using a <regular expression> use "\.", to replace vertical bar characters ("|")
> use "\|" and so on.
> For more information on <regular expressions> see the Perl documentation  
> at http://perldoc.perl.org/perlre.html .

References: replace (command), filter (command), command (glossary),
regular expression (glossary), property (glossary), string (keyword),
caseSensitive (property)

Tags: text processing
