Function Reference


StringSplit

Splits up a string into substrings depending on the given delimiters.

StringSplit ( "string", "delimiters" [, flag = 0] )

Parameters

string The string to evaluate.
delimiters One or more characters to use as delimiters (case sensitive).
flag [optional] Changes how the string split works, add multiple flag values together if required:
    $STR_CHRSPLIT (0) = each character in the delimiter string will mark where to split the string (default)
    $STR_ENTIRESPLIT (1) = entire delimiter string is needed to mark the split
    $STR_NOCOUNT (2) = disable the return count in the first element - effectively makes the array 0-based (must use UBound() to get the size of the array in this case).

Constants are defined in StringConstants.au3.

Return Value

Returns an array, by default the first element ($aArray[0]) contains the number of strings returned, the remaining elements ($aArray[1], $aArray[2], etc.) contain the delimited strings. If the flag parameter is set to $STR_NOCOUNT (2) then the count is not returned in the first element.

If no delimiters were found then the @error flag is set to 1:
    If flag is not equal to $STR_NOCOUNT, $aArray[0] is set to 1 and the full string is returned in $aArray[1].
    If flag is equal to $STR_NOCOUNT, the full string is returned in $aArray[0].

Remarks

If you use an empty string "" for the delimiters, each character will be returned as an element.

If the delimiter string contains several characters function behaviour depends on the flag setting. If set to $STR_CHRSPLIT the string will be split at every instance of each of the individual characters in the delimiter - if set to $STR_ENTIRESPLIT then the string will only be split when the entire delimiter string is encountered. See second example below.

Note that the macro @CRLF is actually a 2 character string, so unless the flag parameter to $STR_ENTIRESPLIT extra blank lines will be generated as the string is split on both @CR and @LF.

StringSplit() is very useful as an alternative to StringInStr() as well as a means to populate an array.

Related

StringInStr, StringLeft, StringLen, StringLower, StringMid, StringRight, StringTrimLeft, StringTrimRight, StringUpper

Example

Example 1

#include <MsgBoxConstants.au3>

Example()

Func Example()
        Local $aDays = StringSplit("Mon,Tues,Wed,Thur,Fri,Sat,Sun", ",") ; Split the string of days using the delimiter "," and the default flag value.
        #cs
                The array returned will contain the following values:
                $aDays[1] = "Mon"
                $aDays[2] = "Tues"
                $aDays[3] = "Wed"
                ...
                $aDays[7] = "Sun"
        #ce

        For $i = 1 To $aDays[0] ; Loop through the array returned by StringSplit to display the individual values.
                MsgBox($MB_SYSTEMMODAL, "", "$aDays[" & $i & "] - " & $aDays[$i])
        Next
EndFunc   ;==>Example

Example 2

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

Example()

Func Example()
        Local $sText = "This\nline\ncontains\nC-style breaks." ; Define a variable with a string of text.
        Local $aArray = StringSplit($sText, '\n', $STR_ENTIRESPLIT) ; Pass the variable to StringSplit and using the delimiter "\n".
        ; Note that flag parameter is set to $STR_ENTIRESPLIT (1) as it would split at \ or n otherwise.
        #cs
                The array returned will contain the following values:
                $aArray[1] = "This"
                $aArray[2] = "line"
                ...
                $aArray[4] = "C-style breaks."
        #ce

        For $i = 1 To $aArray[0] ; Loop through the array returned by StringSplit to display the individual values.
                MsgBox($MB_SYSTEMMODAL, "", "$aArray[" & $i & "] - " & $aArray[$i])
        Next
EndFunc   ;==>Example

Example 3

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

Example()

Func Example()
        Local $sText = "This\nline\ncontains\nC-style breaks." ; Define a variable with a string of text.

        ; Pass the variable to StringSplit and using the delimiter "\n".
        ; Note that flag parameter is set to $STR_ENTIRESPLIT (1) as it would split at \ or n otherwise.
        MsgBox($MB_SYSTEMMODAL, "", StringSplit($sText, '\n', $STR_ENTIRESPLIT)[2]) ; Directly access the array index by using array access on expression.
        #cs
                An internal temporary array is used to return a string that may contain one of the following values:
                $aArray[1] = "This"
                $aArray[2] = "line"
                ...
                $aArray[4] = "C-style breaks."
        #ce
EndFunc   ;==>Example