10.3 Creating Strings

The following functions create strings, either from scratch, or by putting strings together, or by taking them apart.

Function: string &rest characters

This function returns a new string made up of characters.

(string ?S ?X ?E ?m ?a ?c ?s)
     ⇒ "SXEmacs"
(string)
     ⇒ ""

Analogous functions operating on other data types include list, cons (see Building Lists), vector (see Vectors) and bit-vector (see Bit Vectors). This function has not been available in XEmacs prior to 21.0 and FSF Emacs prior to 20.3.

Function: make-string length character

This function returns a new string consisting entirely of length successive copies of character. length must be a non-negative integer.

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

Other functions to compare with this one include char-to-string (see String Conversion), make-vector (see Vectors), and make-list (see Building Lists).

Function: substring string start &optional 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.

(substring "abcdefg" 0 3)
     ⇒ "abc"

Here the index for ‘a’ is 0, the index for ‘b’ is 1, and the index for ‘c’ is 2. Thus, three letters, ‘abc’, are copied from the string "abcdefg". The index 3 marks the character position up to which the substring is copied. The character whose index is 3 is actually the fourth character in the string.

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 as an index, 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 Sequence Functions).

If the characters copied from string have duplicable extents or text properties, those are copied into the new string also. See Duplicable Extents.

A wrong-type-argument error is signaled if either start or end is not an integer or 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 (see 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: 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 (+ 256 121)) [122])
     ⇒ "abcxyz"
;; nil is an empty sequence.
(concat "abc" nil "-def")
     ⇒ "abc-def"
(concat "The " "quick brown " "fox.")
     ⇒ "The quick brown fox."
(concat)
     ⇒ ""

The second example above shows how characters stored in strings are taken modulo 256. In other words, each character in the string is stored in one byte.

The concat function always constructs a new string that is not eq to any existing string.

When an argument is an integer (not a sequence of integers), it is converted to a string of digits making up the decimal printed representation of the integer. Don’t use this feature; we plan to eliminate it. If you already use this feature, change your programs now! The proper way to convert an integer to a decimal number in this way is with format (see Formatting Strings) or number-to-string (see String Conversion).

(concat 137)
     ⇒ "137"
(concat 54 321)
     ⇒ "54321"

For information about other concatenation functions, see the description of mapconcat in Mapping Functions, vconcat in Vectors, bvconcat in Bit Vectors, and append in Building Lists.