bug#55801: [PATCH] Fix documentation of `aset' on strings, `store-substring'

bug#55801: [PATCH] Fix documentation of `aset' on strings, `store-substring'

[Richard Hansen]

[-- Attachment #1.1.1: Type: text/plain, Size: 218 bytes --]

See attached patch:

* doc/lispref/strings.texi (Modifying Strings): `aref` and
`store-substring` automatically convert the string to multibyte if
necessary, and support characters with different sized encodings.

[-- Attachment #1.1.2: 0001-Fix-documentation-of-aset-on-strings-store-substring.patch --]
[-- Type: text/x-patch, Size: 1987 bytes --]

From 64c0d992e4ca5b820a87b6bcd3efc60cf266d2a4 Mon Sep 17 00:00:00 2001
From: Richard Hansen <rhansen@rhansen.org>
Date: Sat, 4 Jun 2022 23:25:11 -0400
Subject: [PATCH] Fix documentation of `aset' on strings, `store-substring'

* doc/lispref/strings.texi (Modifying Strings): `aref` and
`store-substring` automatically convert the string to multibyte if
necessary, and support characters with different sized encodings.
---
 doc/lispref/strings.texi | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 413e17750e..82bed43e4e 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -466,9 +466,11 @@ Modifying Strings
   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.
+@var{idx}.  Unibyte strings are converted to multibyte if necessary
+(@pxref{Text Representations}).  If the size of the internal encoding
+of @var{char} differs from that of the character already present at
+@var{idx}, the string's representation is adjusted to accommodate the
+change.
 
   A more powerful function is @code{store-substring}:
 
@@ -478,9 +480,7 @@ Modifying Strings
 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}.
+an error if @var{obj} doesn't fit within @var{string}'s actual length.
 @end defun
 
   To clear out a string that contained a password, use
-- 
2.36.1


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

bug#55801: [PATCH] Fix documentation of `aset' on strings, `store-substring'

[Eli Zaretskii]

> Date: Sat, 4 Jun 2022 23:30:29 -0400
> From: Richard Hansen <rhansen@rhansen.org>
> 
> See attached patch:
> 
> * doc/lispref/strings.texi (Modifying Strings): `aref` and
> `store-substring` automatically convert the string to multibyte if
> necessary, and support characters with different sized encodings.

Thanks.

I installed the following modified version, which I think is more
accurate (e.g., "length" and "index" can be ambiguous when talking
about Lisp strings), and also includes some practical advice that can
avoid some unibyte-vs-multibyte pitfalls and surprises with these
functions:

    The most basic way to alter the contents of an existing string is with
  @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 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

bug#55801: [PATCH] Fix documentation of `aset' on strings, `store-substring'

[Richard Hansen]

Thanks!

bug#55801: [PATCH] Fix documentation of `aset' on strings, `store-substring'

[Eli Zaretskii]

> Date: Sun, 5 Jun 2022 15:22:24 -0400
> Cc: 55801-done@debbugs.gnu.org
> From: Richard Hansen <rhansen@rhansen.org>
> 
> Thanks!

You are welcome, and thanks for noticing the outdated info.