procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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}. described in this section. @xref{Mutability}.
The most basic way to alter the contents of an existing string is with The most basic way to alter the contents of an existing string is with
@code{aset} (@pxref{Array Functions}). @code{(aset @var{string} @code{aset} (@pxref{Array Functions}). @w{@code{(aset @var{string}
@var{idx} @var{char})} stores @var{char} into @var{string} at index @var{idx} @var{char})}} stores @var{char} into @var{string} at character
@var{idx}. Each character occupies one or more bytes, and if @var{char} index @var{idx}. It will automatically convert a pure-@acronym{ASCII}
needs a different number of bytes from the character already present at @var{string} to a multibyte string (@pxref{Text Representations}) if
that index, @code{aset} signals an error. 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}: A more powerful function is @code{store-substring}:
@defun store-substring string idx obj @defun store-substring string idx obj
This function alters part of the contents of the string @var{string}, by This function alters part of the contents of the specified @var{string},
storing @var{obj} starting at index @var{idx}. The argument @var{obj} by storing @var{obj} starting at character index @var{idx}. The
may be either a character or a (smaller) string. 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 Since it is impossible to change the number of characters in an
an error if @var{obj} doesn't fit within @var{string}'s actual length, existing string, it is en error if @var{obj} consists of more
or if any new character requires a different number of bytes from the characters than would fit in @var{string} starting at character index
character currently present at that point in @var{string}. @var{idx}.
@end defun @end defun
To clear out a string that contained a password, use To clear out a string that contained a password, use