Function Reference


Replaces substrings in a string.

StringReplace ( "string", "searchstring/start", "replacestring" [, occurrence = 0 [, casesense = 0]] )


string The string to evaluate.
searchstring/start The substring to search for or the character position to start the replacement.
replacestring The replacement string.
occurrence [optional] The number of times to replace the searchstring. Use a negative occurrence to replace from the right side.
    0 = all searchstrings will be replaced (default)
casesense [optional] Flag to indicate if the operations should be case sensitive.
    $STR_NOCASESENSE (0) = not case sensitive, using the user's locale (default)
    $STR_CASESENSE (1) = case sensitive
    $STR_NOCASESENSEBASIC (2) = not case sensitive, using a basic/faster comparison

Constants are defined in StringConstants.au3.

Return Value

Returns the new string with the number of replacements performed stored in the @extended macro.


By default or if the occurrence is positive the search/replace is performed left-to-right. Thus, StringReplace("aaa", "aa", "bb") returns "bba"

If the start method is used the occurrence and casesense parameters are ignored. The function will replace the characters in "string", starting at the requested position, with the characters in "replacestring" - as many characters will be replaced as are in "replacestring". However, if there are not enough characters in "string" for the entire "replacestring" to be inserted an empty string is returned and @error is set to 1.


StringAddCR, StringLeft, StringLen, StringLower, StringMid, StringRight, StringStripWS, StringTrimLeft, StringTrimRight, StringUpper


#include <MsgBoxConstants.au3>

; Replace a blank space (' ') with a - (minus) character.
Local $sString = StringReplace("This is a sentence with whitespace.", " ", "-")
Local $iReplacements = @extended
MsgBox($MB_SYSTEMMODAL, "", $iReplacements & " replacements were made and the new string is:" & @CRLF & @CRLF & $sString)