This function splits string into substrings based on the regular expression separators (see Regular Expressions). Each match for separators defines a splitting point; the substrings between splitting points are made into a list, which is returned.

If omit-nulls is nil (or omitted), the result contains null strings whenever there are two consecutive matches for separators , or a match is adjacent to the beginning or end of string . If omit-nulls is t, these null strings are omitted from the result.

If separators is nil (or omitted), the default is the value of split-string-default-separators.

As a special case, when separators is nil (or omitted), null strings are always omitted from the result. Thus:

(split-string " two words ") ⇒ ("two" "words")

The result is not ("" "two" "words" ""), which would rarely be useful. If you need such a result, use an explicit value for separators :

(split-string " two words " split-string-default-separators) ⇒ ("" "two" "words" "")

More examples:

(split-string "Soup is good food" "o") ⇒ ("S" "up is g" "" "d f" "" "d")
(split-string "Soup is good food" "o" t) ⇒ ("S" "up is g" "d f" "d")
(split-string "Soup is good food" "o+") ⇒ ("S" "up is g" "d f" "d")

Empty matches do count, except that split-string will not look for a final empty match when it already reached the end of the string using a non-empty match or when string is empty:

(split-string "aooob" "o*") ⇒ ("" "a" "" "b" "")
(split-string "ooaboo" "o*") ⇒ ("" "" "a" "b" "")
(split-string "" "") ⇒ ("")

However, when separators can match the empty string, omit-nulls is usually t, so that the subtleties in the three previous examples are rarely relevant:

(split-string "Soup is good food" "o*" t) ⇒ ("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d")
(split-string "Nice doggy!" "" t) ⇒ ("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")
(split-string "" "" t) ⇒ nil

Somewhat odd, but predictable, behavior can occur for certain “non-greedy” values of separators that can prefer empty matches over non-empty matches. Again, such values rarely occur in practice:

(split-string "ooo" "o*" t) ⇒ nil
(split-string "ooo" "\\|o+" t) ⇒ ("o" "o" "o")

If the optional argument trim is non-nil, it should be a regular expression to match text to trim from the beginning and end of each substring. If trimming makes the substring empty, it is treated as null.