Behavior of Addr# literals is not documented in the user manual

The GHC user manual includes this description of Addr# literals:

> `"foo"#` has type `Addr#`

That's the extent of the documentation. It should be mentioned that text is encoded with Modified UTF-8. Also, I am not even sure what happens to a string like "hello\x00world"#. Is it treated any differently than "hello\NULworld"#. I haven't checked, but the manual should document what byte sequences these correspond to.

added Tfeature request label

added documentation label

I'm new to GHC internals, so correct me if wrong...

1. Addr# literals are called "primitive string literals" in GHC error message, and "unboxed string literals" in bytestring's document.
2. The content is not encoded in any way.
   1. You can embed a NUL in the literal: "\2\0\1\9"# points to the bytes [2,0,1,9] (with an extra NUL at end).
   2. You can only embed a single-byte character; for example, "α"# is invalid (the error message is primitive string literal must contain only characters <= '\xFF')
3. There will be an extra NUL at the end, like C strings.

Modified UTF-8 encoding is used to encode String literals into primitive string literals: An ASCII string like "hello" will be translated into unpackCString# "hello"#, and a string that contains a NUL or a Unicode character like "hello\NULworld😀" is translated into unpackCStringUtf8# "hello\xC0\x80world\xF0\x9F\x98\x80"#.

I would love this to be better documented in the user manual. Tnanks for making a start.

mentioned in merge request !13220 (closed)

assigned to @aratamizuki

mentioned in commit 4fcd96b0

mentioned in commit 6729566d

mentioned in commit 82b09fc9

mentioned in commit 3f45e68e

mentioned in commit 2b6ba52f

mentioned in commit 8f238895

closed with commit 0a4da5d2

mentioned in commit 0a4da5d2