Section 24.174. String.split( ): break a string into an array of strings

24.174. String.split( ): break a string into an array of strings

ECMAScript v3

24.174.1. Synopsis

string.split(delimiter, limit)

24.174.1.1. Arguments

delimiter

The string or regular expression at which the string splits.

limit

This optional integer specifies the maximum length of the returned array. If specified, no more than this number of substrings will be returned. If not specified, the entire string will be split, regardless of its length.

24.174.1.2. Returns

An array of strings, created by splitting string into substrings at the boundaries specified by delimiter. The substrings in the returned array do not include delimiter itself, except in the case noted in the Description.

24.174.2. Description

The split( ) method creates and returns an array of as many as limit substrings of the specified string. These substrings are created by searching the string from start to end for text that matches delimiter and breaking the string before and after that matching text. The delimiting text is not included in any of the returned substrings, except as noted at the end of this section. Note that if the delimiter matches the beginning of the string, the first element of the returned array will be an empty stringthe text that appears before the delimiter. Similarly, if the delimiter matches the end of the string, the last element of the array (assuming no conflicting limit) will be the empty string.

If no delimiter is specified, the string is not split at all, and the returned array contains only a single, unbroken string element. If delimiter is the empty string or a regular expression that matches the empty string, the string is broken between each character, and the returned array has the same length as the string does, assuming no smaller limit is specified. (Note that this is a special case because the empty strings before the first character and after the last character are not matched.)

As noted earlier, the substrings in the array returned by this method do not contain the delimiting text used to split the string. However, if delimiter is a regular expression that contains parenthesized subexpressions, the substrings that match those parenthesized subexpressions (but not the text that matches the regular expression as a whole) are included in the returned array.

Note that the String.split( ) method is the inverse of the Array.join( ) method.

24.174.3. Example

The split( ) method is most useful when you are working with highly structured strings. For example:

 "1:2:3:4:5".split(":");  // Returns ["1","2","3","4","5"] "|a|b|c|".split("|");    // Returns ["", "a", "b", "c", ""] 

Another common use of the split( ) method is to parse commands and similar strings by breaking them down into words delimited by spaces:

 var words = sentence.split(' '); 

It is easier to split a string into words using a regular expression as a delimiter:

 var words = sentence.split(/\s+/); 

To split a string into an array of characters, use the empty string as the delimiter. Use the limit argument if you only want to split a prefix of the string into an array of characters:

 "hello".split("");     // Returns ["h","e","l","l","o"] "hello".split("", 3);  // Returns ["h","e","l"] 

If you want the delimiters or one or more portions of the delimiter included in the returned array, use a regular expression with parenthesized subexpressions. For example, the following code breaks a string at HTML tags and includes those tags in the returned array:

 var text = "hello <b>world</b>"; text.split(/(<[^>]*>)/);  // Returns ["hello ","<b>","world","</b>",""] 

24.174.4. See Also

Array.join( ), RegExp; Chapter 11