gnu.org (original) (raw)

4.3 Creating Strings

The following functions create strings, either from scratch, or by putting strings together, or by taking them apart. (For functions that create strings based on the modified contents of other strings, like string-replace and replace-regexp-in-string, seeSearch and Replace.)

Function: make-string count character &optional multibyte ¶

This function returns a string made up of count repetitions ofcharacter. If count is negative, an error is signaled.

(make-string 5 ?x) ⇒ "xxxxx" (make-string 0 ?x) ⇒ ""

Normally, if character is an ASCII character, the result is a unibyte string. But if the optional argumentmultibyte is non-nil, the function will produce a multibyte string instead. This is useful when you later need to concatenate the result with non-ASCII strings or replace some of its characters with non-ASCII characters.

Other functions to compare with this one include make-vector(see Vectors) and make-list (see Building Cons Cells and 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 indexend. 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 (see Sequences).

If the characters copied from string have text properties, the properties are copied into the new string also. See 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. Anargs-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 (see Examining 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 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 does not always allocate a new string. Callers are advised not rely on the result being a new string nor on it beingeq to an existing string.

In particular, mutating the returned value may inadvertently change another string, alter a constant string in the program, or even raise an error. To obtain a string that you can safely mutate, usecopy-sequence on the result.

For information about other concatenation functions, see the description of mapconcat in Mapping Functions,vconcat in Functions for Vectors, and append in Building Cons Cells and Lists. For concatenating individual command-line arguments into a string to be used as a shell command, see combine-and-quote-strings.

Function: split-string string &optional separators omit-nulls trim ¶

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 separators is nil (or omitted), the default is the value of split-string-default-separators and the function behaves as if omit-nulls were t.

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

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.

Examples:

(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 forseparators:

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

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

Variable: split-string-default-separators ¶

The default value of separators for split-string. Its usual value is "[ \f\t\n\r\v]+".

Function: string-clean-whitespace string ¶

Clean up the whitespace in string by collapsing stretches of whitespace to a single space character, as well as removing all whitespace from the start and the end of string.

Function: string-trim-left string &optional regexp ¶

Remove the leading text that matches regexp from string.regexp defaults to ‘[ \t\n\r]+’.

Function: string-trim-right string &optional regexp ¶

Remove the trailing text that matches regexp from string.regexp defaults to ‘[ \t\n\r]+’.

Function: string-trim string &optional trim-left trim-right ¶

Remove the leading text that matches trim-left and trailing text that matches trim-right from string. Both regexps default to ‘[ \t\n\r]+’.

Function: string-fill string width ¶

Attempt to Word-wrap string so that it displays with lines no wider than width. Filling is done on whitespace boundaries only. If there are individual words that are longer than width, these will not be shortened, and therefore string might be shown with lines wider than width in that case.

Function: string-limit string length &optional end coding-system ¶

If string is shorter than length characters, stringis returned as is. Otherwise, return a substring of stringconsisting of the first length characters. If the optionalend parameter is given, return a string of the length last characters instead.

If coding-system is non-nil, string will be encoded before limiting, and the result will be a unibyte string that’s shorter than length bytes. If string contains characters that are encoded into several bytes (for instance, when usingutf-8), the resulting unibyte string is never truncated in the middle of a character representation.

This function measures the string length in characters or bytes, and thus is generally inappropriate if you need to shorten strings for display purposes; use truncate-string-to-width orwindow-text-pixel-size or string-glyph-split instead (see Size of Displayed Text).

Function: string-lines string &optional omit-nulls keep-newlines ¶

Split string into a list of strings on newline boundaries. If the optional argument omit-nulls is non-nil, remove empty lines from the results. If the optional argument keep-newlinesis non-nil, don’t remove the trailing newlines from the result strings.

Function: string-pad string length &optional padding start ¶

Pad string to be of the given length using paddingas the padding character. padding defaults to the space character. If string is longer than length, no padding is done. If start is nil or omitted, the padding is appended to the characters of string, and if it’s non-nil, the padding is prepended to string’s characters.

Function: string-chop-newline string ¶

Remove the final newline, if any, from string.