Name: replace

Type: command

Syntax: replace <oldString> with <newString> in <container>

Summary:
Replaces text in a <container> with other text.

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Example:
replace "A" with "N" in thisVariable -- changes all As to Ns

Example:
replace return with empty in field 1 -- runs lines together

Example:
replace somethingOld with "\" in it

Example:
replace ".com" with somethingNew in URL "file:stuff.txt"

Example:
put "12.34.56.78" into p
replace "." with empty in char 4 to -1 of p  -- 12.345678

Parameters:
oldString (string):
Any expression that evaluates to a string, and specifies the text to
replace. 

newString (string):
Any expression that evaluates to a string, and specifies the text to
replace the oldString with.

container:
A field, button, or variable, or the message box.

Description:
Use the <replace> <command> to replace all instances of one <string>
with another <string>.

The <replace> <command> is faster than the <replaceText> <function>, but
does not support <regular expression|regular expressions>: you can
replace only an exact <string> of text.

>*Note:* The <replace> <command> is not recursive and behaves in much the 
> same way a text editor would perform a plain text search, looking at each 
> character in the text once only. This means that if there are two 
> overlapping instances of matching text, only the first will be replaced. 
> For example:

    put "x:y:y:y:y:x:" into tChangeMe
    replace ":y:" with "::" in tChangeMe
    put tChangeMe -- returns x::y::y:x
    
> If the goal were to remove every lone y within two colons that appears 
> in the text, it would be more effective to take advantage of how the 
> text to remove is contained within two identical characters, along with 
> the <itemDelimiter> <property>, such as in the following:

    put "x:y:y:y:y:x" into tChangeMe
    set the itemDelimiter to ":"
    repeat with tCount = 2 to (the number of items in tChangeMe) - 1
        if item tCount of tChangeMe is "y" then 
            put empty into item tCount of tChangeMe
        end if
    end repeat
    put tChangeMe -- returns x:::::x

>*Important:*  You can use the <replace> <command> on a
> <field(keyword)>, but doing so removes any formatting (fonts, styles,
> colors, and sizes) in the field. To preserve existing styling in
> fields use the <replace in field> command.

References: find (command), filter (command), replace (command),
replace in field (command), function (control structure),
replaceText (function), command (glossary), regular expression (glossary),
container (glossary), property (glossary), string (keyword), field (keyword), 
field (object), itemDelimiter (property)

Tags: text processing

