StringSplit

Separates a string into an array of substrings using the specified delimiter characters.

[v1.1.13+]: Deprecated: This command is not recommended for use in new scripts. Use the StrSplit function instead.

StringSplit, OutputArray, InputVar , DelimiterChars, OmitChars

Parameters

OutputArray

The name of the pseudo-array in which to store each substring extracted from InputVar. For example, if MyArray is specified, the command will put the number of substrings produced (0 if none) into MyArray0, the first substring into MyArray1, the second into MyArray2, and so on.

Within a function, to create a pseudo-array that is global instead of local, declare MyArray0 as a global variable inside the function (the converse is true for assume-global functions). However, it is often also necessary to declare each element, due to a common source of confusion. For more details, see Functions.

InputVar

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

Note: InputVar must not be one of the variables in OutputArray.

DelimiterChars

If blank or omitted, each character of InputVar will be treated as a separate substring.

Otherwise, specify one or more characters (case-sensitive), each of which is used to determine where the boundaries between substrings occur in InputVar. Since the delimiter characters are not considered to be part of the substrings themselves, they are never copied into OutputArray. Also, if there is nothing between a pair of delimiter characters within InputVar, the corresponding array element will be blank.

For example: `, (an escaped comma) would divide the string based on every occurrence of a comma. Similarly, %A_Space%%A_Tab% would create a new array element every time a space or tab is encountered in InputVar.

To use a string as a delimiter rather than a character, first use StrReplace() or StringReplace to replace all occurrences of the string with a single character that is never used literally in the text, e.g. one of these special characters: ¢¤¥¦§©ª«®µ¶. Consider this example, which uses the string <br> as a delimiter:

StringReplace, NewHTML, HTMLString, <br>, ``, All  ; Replace each <br> with an accent.
StringSplit, MyArray, NewHTML, ``  ; Split the string based on the accent character.

In [v1.1.13+], use MyArray := StrSplit(HTMLString, "<br>") instead.

OmitChars

If blank or omitted, no characters will be excluded. Otherwise, specify a list of characters (case-sensitive) to exclude from the beginning and end of each array element. For example, if OmitChars is %A_Space%%A_Tab%, spaces and tabs will be removed from the beginning and end (but not the middle) of every element.

If DelimiterChars is blank or omitted, OmitChars indicates which characters should be excluded from the array.

Unlike the last parameter of most other commands, commas in OmitChars must be escaped (`,).

Remarks

If the array elements already exist, the command will change the values of only the first N elements, where N is the number of substrings present in InputVar. Any elements beyond N that existed beforehand will be unchanged. Therefore, it is safest to use the zero element (MyArray0) to determine how many items were actually produced by the command.

Whitespace characters such as spaces and tabs will be preserved unless those characters are themselves delimiters or included in OmitChars. Spaces and tabs can be trimmed from both ends of any variable by assigning it to itself while AutoTrim is on (the default). For example: MyArray1 = %MyArray1%.

To split a string that is in standard CSV (comma separated value) format, use a parsing loop since it has built-in CSV handling.

To arrange the fields in a different order prior to splitting them, use the Sort command.

If you do not need the substrings to be permanently stored in memory, consider using a parsing loop -- especially if InputVar is very large, in which case a large amount of memory would be saved. For example:

Colors := "red,green,blue"
Loop, Parse, Colors, `,
    MsgBox Color number %A_Index% is %A_LoopField%.

StrSplit(), Parsing loop, Arrays, Sort, SplitPath, IfInString, StringGetPos, StringMid, StringTrimLeft, StringTrimRight, StringLen, StringLower, StringUpper, StringReplace

Examples

Separates a sentence into an array of words and reports the fourth word.

TestString := "This is a test."
StringSplit, word_array, TestString, %A_Space%, .  ; Omits periods.
MsgBox, The 4th word is %word_array4%.

Separates a comma-separated list of colors into an array of substrings and traverses them, one by one.

Colors := "red,green,blue"
StringSplit, ColorArray, Colors, `,
Loop, %ColorArray0%
{
    this_color := ColorArray%A_Index%
    MsgBox, Color number %A_Index% is %this_color%.
}