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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 55801 in the body.
You can then email your comments to 55801 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Richard Hansen <rhansen <at> rhansen.org>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Fix documentation of `aset' on strings, `store-substring'
Date: Sat, 4 Jun 2022 23:30:29 -0400

[Message part 1 (text/plain, inline)]

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.

[0001-Fix-documentation-of-aset-on-strings-store-substring.patch (text/x-patch, attachment)]

[OpenPGP_signature (application/pgp-signature, attachment)]

Message #8 received at 55801 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Richard Hansen <rhansen <at> rhansen.org>
Cc: 55801 <at> debbugs.gnu.org
Subject: Re: bug#55801: [PATCH] Fix documentation of `aset' on strings,
 `store-substring'
Date: Sun, 05 Jun 2022 11:30:00 +0300

> Date: Sat, 4 Jun 2022 23:30:29 -0400
> From: Richard Hansen <rhansen <at> 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

Message #13 received at 55801-done <at> debbugs.gnu.org (full text, mbox):

From: Richard Hansen <rhansen <at> rhansen.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 55801-done <at> debbugs.gnu.org
Subject: Re: bug#55801: [PATCH] Fix documentation of `aset' on strings,
 `store-substring'
Date: Sun, 5 Jun 2022 15:22:24 -0400

Thanks!

Message #16 received at 55801 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Richard Hansen <rhansen <at> rhansen.org>
Cc: 55801 <at> debbugs.gnu.org
Subject: Re: bug#55801: [PATCH] Fix documentation of `aset' on strings,
 `store-substring'
Date: Sun, 05 Jun 2022 22:27:46 +0300

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

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.