32.23 Replacing Buffer Text

You can use the following function to replace the text of one buffer with the text of another buffer:

command replace-buffer-contents source \&optional max-secs max-costs

This function replaces the accessible portion of the current buffer with the accessible portion of the buffer source. source may either be a buffer object or the name of a buffer. When replace-buffer-contents succeeds, the text of the accessible portion of the current buffer will be equal to the text of the accessible portion of the source buffer.

This function attempts to keep point, markers, text properties, and overlays in the current buffer intact. One potential case where this behavior is useful is external code formatting programs: they typically write the reformatted text into a temporary buffer or file, and using delete-region and insert-buffer-substring would destroy these properties. However, the latter combination is typically faster (See Deletion, and Insertion).

For its working, replace-buffer-contents needs to compare the contents of the original buffer with that of source which is a costly operation if the buffers are huge and there is a high number of differences between them. In order to keep replace-buffer-contents’s runtime in bounds, it has two optional arguments.

max-secs defines a hard boundary in terms of seconds. If given and exceeded, it will fall back to delete-region and insert-buffer-substring.

max-costs defines the quality of the difference computation. If the actual costs exceed this limit, heuristics are used to provide a faster but suboptimal solution. The default value is 1000000.

replace-buffer-contents returns t if a non-destructive replacement could be performed. Otherwise, i.e., if max-secs was exceeded, it returns nil.

function replace-region-contents beg end replace-fn \&optional max-secs max-costs

This function replaces the region between beg and end using the given replace-fn. The function replace-fn is run in the current buffer narrowed to the specified region and it should return either a string or a buffer replacing the region.

The replacement is performed using replace-buffer-contents (see above) which also describes the max-secs and max-costs arguments and the return value.

Note: If the replacement is a string, it will be placed in a temporary buffer so that replace-buffer-contents can operate on it. Therefore, if you already have the replacement in a buffer, it makes no sense to convert it to a string using buffer-substring or similar.