String.replace("pattern","replacement")

---

---

String/List.replace("pattern","replacement")

This operator allows simple text transformations without use of runCommand as was hitherto required.

pattern and replacement are both one of:

• an action code expression (which includes just referencing a single attribute name')
• a quoted string; quoted strings may be either:
  • a literal string (i.e. actual text)
  • a regular expression

$MyString.replace("pattern","replacement")

In its simplest form, the operator creates a new string in which each occurrence of pattern is replaced by the string replacement, i.e. a global replacement. The source string is not changed by replace; if you wish to change the string itself, write back over the source attribute:

$MyString = $MyString.replace("Hello","Goodbye") 

transforms a $MyString value of "Hello World" to "Goodbye World".

Where pattern is a regular expression, and may contain wildcard characters such as "." (which matches any character) or "*" (which matches 0 or more occurrences of the preceding character). Thus ".*" matches zero or more instances of any character.

Where parentheses in pattern create multiple back-references, replacement strings can include $1, $2, etc., to insert the relevant back-reference matched string ($1 through $9 allowed, and with $0 being the entire match).

Examples:

$MyString.replace("Spenser","Spencer") 

$MyString.replace("(a|e|i|o|u)","")// deletes all vowels

$MyString = "I do not like green eggs".replace("(green) (eggs)","$2 $1") "I do not like eggs green"

Although multiple matches can be replace with the same string, to replace multiple matches with different strings requires chained .replace() calls. Consider formatting a large number to Continental style. This means inserting spaces as the group delimiter and a comma for the decimal delimiter. Assume $MyNumber's value is 1234567.89:

$MyString = $MyNumber.replace("(\d)(?=(?:\d{3})+([^\d]))","$1 ").replace("\.",",") 

Now, 1234567.89 becomes "1 234 567,89".

Some comma-delimited formats use straight double quotes for all/some values and demand that if this character appears in a value that is it escaped by doubling the character. If $Text is

He shouted "Hello!" at the top of his voice. 

Then it could be escaped for CSV export like so:

…,"^value($Text.replace('"','""'))^",… 

That exports:

…,"He shouted ""Hello!"" at the top of his voice.",… 

Note that in this instance using a single straight quote (instead of the more normal straight double quote) to contain the find and replace patterns works just fine. Also, there is no need to escape typographic double quotes, i.e. 'smart' or 'curly' quotes in this context.

From v7.5.3, this functions respects existing rich text styling.

Short form for deletions

If the replacement string is omitted, the one-argument form $MyString.replace(pattern) returns a copy of $MyString in which every occurrence of the pattern is removed.

Trimming leading/trailing whitespace

$MyString = $MyString.replace("^ +","").replace(" +$","") 

The ' +' means one or more space characters. The first replace finds such a sub-string immediately following the start of the whole string ^), whilst the second does the same for a sub-string immediately before the end of the string ($). If applied to multi-paragraph string, e.g. with line breaks such as in $Text, every paragraph is trimmed. Likely this is what is desired, but care is needed in more specialist situations - so testing sample strings/texts is a good idea before changing actual data of value. If working with List or Sets a slightly different code is needed.

Trimming leading/trailing quotes

Because Tinderbox cannot escape quote characters (i.e. \" or \' do not escape the quote), use String.substr() to trim enclosing quotes on a string. Note that the latter, working on location in the string and not character type, cannot work on paragraphs within a string, such as in the example above.

Dealing with inline quote characters

Because pattern is parsed for regular expressions, it may be possible to use the '\dnn' form described here to work around the lack of escaping from single double quotes within strings.