changeset 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 88b4976778d2
children 2af7cdbadb20
files xml/en/docs/njs/changes.xml xml/en/docs/njs/compatibility.xml xml/en/docs/njs/reference.xml xml/ru/docs/njs/compatibility.xml xml/ru/docs/njs/reference.xml
diffstat 5 files changed, 350 insertions(+), 8 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/docs/njs/changes.xml
+++ b/xml/en/docs/njs/changes.xml
@@ -9,7 +9,7 @@
 <article name="Changes"
         link="/en/docs/njs/changes.html"
         lang="en"
-        rev="36"
+        rev="37"
         toc="no">
 
 <section id="njs0.4.3" name="Changes with njs 0.4.3">
@@ -63,7 +63,11 @@ introduced UTF-8 decoder according to
 <listitem>
 <para>
 Feature:
-added TextEncoder/TextDecoder implementation.
+added
+<link doc="reference.xml" id="textdecoder"><literal>TextDecoder()</literal></link>
+and
+<link doc="reference.xml" id="textencoder"><literal>TextEncoder()</literal></link>
+implementation.
 </para>
 </listitem>
 
--- a/xml/en/docs/njs/compatibility.xml
+++ b/xml/en/docs/njs/compatibility.xml
@@ -9,7 +9,7 @@
 <article name="Compatibility"
         link="/en/docs/njs/compatibility.html"
         lang="en"
-        rev="26"
+        rev="27"
         toc="no">
 
 <section>
@@ -670,7 +670,8 @@ asynchronous version of file system meth
 </listitem>
 
 <listitem id="querysting">
-<literal>Query String</literal> methods
+<link doc="reference.xml" id="querystring"><literal>Query String</literal></link>
+methods
 (<link doc="changes.xml" id="njs0.4.3">0.4.3</link>):
 <link doc="reference.xml" id="querystring_decode"><literal>querystring.decode</literal></link>,
 <link doc="reference.xml" id="querystring_encode"><literal>querystring.encode</literal></link>,
@@ -680,6 +681,25 @@ asynchronous version of file system meth
 <link doc="reference.xml" id="querystring_unescape"><literal>querystring.unescape</literal></link>
 </listitem>
 
+<listitem id="textdecoder">
+<link doc="reference.xml" id="textdecoder"><literal>TextDecoder</literal></link>
+methods
+(<link doc="changes.xml" id="njs0.4.3">0.4.3</link>):
+<link doc="reference.xml" id="textdecoder_encoding"><literal>encoding</literal></link>,
+<link doc="reference.xml" id="textdecoder_fatal"><literal>fatal</literal></link>,
+<link doc="reference.xml" id="textdecoder_ignorebom"><literal>ignoreBOM</literal></link>,
+<link doc="reference.xml" id="textdecoder_ignorebom"><literal>decode</literal></link>
+</listitem>
+
+<listitem id="textencoder">
+<link doc="reference.xml" id="textencoder"><literal>TextEncoder</literal></link>
+methods
+(<link doc="changes.xml" id="njs0.4.3">0.4.3</link>):
+<link doc="reference.xml" id="textencoder_encoding"><literal>encoding</literal></link>,
+<link doc="reference.xml" id="textencoder_encode"><literal>encode</literal></link>,
+<link doc="reference.xml" id="textencoder_encodeinto"><literal>encodeInto</literal></link>
+</listitem>
+
 <listitem>
 ES6 modules support:
 default <literal>export</literal> and
--- 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>
--- a/xml/ru/docs/njs/compatibility.xml
+++ b/xml/ru/docs/njs/compatibility.xml
@@ -9,7 +9,7 @@
 <article name="Совместимость"
         link="/ru/docs/njs/compatibility.html"
         lang="ru"
-        rev="26"
+        rev="27"
         toc="no">
 
 <section>
@@ -666,7 +666,8 @@ ES5.1 global functions:
 </listitem>
 
 <listitem id="querysting">
-Методы <literal>Query String</literal>
+Методы
+<link doc="reference.xml" id="querystring"><literal>Query String</literal></link>
 (<link doc="changes.xml" id="njs0.4.3">0.4.3</link>):
 <link doc="reference.xml" id="querystring_decode"><literal>querystring.decode</literal></link>,
 <link doc="reference.xml" id="querystring_encode"><literal>querystring.encode</literal></link>,
@@ -676,6 +677,25 @@ ES5.1 global functions:
 <link doc="reference.xml" id="querystring_unescape"><literal>querystring.unescape</literal></link>
 </listitem>
 
+<listitem id="textdecoder">
+Методы
+<link doc="reference.xml" id="textdecoder"><literal>TextDecoder</literal></link>
+(<link doc="changes.xml" id="njs0.4.3">0.4.3</link>):
+<link doc="reference.xml" id="textdecoder_encoding"><literal>encoding</literal></link>,
+<link doc="reference.xml" id="textdecoder_fatal"><literal>fatal</literal></link>,
+<link doc="reference.xml" id="textdecoder_ignorebom"><literal>ignoreBOM</literal></link>,
+<link doc="reference.xml" id="textdecoder_ignorebom"><literal>decode</literal></link>
+</listitem>
+
+<listitem id="textencoder">
+Методы
+<link doc="reference.xml" id="textencoder"><literal>TextEncoder</literal></link>
+(<link doc="changes.xml" id="njs0.4.3">0.4.3</link>):
+<link doc="reference.xml" id="textencoder_encoding"><literal>encoding</literal></link>,
+<link doc="reference.xml" id="textencoder_encode"><literal>encode</literal></link>,
+<link doc="reference.xml" id="textencoder_encodeinto"><literal>encodeInto</literal></link>
+</listitem>
+
 <listitem>
 ES6 поддержка модулей:
 инструкции
--- a/xml/ru/docs/njs/reference.xml
+++ b/xml/ru/docs/njs/reference.xml
@@ -9,7 +9,7 @@
 <article name="Справочник"
         link="/ru/docs/njs/reference.html"
         lang="ru"
-        rev="52">
+        rev="53">
 
 <section id="summary">
 
@@ -677,6 +677,155 @@ 4
 </section>
 
 
+<section id="textdecoder" name="Text Decoder">
+
+<para>
+Объект <literal>TextDecoder</literal>
+создаёт поток кодовых точек из потока данных
+(<link doc="changes.xml" id="njs0.4.3">0.4.3</link>).
+</para>
+
+<para>
+<list type="tag">
+
+<tag-name><literal>TextDecoder([[<value>кодировка</value>],
+<value>options</value>])</literal></tag-name>
+<tag-desc>
+Создаёт новый объект <literal>TextDecoder</literal>
+для указанной <literal>кодировки</literal>,
+на данный момент поддерживается только UTF-8.
+Параметр <literal>options</literal> является
+словарём <literal>TextDecoderOption</literal> со свойствами:
+
+<list type="tag">
+
+<tag-name><literal>fatal</literal></tag-name>
+<tag-desc>
+логический флаг, указывающий, что
+<link id="textdecoder_decode"><literal>TextDecoder.decode()</literal></link>
+должен вызывать исключение <value>TypeError</value> в случае, если
+найдена ошибка кодирования, по умолчанию <literal>false</literal>.
+</tag-desc>
+
+</list>
+</tag-desc>
+
+<tag-name id="textdecoder_encoding"><literal>TextDecoder.prototype.encoding</literal></tag-name>
+<tag-desc>
+Возвращает строку с именем кодировки, используемой
+<link id="textdecoder"><literal>TextDecoder()</literal></link>,
+только чтение.
+</tag-desc>
+
+<tag-name id="textdecoder_fatal"><literal>TextDecoder.prototype.fatal</literal></tag-name>
+<tag-desc>
+логический флаг, <literal>true</literal>, если
+генерируется ошибка для невалидных символов,
+только чтение.
+</tag-desc>
+
+<tag-name id="textdecoder_ignorebom"><literal>TextDecoder.prototype.ignoreBOM</literal></tag-name>
+<tag-desc>
+логический флаг, <literal>true</literal>, если
+игнорируется маркер порядка следования байтов,
+только чтение.
+</tag-desc>
+
+<tag-name id="textdecoder_decode"><literal>TextDecoder.prototype.decode(<value>буфер</value>,
+[<value>options</value>])</literal></tag-name>
+<tag-desc>
+Возвращает строку с текстом,
+декодированным из <literal>буфера</literal> при помощи
+<link id="textdecoder"><literal>TextDecoder()</literal></link>.
+Буфером может быть
+<literal>ArrayBuffer</literal>.
+Параметром <literal>options</literal> является
+словарь <literal>TextDecodeOptions</literal> со свойствами:
+
+<list type="tag">
+
+<tag-name><literal>stream</literal></tag-name>
+<tag-desc>
+логический флаг, указывающий, что
+при последующих вызовах <literal>decode()</literal>
+должны последовать дополнительные данные:
+<literal>true</literal>, если данные обрабатываются блоками, и
+<literal>false</literal> для последнего блока
+или если данные не передаются блоками.
+По умолчанию <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>
+Объект <literal>TextEncoder</literal>
+создаёт поток данных в кодировке UTF-8
+из потока кодовых точек
+(<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>
+Возвращает только что созданный <literal>TextEncoder</literal>,
+который создаёт поток данных в кодировке UTF-8.
+</tag-desc>
+
+<tag-name id="textencoder_encoding"><literal>TextEncoder.prototype.encoding</literal></tag-name>
+<tag-desc>
+Возвращает “<value>utf-8</value>”, только для чтения.
+</tag-desc>
+
+<tag-name id="textencoder_encode"><literal>TextEncoder.prototype.encode(<value>строка</value>)</literal></tag-name>
+<tag-desc>
+Кодирует <literal>строку</literal> в <literal>Uint8Array</literal>,
+содержащий текст в кодировке UTF-8.
+</tag-desc>
+
+<tag-name id="textencoder_encodeinto"><literal>TextEncoder.prototype.encodeInto(<value>строка</value>,
+<value>uint8Array</value>)</literal></tag-name>
+<tag-desc>
+Преобразует <literal>строку</literal> в UTF-8,
+сохраняет результат в целевом <literal>Uint8Array</literal> и
+возвращает объект словаря, отражающий прогресс кодирования, со свойствами:
+
+<list type="tag">
+
+<tag-name><literal>read</literal></tag-name>
+<tag-desc>
+количество блоков кода UTF-16 из исходной строки,
+преобразованных в UTF-8
+</tag-desc>
+
+<tag-name><literal>written</literal></tag-name>
+<tag-desc>
+количество байтов, преобразованных в целевом <literal>Uint8Array</literal>
+</tag-desc>
+
+</list>
+</tag-desc>
+
+</list>
+</para>
+
+</section>
+
+
 <section id="njs_api_timers" name="Timers">
 
 <para>