Define encodeInto() API

[annevk]

This enables converting strings into byte sequences of pre-allocated buffers.

Also cleanup TextEncoder a bit.

Tests: ...

Fixes #69.

---

Preview | Diff

[annevk]

The reason this does not contain the StringView dictionary is because it can be added later if there's indeed a need for it. This also does not require any particular destination length as either way out-of-band needs to be dealt with and it seems better to be flexible for simple string use cases that would otherwise have to write completely different code.

[hsivonen]

Looks correct to me, but it took me a moment to realize that the algorithm always loops over all tokens and the loop just does not necessarily write all the output. While an early return might be just an optimization, it might make the algorithm more comprehensible.

[annevk]

Thanks for pointing that out, I think it's actually wrong. Say we had 3 bytes left and the next input required 4 bytes and the input after that 1 byte. This would skip the 4 bytes input and then write the 1 byte one.

[ricea]

Generally looks good. There's a few areas where the wording needs tightening up, as you've noted.

[annevk]

Do you know what the wording for those places should be? IDL doesn't really define any language around IDL ArrayBuffer objects... I guess I can file an issue upstream at least.

Other things:

• Add an example.
• Clarify what read and written represent.
• Maybe clarify why there's no decodeInto().

[inexorabletash]

I think this is implied by your last comment, but just to confirm: as written, destination's view bounds (offset, length) onto its ArrayBuffer is seemingly ignored by the current algorithm. i.e. in this case:

const ab = new ArrayBuffer(5);
const ua = new Uint8Array(ab, 1, 2);
new TextEncoder().encodeInto("ABCDE", ua);

... I would expect ab to end up as [0, 65, 66, 0, 0].

(I don't see test cases for this either)

[annevk]

Yeah, that clearly needs to be worded better. (I added tests.)

[annevk]

I think this is good now apart from the example which I'd like feedback on over at #69 (comment). (And there's a Bikeshed issue I'll resolve with Tab.)

[annevk]

I haven't explained why there's no decodeInto(). I suppose "bytes in encoding X" -> "bytes in UTF-8" could make sense, but let's only add that if there's a request.

Anyone want to do a final review pass? (Tests need one too.)

[annevk]

I'll land this and the tests tomorrow, unless there are further comments.

[annevk]

cc @whatwg/documentation

[annevk]

Implementation bugs:

• https://bugzilla.mozilla.org/show_bug.cgi?id=1514664
• https://bugs.webkit.org/show_bug.cgi?id=193274
• https://bugs.chromium.org/p/chromium/issues/detail?id=920107