split-re

Arguments: regexp string &key count (start 0) end (return :string) case-fold single-line multiple-lines ignore-whitespace limit

Warning: incompatible change by patch. This function was updated with a patch released in February, 2013. The patch makes this function similar to the equivalent function in Perl. See below for information on how the behavior has changed (aside from the new limit keyword argument, some forms which errored now return values and nil is returned in some cases where previously ("") was returned.

This function scans string for a delimiter given by regexp and returns a list of substrings. If count is given, then split into no more than count substrings, in which case the last substring will contain the rest of the string. If start and end are specified, the whole string is scanned but only delimiters between start (inclusive) and end (exclusive) are considered.

If limit is specified, it should be a non-negative integer. 0 means no limit. Any positive value means no more than that number of strings will be returned, with the last string containing the rest of the output, if any:

cl-user(8): (split-re ":" "a:b:c:d" :limit 3)
("a" "b" "c:d")

In most cases, limit is like count (which limits the number of matches), but not in the case where the empty string is matched. limit should be used instead of count.

If count is given, then split into no more than count substrings, in which case the last substring will contain the rest of the string. Use of count is deprecated in favor of the limit keyword argument.

If regexp matches a zero length string, split-re works to split each individual characters, excluding the characters that matched the regexp.

(split-re "/*" "/foo/bar") => ("f" "o" "o" "b" "a" "r")

Prior to the patch, that form signaled an error.

If input is empty, nil is returned unless non-zero limit argument is given.

The trailing empty fields are removed unless non-zero limit is given.

(split-re ":" ":a:b:c:::") -> ("" "a" "b" "c")
(split-re ":" ":a:b:c:::" :limit 100) -> ("" "a" "b" "c" "" "" "")

The return argument can be :string (the default, the return value will be a list of strings) or :index (the return value will be a list of dotted pairs or indexes into string corresponding to the substrings that would have been returned if return was :string). See the example.

See the section Matching mode in the regexp2 module in regexp.htm for information on the case-fold, single-line, multiple-lines, and ignore-whitespace keyword arguments.

The symbol naming this operator is also exported from the regexp package.

Examples

(excl:split-re "-" "a-b-c-d")
  --> ("a" "b" "c" "d")
(split-re ":" "1:2:3:4:5")
  --> ("1" "2" "3" "4" "5")
(split-re ":" "1:2:3:4:5" :return :index)
  --> ((0 . 1) (2 . 3) (4 . 5) (6 . 7) (8 . 9))
(split-re ":" "1:2:3:4:5" :limit 2)
  --> ("1" "2" "3:4:5")
(split-re ":" "1:2:3:4:5" :start 2)
  --> ("1:2" "3" "4" "5")
(split-re ":" "1:2:3:4:5" :start 2 :return :index)
  --> ((0 . 3) (4 . 5) (6 . 7) (8 . 9))

cl-user(23): (split-re "/+" "abc/def")
("abc" "def")
cl-user(24): (split-re "/+" "/abc//def///ghi")
("" "abc" "def" "ghi")
cl-user(25): 


;; This results with the new patch are different from
;; the pre-patch behavior:
(split-re "/+" "") --> () ;; pre-patch returned ("")
(split-re "/+" "" :limit 10) --> ("") ;; pre-patch no limit arg
(split-re "/+" "/abc/def" :start 2 :end 2) --> ()
  ;; pre-patch "/abc/def"
(split-re ":" ":a:b:c:::") --> ("" "a" "b" "c")
  ;; pre-patch ("" "a" "b" "c" "" "" "")
(split-re ":" ":a:b:c:::" :limit 100) 
  --> ("" "a" "b" "c" "" "" "")
(split-re "/*" "/foo/bar") 
  --> ("f" "o" "o" "b" "a" "r")
  ;; pre-patch ERROR

See The new regexp2 module in regexp.htm for further information on this function and the regexp2 module.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had significant revisions compared to the 8.2 page.
Created 2019.8.20.