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