bug#55777: [PATCH] Improve documentation of `string-to-multibyte', `string-to-unibyte'

[Richard Hansen]

On 6/3/22 03:02, Eli Zaretskii wrote:
> Thanks, but please explain the motivation for these changes.

The motivation is in the commit message, which I revised in the
attached patch to hopefully make it more clear.

> In particular, why would we need to describe in a doc string such 
> intimate details of our current implementation?
There is a fair amount of implementation detail right now; the patch
doesn't significantly change that. But I revised the patch to remove
some of the detail.

> If there was some situation where you needed these details for some 
> Lisp program, please describe that situation.
I'm trying to understand some inconsistent behavior I'm observing
while writing code to process binary data, and I found the existing
documentation lacking.

    ;; Unibyte vs. multibyte characters:
    (eq ?\xff ?\x3fffff)                           ; t (ok)
    (eq (aref "\x3fffff" 0) (aref "\xff" 0))       ; t (ok)
    (eq (aref "\x3fffff 😀" 0) (aref "\xff 😀" 0)) ; t (ok)
    (eq (aref "\xff" 0) (aref "\xff 😀" 0))        ; nil (expected t)

    ;; Unibyte vs. multibyte strings:
    (multibyte-string-p "\xff")                    ; nil (ok)
    (multibyte-string-p "\x3fffff")                ; nil (ok???)
    (string= "\xff" (string-to-multibyte "\xff"))  ; nil (expected t)

    ;; Char code vs. Unicode codepoint:
    (string= "😀\xff" "😀\x3fffff")                ; t (ok)
    (string= "😀\N{U+ff}" "😀\xff")                ; nil (ok)
    (string= "😀\N{U+ff}" "😀\x3fffff")            ; nil (ok)
    (string= "😀ÿ" "😀\N{U+ff}")                   ; t (ok)
    (string= "😀ÿ" "😀\xff")                       ; nil (ok)
    (string= "😀ÿ" "😀\x3fffff")                   ; nil (ok)
    (eq ?\N{U+ff} ?\xff)                           ; t (expected nil)
    (eq ?\N{U+ff} ?\x3fffff)                       ; t (expected nil)
    (eq ?ÿ ?\xff)                                  ; t (expected nil)
    (eq ?ÿ ?\x3fffff)                              ; t (expected nil)

0001-Improve-documentation-of-string-to-multibyte-string-.patch
Description: Text Data

OpenPGP_signature
Description: OpenPGP digital signature