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.

If performing a non-case sensitive ($STR_NOCASESENSE) replacement on a long string, execution time might be reduced by using StringRegExpReplace() with the leading (?i) option. Note that in this case RegEx metacharacters \ . ^ $ | [ ( { * + ? # must be escaped by using a preceding \. See example 2 for performance differences.


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


#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)