changeset 2604:a29676472a11

Added Buffer object info to some njs methods.
author Yaroslav Zhuravlev <yar@nginx.com>
date Wed, 30 Sep 2020 22:12:05 +0100
parents 94ebfbcd68bb
children 0ec1e1b063d7
files xml/en/docs/njs/reference.xml xml/ru/docs/njs/reference.xml
diffstat 2 files changed, 66 insertions(+), 19 deletions(-) [+]
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="54">
+        rev="55">
 
 <section id="summary">
 
@@ -923,7 +923,12 @@ The encoding can be
 <literal>hex</literal>,
 <literal>base64</literal>, and
 <literal>base64url</literal>.
-If encoding is not provided, a byte string is returned.
+If encoding is not provided, a Buffer object
+(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>) is returned.
+<note>
+Before version (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>),
+a byte string was returned instead of a Buffer object.
+</note>
 </tag-desc>
 
 </list>
@@ -960,7 +965,12 @@ The encoding can be
 <literal>hex</literal>,
 <literal>base64</literal>, and
 <literal>base64url</literal>.
-If encoding is not provided, a byte string is returned.
+If encoding is not provided, a Buffer object
+(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>) is returned.
+<note>
+Before version <link doc="changes.xml" id="njs0.4.4">0.4.4</link>,
+a byte string was returned instead of a Buffer object.
+</note>
 </tag-desc>
 </list>
 </para>
@@ -1032,6 +1042,8 @@ try {
 <tag-desc>
 Synchronously appends specified <literal>data</literal>
 to a file with provided <literal>filename</literal>.
+The <literal>data</literal> is expected to be a string
+or a Buffer object (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
 If the file does not exist, it will be created.
 The <literal>options</literal> parameter is expected to be
 an object with the following keys:
@@ -1083,8 +1095,9 @@ or an object with the following keys:
 
 <tag-name id="fs_readdirsync_encoding"><literal>encoding</literal></tag-name>
 <tag-desc>
-encoding, by default is not specified.
-The encoding can be <literal>utf8</literal>.
+encoding, by default is <literal>utf8</literal>.
+The encoding can be <literal>utf8</literal> and <literal>buffer</literal>
+(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
 </tag-desc>
 
 <tag-name id="fs_readdirsync_withfiletypes"><literal>withFileTypes</literal></tag-name>
@@ -1104,8 +1117,14 @@ Synchronously returns the contents of th
 with provided <literal>filename</literal>.
 The <literal>options</literal> parameter holds
 <literal>string</literal> that specifies encoding.
-If not specified, a <link id="string_tobytes">byte string</link> is returned.
-If <literal>utf8</literal> encoding is specified, a Unicode string is returned.
+If an encoding is specified, a string is returned,
+otherwise, a Buffer object
+(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>) is returned.
+<note>
+Before version <link doc="changes.xml" id="njs0.4.4">0.4.4</link>,
+a <link id="string_tobytes">byte string</link> was returned
+if encoding was not specified.
+</note>
 Otherwise, <literal>options</literal> is expected to be
 an object with the following keys:
 <list type="tag">
@@ -1113,7 +1132,13 @@ an object with the following keys:
 <tag-name><literal>encoding</literal></tag-name>
 <tag-desc>
 encoding, by default is not specified.
-The encoding can be <literal>utf8</literal>
+The encoding can be <literal>utf8</literal>,
+<literal>hex</literal>
+(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>),
+<literal>base64</literal>
+(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>),
+<literal>base64url</literal>
+(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
 </tag-desc>
 
 <tag-name><literal>flag</literal></tag-name>
@@ -1128,7 +1153,7 @@ by default is <literal>r</literal>
 undefined
 >> var file = fs.readFileSync('/file/path.tar.gz')
 undefined
->> var gzipped = /^\x1f\x8b/.test(file); gzipped
+>> var gzipped = file.slice(0,2).toString('hex') === '1f8b'; gzipped
 true
 </example>
 </tag-desc>
@@ -1187,6 +1212,8 @@ Synchronously unlinks a file by <literal
 <tag-desc>
 Synchronously writes <literal>data</literal> to a file
 with provided <literal>filename</literal>.
+The <literal>data</literal> is expected to be a string
+or a Buffer object (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
 If the file does not exist, it will be created,
 if the file exists, it will be replaced.
 The <literal>options</literal> parameter is expected to be
--- 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="54">
+        rev="55">
 
 <section id="summary">
 
@@ -925,7 +925,12 @@ clearTimeout(t);
 <literal>hex</literal>,
 <literal>base64</literal> и
 <literal>base64url</literal>.
-Если кодировка не указана, то будет возвращена байтовая строка.
+Если кодировка не указана, то будет возвращен объект буфера
+(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
+<note>
+До версии <link doc="changes.xml" id="njs0.4.4">0.4.4</link>
+вместо объекта буфера возвращалась байтовая строка.
+</note>
 </tag-desc>
 
 </list>
@@ -1035,6 +1040,8 @@ try {
 <tag-desc>
 Синхронно добавляет указанные <literal>данные</literal>
 в файл с указанным <literal>именем</literal>.
+<literal>Данными</literal> могут быть строка
+или объект буфера (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>.
 Если файл не существует, то он будет создан.
 Параметр <literal>options</literal> должен быть
 объектом со следующими ключами:
@@ -1086,8 +1093,9 @@ try {
 
 <tag-name id="fs_readdirsync_encoding"><literal>кодировка</literal></tag-name>
 <tag-desc>
-кодировка, по умолчанию не указана.
-Кодировка может быть <literal>utf8</literal>.
+кодировка, по умолчанию <literal>utf8</literal>.
+Кодировка может быть <literal>utf8</literal> и <literal>буфер</literal>
+(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
 </tag-desc>
 
 <tag-name id="fs_readdirsync_withfiletypes"><literal>withFileTypes</literal></tag-name>
@@ -1107,10 +1115,14 @@ try {
 с указанным <literal>именем</literal>.
 Параметр <literal>options</literal> хранит
 <literal>строку</literal>, которая задаёт кодировку.
-Если кодировка не указана,
-то будет возвращена <link id="string_tobytes">байтовая строка</link>.
-Если указана кодировка <literal>utf8</literal>,
-то будет возвращена строка Unicode.
+Если кодировка указана, то будет возвращена строка,
+иначе будет возвращён объект буфера
+(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
+<note>
+До версии <link doc="changes.xml" id="njs0.4.4">0.4.4</link>
+возвращалась <link id="string_tobytes">байтовая строка</link>
+в случае, если не была указана кодировка.
+</note>
 Иначе ожидается, что <literal>options</literal> является
 объектом с ключами:
 <list type="tag">
@@ -1118,7 +1130,13 @@ try {
 <tag-name><literal>кодировка</literal></tag-name>
 <tag-desc>
 кодировка, по умолчанию не указана.
-Кодировка может быть <literal>utf8</literal>
+Кодировка может быть <literal>utf8</literal>,
+<literal>hex</literal>
+(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>),
+<literal>base64</literal>
+(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>),
+<literal>base64url</literal>
+(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
 </tag-desc>
 
 <tag-name><literal>флаг</literal></tag-name>
@@ -1133,7 +1151,7 @@ try {
 undefined
 >> var file = fs.readFileSync('/file/path.tar.gz')
 undefined
->> var gzipped = /^\x1f\x8b/.test(file); gzipped
+>> var gzipped = file.slice(0,2).toString('hex') === '1f8b'; gzipped
 true
 </example>
 </tag-desc>
@@ -1191,6 +1209,8 @@ undefined
 <tag-desc>
 Синхронно записывает <literal>данные</literal> в файл
 с указанным <literal>именем</literal>.
+<literal>Данными</literal> могут быть строка
+или объект буфера (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>.
 Если файл не существует, то он будет создан.
 Если файл существует, то он будет заменён.
 Параметр <literal>options</literal> должен быть