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"

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 Sequence Functions).

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. 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.