diff options
Diffstat (limited to 'devdocs/elisp/replacing.html')
| -rw-r--r-- | devdocs/elisp/replacing.html | 14 |
1 files changed, 14 insertions, 0 deletions
diff --git a/devdocs/elisp/replacing.html b/devdocs/elisp/replacing.html new file mode 100644 index 00000000..e3c361a9 --- /dev/null +++ b/devdocs/elisp/replacing.html @@ -0,0 +1,14 @@ + <h3 class="section">Replacing Buffer Text</h3> <p>You can use the following function to replace the text of one buffer with the text of another buffer: </p> <dl> <dt id="replace-buffer-contents">Command: <strong>replace-buffer-contents</strong> <em>source &optional max-secs max-costs</em> +</dt> <dd> +<p>This function replaces the accessible portion of the current buffer with the accessible portion of the buffer <var>source</var>. <var>source</var> may either be a buffer object or the name of a buffer. When <code>replace-buffer-contents</code> succeeds, the text of the accessible portion of the current buffer will be equal to the text of the accessible portion of the <var>source</var> buffer. </p> <p>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 <code>delete-region</code> and <code>insert-buffer-substring</code> would destroy these properties. However, the latter combination is typically faster (See <a href="deletion">Deletion</a>, and <a href="insertion">Insertion</a>). </p> <p>For its working, <code>replace-buffer-contents</code> needs to compare the contents of the original buffer with that of <var>source</var> which is a costly operation if the buffers are huge and there is a high number of differences between them. In order to keep <code>replace-buffer-contents</code>’s runtime in bounds, it has two optional arguments. </p> <p><var>max-secs</var> defines a hard boundary in terms of seconds. If given and exceeded, it will fall back to <code>delete-region</code> and <code>insert-buffer-substring</code>. </p> <p><var>max-costs</var> 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. </p> <p><code>replace-buffer-contents</code> returns t if a non-destructive replacement could be performed. Otherwise, i.e., if <var>max-secs</var> was exceeded, it returns nil. </p> +</dd> +</dl> <dl> <dt id="replace-region-contents">Function: <strong>replace-region-contents</strong> <em>beg end replace-fn &optional max-secs max-costs</em> +</dt> <dd> +<p>This function replaces the region between <var>beg</var> and <var>end</var> using the given <var>replace-fn</var>. The function <var>replace-fn</var> is run in the current buffer narrowed to the specified region and it should return either a string or a buffer replacing the region. </p> <p>The replacement is performed using <code>replace-buffer-contents</code> (see above) which also describes the <var>max-secs</var> and <var>max-costs</var> arguments and the return value. </p> <p>Note: If the replacement is a string, it will be placed in a temporary buffer so that <code>replace-buffer-contents</code> 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 <code>buffer-substring</code> or similar. </p> +</dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Replacing.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Replacing.html</a> + </p> +</div> |