TextEncoder: encodeInto() Methode

Syntax

encodeInto(string, uint8Array)

Parameter

string

Ein String, der den zu kodierenden Text enthlt.

uint8Array

Eine Uint8Array-Objektinstanz, in die der resultierende UTF-8 kodierte Text eingefgt wird.

Rckgabewert

Ein Objekt, das zwei Mitglieder enthlt:

read

Die Anzahl der UTF-16 Code-Einheiten aus der Quelle, die in UTF-8 umgewandelt wurden. Dies kann kleiner als string.length sein, wenn uint8Array nicht gengend Platz hatte.

written

Die Anzahl der modifizierten Bytes im Ziel-Uint8Array. Die geschriebenen Bytes bilden garantiert vollstndige UTF-8-Bytesequenzen.

In eine bestimmte Position kodieren

encodeInto() legt seine Ausgabe immer am Anfang des Arrays ab. Es ist jedoch manchmal ntzlich, die Ausgabe an einem bestimmten Index zu starten. Die Lsung ist TypedArray.prototype.subarray():

const encoder = new TextEncoder();

function encodeIntoAtPosition(string, u8array, position) {
  return encoder.encodeInto(
    string,
    position ? u8array.subarray(position | 0) : u8array,
  );
}

const u8array = new Uint8Array(8);
encodeIntoAtPosition("hello", u8array, 2);
console.log(u8array.join()); // 0,0,104,101,108,108,111,0

Puffergre

Um einen JavaScript-String s zu konvertieren, darf der fr die vollstndige Konvertierung bentigte Ausgabespeicher nie kleiner als s.length Bytes und nie grer als s.length * 3 Bytes sein. Das genaue UTF-8-zu-UTF-16-Lngenverhltnis fr Ihren String hngt von der Sprache ab, mit der Sie arbeiten:

• Fr einfachen englischen Text, der hauptschlich ASCII-Zeichen verwendet, liegt das Verhltnis nahe bei 1.
• Fr Texte in Schriftsystemen, die Zeichen von U+0080 bis U+07FF verwenden, darunter Griechisch, Kyrillisch, Hebrisch, Arabisch etc., liegt das Verhltnis bei etwa 2.
• Fr Texte in Schriftsystemen, die Zeichen von U+0800 bis U+FFFF verwenden, darunter Chinesisch, Japanisch, Koreanisch etc., betrgt das Verhltnis etwa 3.
• Es ist nicht blich, dass ganze Schriftsysteme in Nicht-BMP-Zeichen geschrieben werden (obwohl sie existieren). Diese Zeichen sind normalerweise mathematische Symbole, Emojis, historische Schriften etc. Das Verhltnis fr diese Zeichen betrgt 2, da sie 4 Bytes in UTF-8 und 2 in UTF-16 bentigen.

Wenn die Ausgabezuordnung (typischerweise innerhalb des Wasm-Speicherbereichs) voraussichtlich kurzlebig ist, ist es sinnvoll, s.length * 3 Bytes fr die Ausgabe zu reservieren, in diesem Fall ist der erste Umwandlungsversuch garantiert, den ganzen String zu konvertieren.

Wenn Ihr Text hauptschlich Englisch ist, ist es unwahrscheinlich, dass langer Text die Lnge von s.length * 2 Bytes berschreitet. Daher knnte ein optimistischerer Ansatz darin bestehen, s.length * 2 + 5 Bytes zu reservieren und bei der seltenen Gelegenheit, dass die optimistische Vorhersage falsch war, eine Neuzuordnung durchzufhren.

Wenn die Ausgabe voraussichtlich langlebig ist, wre es sinnvoll, eine minimale Zuordnung roundUpToBucketSize(s.length), die maximale Zuordnungsgre s.length * 3 zu berechnen und einen (als Kompromiss zwischen Speicherverbrauch und Geschwindigkeit) Schwellenwert t zu haben, sodass Sie, wenn roundUpToBucketSize(s.length) + t >= s.length * 3, fr s.length * 3 reservieren. Andernfalls reservieren Sie zunchst fr roundUpToBucketSize(s.length) und konvertieren. Falls der read-Eintrag im Rckgabewrterbuch s.length betrgt, ist die Konvertierung abgeschlossen. Falls nicht, reservieren Sie den Zielpuffer fr written + (s.length - read) * 3 neu und konvertieren dann den Rest, indem Sie einen Teilstring von s ab dem Index read und einen Teilpuffer des Zielpuffers ab dem Index written verwenden.

Oben ist roundUpToBucketSize(), eine Funktion, die auf die Bucket-Gre des Allokators aufrundet. Wenn beispielsweise Ihr Wasm-Allokator bekannt ist, Potenzen von zwei zu verwenden, sollte roundUpToBucketSize() das Argument zurckgeben, wenn es eine Potenz von zwei ist oder die nchste Potenz von zwei andernfalls. Wenn das Verhalten des Wasm-Allokators unbekannt ist, sollte roundUpToBucketSize() eine Identittsfunktion sein.

Wenn das Verhalten Ihres Allokators unbekannt ist, mchten Sie mglicherweise bis zu zwei Neuzuordnungsschritte haben und den ersten Neuzuordnungsschritt die restliche unkonvertierte Lnge mal zwei anstelle von drei multiplizieren lassen. In diesem Fall macht es jedoch Sinn, das bliche Multiplizieren mit zwei der bereits geschriebenen Pufferspeicherlnge nicht zu implementieren, denn wenn eine zweite Neuzuweisung stattgefunden hat, wrde sie im Vergleich zur ursprnglichen Lnge mal drei stets berallokieren. Der obige Rat setzt voraus, dass Sie keinen Speicherplatz fr ein Null-Terminierungszeichen bentigen. Das bedeutet, dass auf der Wasm-Seite mit Rust-Strings oder einer nicht-nullterminierenden C++-Klasse gearbeitet wird. Wenn Sie mit C++ std::string arbeiten, mssen Sie, auch wenn die logische Lnge angezeigt wird, das zustzliche Terminierungsbyte bercksichtigen, wenn Sie das Aufrunden zur Bucket-Gre des Allokators berechnen. Siehe den nchsten Abschnitt ber C-Strings.

Keine Null-Terminierung

Wenn der Eingabestring das Zeichen U+0000 enthlt, wird encodeInto() ein 0x00-Byte in der Ausgabe schreiben. encodeInto() schreibt nicht ein C-hnliches 0x00-Sentinel-Byte nach der logischen Ausgabe.

Wenn Ihr Wasm-Programm C-Strings verwendet, liegt es in Ihrer Verantwortung, das 0x00-Sentinel zu schreiben, und Sie knnen nicht verhindern, dass Ihr Wasm-Programm einen logisch abgeschnittenen String sieht, wenn der JavaScript-String U+0000 enthielt. Beobachten Sie:

const encoder = new TextEncoder();

function encodeIntoWithSentinel(string, u8array, position) {
  const stats = encoder.encodeInto(
    string,
    position ? u8array.subarray(position | 0) : u8array,
  );
  if (stats.written < u8array.length) u8array[stats.written] = 0; // append null if room
  return stats;
}

Beispiele

Kodierung in einen Puffer

<p class="source">This is a sample paragraph.</p>
<p class="result"></p>

const sourcePara = document.querySelector(".source");
const resultPara = document.querySelector(".result");
const string = sourcePara.textContent;

const textEncoder = new TextEncoder();
const utf8 = new Uint8Array(string.length);

const encodedResults = textEncoder.encodeInto(string, utf8);
resultPara.textContent +=
  `Bytes read: ${encodedResults.read}` +
  ` | Bytes written: ${encodedResults.written}` +
  ` | Encoded result: ${utf8}`;

Spezifikationen

Browser-Kompatibilitt

Siehe auch

• Das TextEncoder-Interface, zu dem es gehrt.
• TextEncoder.encode()