# Function Reference

# StringReplace

Replaces substrings in a string.

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

## Parameters

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.

## Remarks

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.

## Related

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

## Example

### Example 1

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

### Example 2

    #include <MsgBoxConstants.au3>
    #include <StringConstants.au3>

    Example()

    Func Example()
        Local $sSubject

        ; Subject definition
        For $i = 65 To 90
            $sSubject &= Chr($i) & Chr($i + 32) ; "AaBb...YyZz" : 52 chars (26*2)
        Next
        For $i = 1 To 17 ; Do not increase this loop too much, it would quickly generate a very big subject !
            $sSubject &= $sSubject
        Next
        ConsoleWrite("Subject is " & StringLen($sSubject) & " long" & @CRLF & @CRLF) ; 6,815,744 chars when 17 in For loop

        _CompareSpeed($sSubject, True)  ; case sensitive
        _CompareSpeed($sSubject, False) ; case insensitive
    EndFunc   ;==>Example

    Func _CompareSpeed(ByRef $sSubject, $bSensitive)
        Local $sSearch, $sReplace, $hTimer, $sOutput1, $sOutput2

        ; Search string and Replace string
        $sSearch = "Aa"
        $sReplace = "12"

        ConsoleWrite("Case " & ($bSensitive ? "" : "in") & "sensitive :" & @CRLF)

        ; StringReplace
        $hTimer = TimerInit()
        $sOutput1 = StringReplace($sSubject, $sSearch, $sReplace, 0, ($bSensitive ? $STR_CASESENSE : $STR_NOCASESENSE))
        ConsoleWrite(@extended & " replacements with StringReplace        Timer : " & TimerDiff($hTimer) & @CRLF)

        ; StringRegExpReplace
        $hTimer = TimerInit()
        $sOutput2 = StringRegExpReplace($sSubject, ($bSensitive ? "" : "(?i)") & $sSearch, $sReplace)
        ConsoleWrite(@extended & " replacements with StringRegExpReplace  Timer : " & TimerDiff($hTimer) & @CRLF & @CRLF)

        ; Keep this ?
        If Not ($sOutput1 == $sOutput2) Then
            MsgBox($MB_TOPMOST, "No way", "StringReplace output <> StringRegExpReplace output !")
        EndIf
    EndFunc   ;==>_CompareSpeed