43.4 Inserting Text

Insertion means adding new text to a buffer. The inserted text goes at point—between the character before point and the character after point.

Insertion relocates markers that point at positions after the insertion point, so that they stay with the surrounding text (see Markers). When a marker points at the place of insertion, insertion normally doesn’t relocate the marker, so that it points to the beginning of the inserted text; however, certain special functions such as insert-before-markers relocate such markers to point after the inserted text.

Some insertion functions leave point before the inserted text, while other functions leave it after. We call the former insertion after point and the latter insertion before point.

If a string with non-nil extent data is inserted, the remembered extents will also be inserted. See Duplicable Extents.

Insertion functions signal an error if the current buffer is read-only.

These functions copy text characters from strings and buffers along with their properties. The inserted characters have exactly the same properties as the characters they were copied from. By contrast, characters specified as separate arguments, not part of a string or buffer, inherit their text properties from the neighboring text.

Function: insert &rest args

This function inserts the strings and/or characters args into the current buffer, at point, moving point forward. In other words, it inserts the text before point. An error is signaled unless all args are either strings or characters. The value is nil.

Function: insert-before-markers &rest args

This function inserts the strings and/or characters args into the current buffer, at point, moving point forward. An error is signaled unless all args are either strings or characters. The value is nil.

This function is unlike the other insertion functions in that it relocates markers initially pointing at the insertion point, to point after the inserted text.

Function: insert-string string &optional buffer

This function inserts string into buffer before point. buffer defaults to the current buffer if omitted. This function is chiefly useful if you want to insert a string in a buffer other than the current one (otherwise you could just use insert).

Function: insert-char character &optional count ignored buffer

This function inserts count instances of character into buffer before point. count must be a number, and character must be a character.

If optional argument buffer is nil, the current buffer is assumed. In FSF Emacs, the third argument is called inherit and refers to text properties. In SXEmacs and XEmacs, it is always ignored.

This function always returns nil.

Function: insert-buffer-substring from-buffer-or-name &optional start end

This function inserts a portion of buffer from-buffer-or-name (which must already exist) into the current buffer before point. The text inserted is the region from start and end. (These arguments default to the beginning and end of the accessible portion of that buffer.) This function returns nil.

In this example, the form is executed with buffer ‘bar’ as the current buffer. We assume that buffer ‘bar’ is initially empty.

---------- Buffer: foo ----------
We hold these truths to be self-evident, that all
---------- Buffer: foo ----------

(insert-buffer-substring "foo" 1 20)
     ⇒ nil

---------- Buffer: bar ----------
We hold these truth∗
---------- Buffer: bar ----------