split-re

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

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")

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): 

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

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.