elisp: Creating Strings
4.3 Creating Strings
====================
The following functions create strings, either from scratch, or by
putting strings together, or by taking them apart.
-- Function: make-string count character
This function returns a string made up of COUNT repetitions of
CHARACTER. If COUNT is negative, an error is signaled.
(make-string 5 ?x)
⇒ "xxxxx"
(make-string 0 ?x)
⇒ ""
Other functions to compare with this one include ‘make-vector’
(
Vectors) and ‘make-list’ (Building Lists).
-- Function: string &rest characters
This returns a string containing the characters CHARACTERS.
(string ?a ?b ?c)
⇒ "abc"
-- Function: substring string &optional start end
This function returns a new string which consists of those
characters from STRING in the range from (and including) the
character at the index START up to (but excluding) the character at
the index END. The first character is at index zero. With one
argument, this function just copies STRING.
(substring "abcdefg" 0 3)
⇒ "abc"
In the above example, the index for ‘a’ is 0, the index for ‘b’ is
1, and the index for ‘c’ is 2. The index 3—which is the fourth
character in the string—marks the character position up to which
the substring is copied. Thus, ‘abc’ is copied from the string
‘"abcdefg"’.
A negative number counts from the end of the string, so that −1
signifies the index of the last character of the string. For
example:
(substring "abcdefg" -3 -1)
⇒ "ef"
In this example, the index for ‘e’ is −3, the index for ‘f’ is −2,
and the index for ‘g’ is −1. Therefore, ‘e’ and ‘f’ are included,
and ‘g’ is excluded.
When ‘nil’ is used for END, it stands for the length of the string.
Thus,
(substring "abcdefg" -3 nil)
⇒ "efg"
Omitting the argument END is equivalent to specifying ‘nil’. It
follows that ‘(substring STRING 0)’ returns a copy of all of
STRING.
(substring "abcdefg" 0)
⇒ "abcdefg"
But we recommend ‘copy-sequence’ for this purpose (Sequence
Functions).
If the characters copied from STRING have text properties, the
properties are copied into the new string also. Text
Properties.
‘substring’ also accepts a vector for the first argument. For
example:
(substring [a b (c) "d"] 1 3)
⇒ [b (c)]
A ‘wrong-type-argument’ error is signaled if START is not an
integer or if END is neither an integer nor ‘nil’. An
‘args-out-of-range’ error is signaled if START indicates a
character following END, or if either integer is out of range for
STRING.
Contrast this function with ‘buffer-substring’ (Buffer
Contents), which returns a string containing a portion of the
text in the current buffer. The beginning of a string is at index
0, but the beginning of a buffer is at index 1.
-- Function: substring-no-properties string &optional start end
This works like ‘substring’ but discards all text properties from
the value. Also, START may be omitted or ‘nil’, which is
equivalent to 0. Thus, ‘(substring-no-properties STRING)’ returns
a copy of STRING, with all text properties removed.
-- Function: concat &rest sequences
This function returns a new string consisting of the characters in
the arguments passed to it (along with their text properties, if
any). The arguments may be strings, lists of numbers, or vectors
of numbers; they are not themselves changed. If ‘concat’ receives
no arguments, it returns an empty string.
(concat "abc" "-def")
⇒ "abc-def"
(concat "abc" (list 120 121) [122])
⇒ "abcxyz"
;; ‘nil’ is an empty sequence.
(concat "abc" nil "-def")
⇒ "abc-def"
(concat "The " "quick brown " "fox.")
⇒ "The quick brown fox."
(concat)
⇒ ""
This function always constructs a new string that is not ‘eq’ to
any existing string, except when the result is the empty string (to
save space, Emacs makes only one empty multibyte string).
For information about other concatenation functions, see the
description of ‘mapconcat’ in Mapping Functions, ‘vconcat’
DONTPRINTYET in Vector Functions, and ‘append’ in *noteBuilding
DONTPRINTYET in Vector Functions, and ‘append’ in Building
Lists. For concatenating individual command-line arguments into
a string to be used as a shell command, see
combine-and-quote-strings Shell Arguments.
-- Function: split-string string &optional separators omit-nulls trim
This function splits STRING into substrings based on the regular
expression SEPARATORS (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.
If you need to split a string into a list of individual
command-line arguments suitable for ‘call-process’ or
‘start-process’, see split-string-and-unquote Shell
Arguments.
-- Variable: split-string-default-separators
The default value of SEPARATORS for ‘split-string’. Its usual
value is ‘"[ \f\t\n\r\v]+"’.
Info Catalog
elisp: Predicates for Strings
elisp: Strings and Characters
elisp: Modifying Strings