mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2025-02-08 20:58:58 +00:00
Code Issues Releases Activity

Update documentation of 'aset' and 'store-substring'

Browse Source 
* 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)
This commit is contained in:
Eli Zaretskii 2022-06-05 11:28:10 +03:00
parent 1b8719835a
commit 3ea9357d10
1 changed files with 18 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
doc/lispref/strings.texi
View File

@ -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.
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 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}.
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