In this example, a string containing a list of fruit names separated by single semi-colons is being split using a string type splitter that is a single semi-colon.

EXAMPLE

fruits = Uize.Str.Split.split ('apple;orange;pear;peach;strawberry;watermelon',';');

After the above statement has been executed, the value of the fruits variable will be the array ['apple','orange','pear','peach','strawberry','watermelon'].

In this example, a string containing a list of fruit names separated by various different delimiters that are one or more non-word characters is being split using a regular expression splitter that matches on one or more non-word characters.

EXAMPLE

fruits = Uize.Str.Split.split ('apple-|-orange,pear;peach<>strawberry...watermelon',/\W+/);

After the above statement has been executed, the value of the fruits variable will be the array ['apple','orange','pear','peach','strawberry','watermelon'].

In this example, a multi-line string is being split using a regular expression that supports a variety of different EOL (End Of Line) styles.

EXAMPLE

lines = Uize.Str.Split.split ('line 1\rline 2\nline 3\r\nline 4',/\r\n|[\r\n]/);

After the above statement has been executed, the value of the lines variable will be the array ['line 1','line 2','line 3','line 4']. The regular expression being used to split the multi-line string supports three different EOL styles: a carriage return (the '\r' character) followed by a line feed (the '\n' character), just a single carriage return character, or just a single line feed character.

Because the Uize.Str.Split.split method is a strict implementation of the ECMA-262 specification for the split instance method of JavaScript's String object, it supports including the regular expression captures in the returned array.

So, for example, if we were splitting a multi-line string into separate lines and wanted to capture the specific line ending characters used for each of the lines (they may be inconcistent across all the lines of the multi-line string), then we can use the unique behavior of the Uize.Str.Split.split method as follows...

EXAMPLE

lines = Uize.Str.Split.split ('line 1\rline 2\nline 3\r\nline 4',/(\r\n|[\r\n])/);

After the above statement has been executed, the value of the lines variable will be the array ['line 1','\r','line 2','\n','line 3','\r\n','line 4']. Because the entire splitter regular expression is inside a capture (i.e. the parentheses), the entire matched splitter is included in the returned array for each line of the multi-line string. When the Uize.Str.Split.split method builds up the result array, it follows the array element for each split part with elements for all the captures in the regular expression, in the order in which the captures occur in the regular expression.

Because the Uize.Str.Split.split method includes captures from a regular expression splitter in the returned array, an extra step is needed if you wish to use parentheses for grouping in a regular expression but don't wish the captures to be included in the result array.

EXAMPLE

words = Uize.Str.Split.split ('solar<_-_>power<_-_-_>will<_-_-_-_>win',/<(?:-=)+->/);

After the above statement has been executed, the value of the words variable will be the array ['solar','power','will','win']. The regular expression is using a group to allow matching of one or more of the substring '-='. However, we don't want those matched characters to pollute the result array - we only want the words that are split out from the string. To accomplish this, we use a feature of regular expressions that allows a group to not be treated as a capture, simply by prefixing the contents of the group expression (i.e. the stuff inside the group's parentheses) with the special characters ?: - this tells the regular expression engine to not capture the characters matched by the group.

Microsoft's JScript interpreter exhibits an issue where empty split values are omitted when a regular expression splitter is used (but not when a string splitter is used).

EXAMPLE

result = 'foo,,bar'.split (/,/);

In the above example, a string is being split using a regular expression splitter that matches a single comma. In compliant JavaScript interpreters, the above statement would produce a result array with the value ['foo','','bar'] - exactly the same result as if you used a simple string splitter (i.e. 'foo,,bar'.split (',')).

For a reason that is hard to fathom, the JScript interpreter omits the second empty string element to produce, instead, the result ['foo','bar']. It's hard to justify or defend this implementation choice, as it wreaks havoc with using the split instance method to parse lists of values that were serialized using the Array object's join instance method, and where some of the values were empty strings.

The Uize.Str.Split.split method fixes this issue, so it can be used in Internet Explorer and WSH (Windows Script Host) to safely split strings using a regular expression splitter.

While the split instance method of JavaScript's built-in String object is supposed to include captures from a regular expression splitter in the returned array, this behavior is not supported by some JavaScript interpreters - notably Microsoft's JScript interpreter.

This means that the statement 'line 1\rline 2\nline 3\r\nline 4'.split (/(\r\n|[\r\n])/) would return the result array ['line 1','line 2','line 3','line 4'] in the JScript interpreter, and not the array ['line 1','\r','line 2','\n','line 3','\r\n','line 4'] as it should. The Uize.Str.Split.split method fixes this issue, so it can be used in Internet Explorer and WSH (Windows Script Host) to safely split strings using a regular expression splitter.