emscripten-core / emscripten-core/emscripten

Document the return value of intArrayFromString() better

Open
#24,633 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
27.6k
Forks
3.6k
Avg merge
1d 1h
Merged PRs (30d)
105

Description

The online documentation of `intArrayFromString()` does not explain the content of the returned array, so the user must guess or test it out (and is not sure whether the result is stable for next versions).

Sensible results:

Array of
* UTF-8 unsigned values (0…0xFF)
* UTF-8 signed values (0…127 for ASCII, negative values for two-, three-, four-octet sequences)
* UTF-16 unsigned values (0…0xFFFF)
* UTF-16 signed … oh please, no!
* UTF-32 unsigned values (0…0x10FFF)
* something else

If the result are UTF-8 values: When the string UTF-16 contains surrogate pairs: are they converted correctly or is something crazy like CESU-8 is used?

Btw. it is confusing that all the other conversion functions are named _source_`to`_target_ (e.g. `stringToUtf8()`, `Utf8ToString()` but here it is a "from" in the name. Why? Maybe the documentation should mentioned it, too, what's the reason for the different naming scheme here.

I guess there is a difference to the existing `StringToUTF…()` functions, but the difference is not shown clearly.

Moreover: I found a *lot* of questionable or just wrong usages of this function in the web, so better documentation seems necessary not only for me. ;-(

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.