Subject: bug#6576: documentation `string-to-char' is incorrect

From: Eli Zaretskii <[email-masked]>
Date: Wed, 07 Jul 2010 13:31:27 +0300

> From: Andreas Schwab <[email-masked]>
> Cc: MON KEY <[email-masked]>,  [email-masked]
> Date: Wed, 07 Jul 2010 10:40:00 +0200
> 
> Eli Zaretskii <[email-masked]> writes:
> 
> >   "Return the Unicode codepoint of the first character of STRING.
> 
> This is not correct.  The value is just the internal encoding of the
> character.

Which is Unicode, AFAIK.  The note takes care of the extension that
is specific to Emacs.  If there are other extensions that I forgot, we
can add more notes.

> It's identical to (aref STRING 0)

I don't think talking about `(aref STRING 0)' in a doc string is a
good idea.  Only people who know quite a lot about the internal
representation and what aref does in this case will understand such a
documentation.

> except that it returns 0 for the empty string

This fact should probably be mentioned in the doc string.

> >   Note: eight-bit characters are returned as single-byte values in the
> >   range 160 to 255, inclusive."
> 
> That depends on the multibyteness of the string.

Eight-bit characters are defined as such only in multibyte strings.

But I think the note is correct for unibyte strings as well, because
they by definition include raw bytes.