From 3ea9357d109e303fece9d49e1fdad8a2e42cc858 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 5 Jun 2022 11:28:10 +0300 Subject: [PATCH] Update documentation of 'aset' and 'store-substring' * doc/lispref/strings.texi (Modifying Strings): Adjust to implementation changes: it is possible for the modified string to have fewer or more bytes than the original. Add recommendations regarding unibyte vs multibyte strings and characters. (Bug#55801) --- doc/lispref/strings.texi | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 742ab76244d..c9612e598a3 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -461,23 +461,29 @@ Remove the final newline, if any, from @var{string}. described in this section. @xref{Mutability}. The most basic way to alter the contents of an existing string is with -@code{aset} (@pxref{Array Functions}). @code{(aset @var{string} -@var{idx} @var{char})} stores @var{char} into @var{string} at index -@var{idx}. Each character occupies one or more bytes, and if @var{char} -needs a different number of bytes from the character already present at -that index, @code{aset} signals an error. +@code{aset} (@pxref{Array Functions}). @w{@code{(aset @var{string} +@var{idx} @var{char})}} stores @var{char} into @var{string} at character +index @var{idx}. It will automatically convert a pure-@acronym{ASCII} +@var{string} to a multibyte string (@pxref{Text Representations}) if +needed, but we recommend to always make sure @var{string} is multibyte +(e.g., by using @code{string-to-multibyte}, @pxref{Converting +Representations}), if @var{char} is a non-@acronym{ASCII} character, not +a raw byte. A more powerful function is @code{store-substring}: @defun store-substring string idx obj -This function alters part of the contents of the string @var{string}, by -storing @var{obj} starting at index @var{idx}. The argument @var{obj} -may be either a character or a (smaller) string. - -Since it is impossible to change the length of an existing string, it is -an error if @var{obj} doesn't fit within @var{string}'s actual length, -or if any new character requires a different number of bytes from the -character currently present at that point in @var{string}. +This function alters part of the contents of the specified @var{string}, +by storing @var{obj} starting at character index @var{idx}. The +argument @var{obj} may be either a character (in which case the function +behaves exactly as @code{aset}) or a (smaller) string. If @var{obj} +is a multibyte string, we recommend to make sure @var{string} is also +multibyte, even if it's pure-@acronym{ASCII}. + +Since it is impossible to change the number of characters in an +existing string, it is en error if @var{obj} consists of more +characters than would fit in @var{string} starting at character index +@var{idx}. @end defun To clear out a string that contained a password, use -- 2.39.2