diff xml/en/docs/njs/reference.xml @ 2585:7035221dbe37

Documented TextDecoder and TextEncoder in njs Reference.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 13 Aug 2020 21:42:01 +0100
parents cd97adddd757
children 5528961da54d
line wrap: on
line diff
--- a/xml/en/docs/njs/reference.xml
+++ b/xml/en/docs/njs/reference.xml
@@ -9,7 +9,7 @@
 <article name="Reference"
         link="/en/docs/njs/reference.html"
         lang="en"
-        rev="52">
+        rev="53">
 
 <section id="summary">
 
@@ -674,6 +674,155 @@ 4
 </section>
 
 
+<section id="textdecoder" name="Text Decoder">
+
+<para>
+The <literal>TextDecoder</literal>
+produces a stream of code points
+from a stream of bytes
+(<link doc="changes.xml" id="njs0.4.3">0.4.3</link>).
+</para>
+
+<para>
+<list type="tag">
+
+<tag-name><literal>TextDecoder([[<value>encoding</value>],
+<value>options</value>])</literal></tag-name>
+<tag-desc>
+Creates a new <literal>TextDecoder</literal> object
+for specified <literal>encoding</literal>,
+currently, only UTF-8 is supported.
+The <literal>options</literal> is
+<literal>TextDecoderOptions</literal> dictionary with the property:
+
+<list type="tag">
+
+<tag-name><literal>fatal</literal></tag-name>
+<tag-desc>
+boolean flag indicating if
+<link id="textdecoder_decode"><literal>TextDecoder.decode()</literal></link>
+must throw the <value>TypeError</value> exception when
+a coding error is found, by default is <literal>false</literal>.
+</tag-desc>
+
+</list>
+</tag-desc>
+
+<tag-name id="textdecoder_encoding"><literal>TextDecoder.prototype.encoding</literal></tag-name>
+<tag-desc>
+Returns a string with the name of the encoding used by
+<link id="textdecoder"><literal>TextDecoder()</literal></link>,
+read-only.
+</tag-desc>
+
+<tag-name id="textdecoder_fatal"><literal>TextDecoder.prototype.fatal</literal></tag-name>
+<tag-desc>
+boolean flag, <literal>true</literal> if
+the error mode is fatal,
+read-only.
+</tag-desc>
+
+<tag-name id="textdecoder_ignorebom"><literal>TextDecoder.prototype.ignoreBOM</literal></tag-name>
+<tag-desc>
+boolean flag, <literal>true</literal> if
+the byte order marker is ignored,
+read-only.
+</tag-desc>
+
+<tag-name id="textdecoder_decode"><literal>TextDecoder.prototype.decode(<value>buffer</value>,
+[<value>options</value>])</literal></tag-name>
+<tag-desc>
+Returns a string with the text
+decoded from the <literal>buffer</literal> by
+<link id="textdecoder"><literal>TextDecoder()</literal></link>.
+The buffer can be <literal>ArrayBuffer</literal>.
+The <literal>options</literal> is
+<literal>TextDecodeOptions</literal> dictionary with the property:
+
+<list type="tag">
+
+<tag-name><literal>stream</literal></tag-name>
+<tag-desc>
+boolean flag indicating if
+additional data will follow in subsequent calls to <literal>decode()</literal>:
+<literal>true</literal> if processing the data in chunks, and
+<literal>false</literal> for the final chunk
+or if the data is not chunked.
+By default is <literal>false</literal>.
+</tag-desc>
+
+</list>
+<example>
+>> (new TextDecoder()).decode(new Uint8Array([206,177,206,178]))
+αβ
+</example>
+</tag-desc>
+
+</list>
+</para>
+
+</section>
+
+
+<section id="textencoder" name="Text Encoder">
+
+<para>
+The <literal>TextEncoder</literal> object
+produces a byte stream with UTF-8 encoding
+from a stream of code points
+(<link doc="changes.xml" id="njs0.4.3">0.4.3</link>).
+</para>
+
+<para>
+<list type="tag">
+
+<tag-name><literal>TextEncoder()</literal></tag-name>
+<tag-desc>
+Returns a newly constructed <literal>TextEncoder</literal>
+that will generate a byte stream with UTF-8 encoding.
+</tag-desc>
+
+<tag-name id="textencoder_encoding"><literal>TextEncoder.prototype.encoding</literal></tag-name>
+<tag-desc>
+Returns “<value>utf-8</value>”, read-only.
+</tag-desc>
+
+<tag-name id="textencoder_encode"><literal>TextEncoder.prototype.encode(<value>string</value>)</literal></tag-name>
+<tag-desc>
+Encodes <literal>string</literal> into a <literal>Uint8Array</literal>
+with UTF-8 encoded text.
+</tag-desc>
+
+<tag-name id="textencoder_encodeinto"><literal>TextEncoder.prototype.encodeInto(<value>string</value>,
+<value>uint8Array</value>)</literal></tag-name>
+<tag-desc>
+Encodes a <literal>string</literal> to UTF-8,
+puts the result into destination <literal>Uint8Array</literal>, and
+returns a dictionary object that shows the progress of the encoding.
+The dictionary object contains two members:
+
+<list type="tag">
+
+<tag-name><literal>read</literal></tag-name>
+<tag-desc>
+the number of UTF-16 units of code from the source <literal>string</literal>
+converted to UTF-8
+</tag-desc>
+
+<tag-name><literal>written</literal></tag-name>
+<tag-desc>
+the number of bytes modified in the destination <literal>Uint8Array</literal>
+</tag-desc>
+
+</list>
+</tag-desc>
+
+</list>
+</para>
+
+</section>
+
+
 <section id="njs_api_timers" name="Timers">
 
 <para>