From bdf716bba197f41d25be41b08ca2003f72fe70c0 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Mattias=20Engdeg=C3=A5rd?= Date: Thu, 9 Jul 2020 17:32:13 +0200 Subject: [PATCH] Correct 'concat' manual entry (bug#42296) * doc/lispref/strings.texi (Creating Strings): 'concat' does not necessarily return a newly allocated string. This has been the case at least since 1997 (Emacs 20.3). --- doc/lispref/strings.texi | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 4a7bda57c4e..0dc47f30c43 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -248,7 +248,7 @@ properties removed. @defun concat &rest sequences @cindex copying strings @cindex concatenating strings -This function returns a new string consisting of the characters in the +This function returns a string consisting of the characters in the arguments passed to it (along with their text properties, if any). The arguments may be strings, lists of numbers, or vectors of numbers; they are not themselves changed. If @code{concat} receives no arguments, it @@ -269,9 +269,14 @@ returns an empty string. @end example @noindent -This function always constructs a new string that is not @code{eq} to -any existing string, except when the result is the empty string (to -save space, Emacs makes only one empty multibyte string). +This function does not always allocate a new string. Callers are +advised not rely on the result being a new string nor on it being +@code{eq} to an existing string. + +In particular, mutating the returned value may inadvertently change +another string, alter a constant string in the program, or even raise +an error. To obtain a string that you can safely mutate, use +@code{copy-sequence} on the result. For information about other concatenation functions, see the description of @code{mapconcat} in @ref{Mapping Functions}, -- 2.39.2