32.8.3 Functions for Yanking

Yanking means reinserting an entry of previously killed text from the kill ring. The text properties are copied too.

Command: yank &optional arg

This command inserts before point the text in the first entry in the kill ring. It positions the mark at the beginning of that text, and point at the end.

If arg is a list (which occurs interactively when the user types C-u with no digits), then yank inserts the text as described above, but puts point before the yanked text and puts the mark after it.

If arg is a number, then yank inserts the argth most recently killed text--the argth element of the kill ring list.

yank does not alter the contents of the kill ring or rotate it. It returns nil.

Command: yank-pop arg

This command replaces the just-yanked entry from the kill ring with a different entry from the kill ring.

This is allowed only immediately after a yank or another yank-pop. At such a time, the region contains text that was just inserted by yanking. yank-pop deletes that text and inserts in its place a different piece of killed text. It does not add the deleted text to the kill ring, since it is already in the kill ring somewhere.

If arg is nil, then the replacement text is the previous element of the kill ring. If arg is numeric, the replacement is the argth previous kill. If arg is negative, a more recent kill is the replacement.

The sequence of kills in the kill ring wraps around, so that after the oldest one comes the newest one, and before the newest one goes the oldest.

The return value is always nil.