StrReplace() / StringReplace

Replaces the specified substring with a new string.

StrReplace() [v1.1.21+]

ReplacedStr := StrReplace(Haystack, SearchText , ReplaceText, OutputVarCount, Limit := -1)

Parameters

Haystack

The string whose content is searched and replaced.

SearchText

The string to search for. Matching is not case sensitive unless StringCaseSense has been turned on.

ReplaceText

SearchText will be replaced with this text. If omitted or blank, SearchText will be replaced with blank (empty). In other words, it will be omitted from OutputVar.

OutputVarCount

Specify a variable in which to store the number of replacements that occurred (0 if none).

Limit

If Limit is omitted, it defaults to -1, which replaces all occurrences of the pattern found in Haystack. Otherwise, specify the maximum number of replacements to allow. The part of Haystack to the right of the last replacement is left unchanged.

Return Value

This function returns a version of Haystack whose contents have been replaced by the operation. If no replacements are needed, Haystack is returned unaltered.

Examples

; Remove all CR+LF's from the clipboard contents:
Clipboard := StrReplace(Clipboard, "`r`n")

; Replace all spaces with pluses:
NewStr := StrReplace(OldStr, A_Space, "+")

; Remove all blank lines from the text in a variable:
Loop
{
    MyString := StrReplace(MyString, "`r`n`r`n", "`r`n", Count)
    if Count = 0  ; No more replacements needed.
        break
}

StringReplace

Deprecated: This command is not recommended for use in new scripts. Use the StrReplace function instead.

StringReplace, OutputVar, InputVar, SearchText , ReplaceText, ReplaceAll?

Parameters

OutputVar

The name of the variable in which to store the result of the replacement process.

InputVar

The name of the variable whose contents will be read from. Do not enclose the name in percent signs unless you want the contents of the variable to be used as the name.

SearchText

The string to search for. Matching is not case sensitive unless StringCaseSense has been turned on.

ReplaceText

SearchText will be replaced with this text. If omitted or blank, SearchText will be replaced with blank (empty). In other words, it will be omitted from OutputVar.

ReplaceAll?

If omitted, only the first occurrence of SearchText will be replaced. But if this parameter is 1, A, or All, all occurrences will be replaced.

Specify the word UseErrorLevel to store in ErrorLevel the number of occurrences replaced (0 if none). UseErrorLevel implies "All".

ErrorLevel

When the last parameter is UseErrorLevel, ErrorLevel is given the number occurrences replaced (0 if none). Otherwise, ErrorLevel is set to 1 if SearchText is not found within InputVar, or 0 if it is found.

Remarks

For this and all other commands, OutputVar is allowed to be the same variable as an InputVar.

The built-in variables %A_Space% and %A_Tab% contain a single space and a single tab character, respectively. They are useful when searching for spaces and tabs alone or at the beginning or end of SearchText.

[v1.0.45+]: The AllSlow option became obsolete due to improvements to performance and memory utilization. Although it may still be specified, it has no effect.

Examples

; Remove all CR+LF's from the clipboard contents:
StringReplace, Clipboard, Clipboard, `r`n, , All

; Replace all spaces with pluses:
StringReplace, NewStr, OldStr, %A_Space%, +, All

; Remove all blank lines from the text in a variable:
Loop
{
    StringReplace, MyString, MyString, `r`n`r`n, `r`n, UseErrorLevel
    if ErrorLevel = 0  ; No more replacements needed.
        break
}

Related

RegExReplace(), IfInString, StringCaseSense, StringLeft, StringRight, StringMid, StringTrimLeft, StringTrimRight, StringLen, StringLower, StringUpper, StringGetPos, if var is type