changeset 2609:99bd2ae8d2be

Added Buffer to njs Reference.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 08 Oct 2020 11:36:19 +0100
parents 249ae2577aac
children fdfe54a01ea1
files xml/en/docs/njs/reference.xml
diffstat 1 files changed, 571 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/docs/njs/reference.xml
+++ b/xml/en/docs/njs/reference.xml
@@ -872,6 +872,577 @@ clearTimeout(t);
 <section id="built-in" name="Built-in Modules">
 
 
+<section id="buffer" name="Buffer">
+
+<para>
+<list type="tag">
+
+<tag-name id="buffer_alloc"><literal>Buffer.alloc(<value>size</value>[,
+<value>fill</value>[,
+<value>encoding</value>]]))</literal></tag-name>
+<tag-desc>
+<para>
+Allocates a new Buffer of a specified <value>size</value>.
+If <value>fill</value> is not specified, the Buffer will be zero-filled.
+If <value>fill</value> is specified,
+the allocated Buffer will be initialized by calling
+<link id="buf_fill"><literal>buf.fill(fill)</literal></link>.
+If <value>fill</value> and <value>encoding</value> are specified,
+the allocated Buffer will be initialized by calling
+<link id="buf_fill"><literal>buf.fill(fill,
+encoding)</literal></link>.
+</para>
+
+<para>
+The <value>fill</value> parameter may be a
+<value>string</value>,
+<value>Buffer</value>,
+<value>Uint8Array</value>, or
+<value>integer</value>.
+</para>
+</tag-desc>
+
+<tag-name id="buffer_alloc_unsafe"><literal>Buffer.allocUnsafe(<value>size</value>)</literal></tag-name>
+<tag-desc>
+<para>
+The same as
+<link id="buffer_alloc"><literal>Buffer.alloc()</literal></link>,
+with the difference that the memory allocated for the buffer is not initialized,
+the contents of the new buffer is unknown and may contain sensitive data.
+</para>
+</tag-desc>
+
+<tag-name id="buffer_bytelength"><literal>Buffer.byteLength(<value>value</value>[,
+<value>encoding</value>])</literal></tag-name>
+<tag-desc>
+Returns the byte length of a specified value,
+when encoded using <value>encoding</value>.
+The value can be a
+<literal>string</literal>,
+<literal>Buffer</literal>,
+<literal>TypedArray</literal>,
+<literal>DataView</literal>, or
+<literal>ArrayBuffer</literal>.
+If the value is a <value>string</value>,
+the <literal>encoding</literal> parameter is its encoding, can be
+<value>utf-8</value>,
+<value>hex</value>,
+<value>base64</value>,
+<value>base64url</value>;
+by default is <value>utf-8</value>.
+</tag-desc>
+
+<tag-name id="buffer_compare"><literal>Buffer.compare(<value>buffer1</value>,
+<value>buffer2</value>)</literal></tag-name>
+<tag-desc>
+Compares <value>buffer1</value> with <value>buffer2</value>
+when sorting arrays of Buffer instances.
+Returns
+<literal>0</literal> if
+<value>buffer1</value> is the same as <value>buffer2</value>,
+<literal>1</literal> if
+<value>buffer2</value> should come before <value>buffer1</value> when sorted, or
+<literal>-1</literal> if
+<value>buffer2</value> should come after <value>buffer1</value> when sorted.
+</tag-desc>
+
+<tag-name id="buffer_concat"><literal>Buffer.concat(<value>list</value>[,
+<value>totalLength</value>])</literal></tag-name>
+<tag-desc>
+Returns a new Buffer
+which is the result of concatenating all the Buffer instances in the list.
+If there are no items in the list or the total length is 0, 
+a new zero-length Buffer is returned.
+If <value>totalLength</value> is not specified,
+it is calculated from the Buffer instances in list by adding their lengths.
+If <value>totalLength</value> is specified,
+it is coerced to an unsigned integer.
+If the combined length of the Buffers in list exceeds
+<value>totalLength</value>,
+the result is truncated to <value>totalLength</value>.
+</tag-desc>
+
+<tag-name id="buffer_from_array"><literal>Buffer.from(<value>array</value>)</literal></tag-name>
+<tag-desc>
+Allocates a new Buffer using an array of bytes
+in the range <literal>0</literal> – <literal>255</literal>.
+Array entries outside that range will be truncated.
+</tag-desc>
+
+<tag-name id="buffer_from_buffer"><literal>Buffer.from(<value>buffer</value>)</literal></tag-name>
+<tag-desc>
+Copies the passed buffer data onto a new Buffer instance.
+</tag-desc>
+
+<tag-name id="buffer_from_object"><literal>Buffer.from(<value>object</value>[,
+<value>offsetOrEncoding</value>[,
+<value>length</value>]])</literal></tag-name>
+<tag-desc>
+For objects whose <literal>valueOf()</literal> function
+returns a value not strictly equal to object,
+returns
+<literal>Buffer.from(object.valueOf()</literal>,
+<literal>offsetOrEncoding</literal>,
+<literal>length</literal>).
+</tag-desc>
+
+<tag-name id="buffer_from_string"><literal>Buffer.from(<value>string</value>[,
+<value>encoding</value>])</literal></tag-name>
+<tag-desc>
+Creates a new Buffer with a <value>string</value>.
+The <value>encoding</value> parameter identifies the character encoding
+to be used when converting a string into bytes.
+The encoding can be
+<literal>utf-8</literal>,
+<literal>hex</literal>,
+<literal>base64</literal>,
+<literal>base64url</literal>;
+by default is <literal>utf-8</literal>.
+</tag-desc>
+
+<tag-name id="buffer_is_buffer"><literal>Buffer.isBuffer(<value>object</value>)</literal></tag-name>
+<tag-desc>
+A boolean value,
+returns <literal>true</literal> if <value>object</value> is a Buffer.
+</tag-desc>
+
+<tag-name id="buffer_is_encoding"><literal>Buffer.isEncoding(<value>encoding</value>)</literal></tag-name>
+<tag-desc>
+A boolean value,
+returns <literal>true</literal>
+if encoding is the name of a supported character encoding.
+</tag-desc>
+
+<tag-name id="buf_index"><literal>buffer[<value>index</value>]</literal></tag-name>
+<tag-desc>
+The index operator <value>index</value>
+can be used to get and set the octet at position index in
+<literal>buffer</literal>.
+The values refer to individual bytes,
+so the legal value range is between 0 and 255 (decimal).
+</tag-desc>
+
+<tag-name id="buf_buffer"><literal>buf.buffer</literal></tag-name>
+<tag-desc>
+The underlying <literal>ArrayBuffer</literal> object
+based on which this Buffer object is created.
+</tag-desc>
+
+<tag-name id="buf_byte_offset"><literal>buf.byteOffset</literal></tag-name>
+<tag-desc>
+An integer,
+specifying the <literal>byteOffset</literal> of the Buffers
+underlying <literal>ArrayBuffer</literal> object.
+</tag-desc>
+
+<tag-name id="buf_compare"><literal>buf.compare(<value>target</value>[,
+<value>targetStart</value>[,
+<value>targetEnd</value>[,
+<value>sourceStart</value>[,
+<value>sourceEnd</value>]]]])</literal></tag-name>
+<tag-desc>
+Compares buffer with target and returns a number
+indicating whether buffer comes before, after, or is the same
+as target in sort order.
+Comparison is based on the actual sequence of bytes in each Buffer.
+The <literal>targetStart</literal> is an integer specifying the offset
+within target at which to begin comparison,
+by default is 0.
+The <literal>targetEnd</literal> is an integer specifying the offset
+within target at which to end comparison,
+by default is <literal>target.length</literal>.
+The <literal>sourceStart</literal> is an integer specifying the offset
+within buffer at which to begin comparison,
+by default is 0.
+The <literal>sourceEnd</literal> is an integer specifying the offset
+within buffer at which to end comparison (not inclusive),
+by default is <literal>buf.length</literal>.
+</tag-desc>
+
+<tag-name id="buf_copy"><literal>buf.copy(<value>target</value>[,
+<value>targetStart</value>[,
+<value>sourceStart</value>[,
+<value>sourceEnd</value>]]])</literal></tag-name>
+<tag-desc>
+Copies data from a region of buffer to a region in target,
+even if the target memory region overlaps with buffer.
+The <literal>target</literal> parameter is a
+<value>Buffer</value> or <value>Uint8Array</value> to copy into.
+
+<para>
+The <literal>targetStart</literal> is an integer specifying the offset
+within target at which to begin writing,
+by default is 0.
+The <literal>sourceStart</literal> is an integer specifying the offset
+within buffer from which to begin copying,
+by default is 0.
+The <literal>sourceEnd</literal> is an integer specifying the offset
+within buffer at which to stop copying (not inclusive)
+by default is <value>buf.length</value>.
+</para>
+</tag-desc>
+
+<tag-name id="buf_equals"><literal>buf.equals(<value>otherBuffer</value>)</literal></tag-name>
+<tag-desc>
+A boolean value,
+returns <literal>true</literal> if both Buffer and <value>otherBuffer</value>
+have exactly the same bytes.
+</tag-desc>
+
+<tag-name id="buf_fill"><literal>buf.fill(<value>value</value>[,
+<value>offset</value>[,
+<value>end</value>]][,
+<value>encoding</value>])</literal></tag-name>
+<tag-desc>
+Fills the Buffer with the specified <value>value</value>.
+If the <value>offset</value> and <value>end</value> are not specified,
+the entire Buffer will be filled.
+The <value>value</value> is coerced to <value>uint32</value> if it is not a
+<literal>string</literal>,
+<literal>Buffer</literal>, or
+<literal>integer</literal>.
+If the resulting integer is greater than 255,
+the Buffer will be filled with <value>value</value> and 255.
+</tag-desc>
+
+<tag-name id="buf_includes"><literal>buf.includes(<value>value</value>[,
+<value>byteOffset</value>][,
+<value>encoding</value>])</literal></tag-name>
+<tag-desc>
+Equivalent to
+<link id="buf_indexof"><literal>buf.indexOf()</literal></link>
+<literal>!== -1</literal>,
+returns <literal>true</literal> if the <value>value</value> was found
+in Buffer.
+</tag-desc>
+
+<tag-name id="buf_indexof"><literal>buf.indexOf(<value>value</value>[,
+<value>byteOffset</value>][,
+<value>encoding</value>])</literal></tag-name>
+<tag-desc>
+Returns an integer which is the index of the first occurrence of
+<value>value</value> in Buffer, or <value>-1</value>
+if Buffer does not contain value.
+The <value>value</value> can be a
+<literal>string</literal> with specified <value>encoding</value>
+(by default <value>utf-8</value>),
+<literal>Buffer</literal>,
+<literal>Unit8Array</literal>,
+or a number between 0 and 255.
+</tag-desc>
+
+<tag-name id="buf_lastindexof"><literal>buf.lastIndexOf(<value>value</value>[,
+<value>byteOffset</value>][,
+<value>encoding</value>])</literal></tag-name>
+<tag-desc>
+The same as
+<link id="buf_indexof"><literal>buf.indexOf()</literal></link>,
+except the last occurrence of the <value>value</value> is found
+instead of the first occurrence.
+The <value>value</value> can be a string, Buffer, or
+integer between 1 and 255.
+If the <value>value</value> is an empty string or empty Buffer,
+<literal>byteOffset</literal> will be returned.
+</tag-desc>
+
+<tag-name id="buf_length"><literal>buf.length</literal></tag-name>
+<tag-desc>
+Returns the number of bytes in Buffer.
+</tag-desc>
+
+<tag-name id="buf_readintbe"><literal>buf.readIntBE(<value>offset</value>,
+<value>byteLength</value>)</literal></tag-name>
+<tag-desc>
+Reads the <value>byteLength</value> from <literal>buf</literal>
+at the specified <value>offset</value>
+and interprets the result as a big-endian,
+two's complement signed value supporting up to 48 bits of accuracy.
+The <value>byteLength</value> parameter is an integer between 1 and 6
+specifying the number of bytes to read.
+<para>
+The similar methods are also supported:
+<literal>buf.readInt8([offset])</literal>,
+<literal>buf.readInt16BE([offset])</literal>,
+<literal>buf.readInt32BE([offset])</literal>.
+</para>
+</tag-desc>
+
+<tag-name id="buf_readintle"><literal>buf.readIntLE(<value>offset</value>,
+<value>byteLength</value>)</literal></tag-name>
+<tag-desc>
+Reads the <value>byteLength</value> from <literal>buf</literal>
+at the specified <value>offset</value>
+and interprets the result as a little-endian,
+two's complement signed value supporting up to 48 bits of accuracy.
+The <value>byteLength</value> parameter is an integer between 1 and 6
+specifying the number of bytes to read.
+<para>
+The similar methods are also supported:
+<literal>buf.readInt8([offset])</literal>,
+<literal>buf.readInt16LE([offset])</literal>,
+<literal>buf.readInt32LE([offset])</literal>.
+</para>
+</tag-desc>
+
+<tag-name id="buf_readuintbe"><literal>buf.readUIntBE(<value>offset</value>,
+<value>byteLength</value>)</literal></tag-name>
+<tag-desc>
+Reads the <value>byteLength</value> from <literal>buf</literal>
+at the specified <value>offset</value>
+and interprets the result as a big-endian
+integer supporting up to 48 bits of accuracy.
+The <value>byteLength</value> parameter is an integer between 1 and 6
+specifying the number of bytes to read.
+<para>
+The similar methods are also supported:
+<literal>buf.readUInt8([offset])</literal>,
+<literal>buf.readUInt16BE([offset])</literal>,
+<literal>buf.readUInt32BE([offset])</literal>.
+</para>
+</tag-desc>
+
+<tag-name id="buf_readuintle"><literal>buf.readUIntLE(<value>offset</value>,
+<value>byteLength</value>)</literal></tag-name>
+<tag-desc>
+Reads the <value>byteLength</value> from <literal>buf</literal>
+at the specified <value>offset</value>
+and interprets the result as a little-endian
+integer supporting up to 48 bits of accuracy.
+The <value>byteLength</value> parameter is an integer between 1 and 6
+specifying the number of bytes to read.
+<para>
+The similar methods are also supported:
+<literal>buf.readUInt8([offset])</literal>,
+<literal>buf.readUInt16LE([offset])</literal>,
+<literal>buf.readUInt32LE([offset])</literal>.
+</para>
+</tag-desc>
+
+<tag-name id="buf_readdobulebe"><literal>buf.readDoubleBE</literal>([<value>offset</value>])</tag-name>
+<tag-desc>
+Reads a 64-bit, big-endian double from <literal>buf</literal>
+at the specified <value>offset</value>.
+</tag-desc>
+
+<tag-name id="buf_readdobulele"><literal>buf.readDoubleLE</literal>([<value>offset</value>])</tag-name>
+<tag-desc>
+Reads a 64-bit, little-endian double from <literal>buf</literal>
+at the specified <value>offset</value>.
+</tag-desc>
+
+<tag-name id="buf_readfloatbe"><literal>buf.readFloatBE</literal>([<value>offset</value>])</tag-name>
+<tag-desc>
+Reads a 32-bit, big-endian float from <literal>buf</literal>
+at the specified <value>offset</value>.
+</tag-desc>
+
+<tag-name id="buf_readfloatle"><literal>buf.readFloatLE</literal>([<value>offset</value>])</tag-name>
+<tag-desc>
+Reads a 32-bit, little-endian float from <literal>buf</literal>
+at the specified <value>offset</value>.
+</tag-desc>
+
+<tag-name id="buf_subarray"><literal>buf.subarray[<value>start</value>[,
+<value>end</value>]])</literal></tag-name>
+<tag-desc>
+Returns a new <literal>buf</literal>
+that references the same memory as the original,
+but offset and cropped by
+<value>start</value> and <value>end</value>.
+If <value>end</value> is greater than
+<link id="buf_length"><literal>buf.length</literal></link>,
+the same result as that of end equal to
+<link id="buf_length"><literal>buf.length</literal></link>
+is returned.
+</tag-desc>
+
+<tag-name id="buf_slice"><literal>buf.slice[<value>start</value>[,
+<value>end</value>]])</literal></tag-name>
+<tag-desc>
+Returns a new <literal>buf</literal>
+that references the same memory as the original,
+but offset and cropped by the
+<value>start</value> and <value>end</value> values.
+The method is not compatible with the
+<literal>Uint8Array.prototype.slice()</literal>,
+which is a superclass of Buffer.
+To copy the slice, use
+<literal>Uint8Array.prototype.slice()</literal>.
+</tag-desc>
+
+<tag-name id="buf_swap16"><literal>buf.swap16</literal>()</tag-name>
+<tag-desc>
+Interprets <literal>buf</literal> as an array of unsigned 16-bit numbers
+and swaps the byte order in-place.
+Throws an error if
+<link id="buf_length"><literal>buf.length</literal></link>
+is not a multiple of 2.
+</tag-desc>
+
+<tag-name id="buf_swap32"><literal>buf.swap32</literal>()</tag-name>
+<tag-desc>
+Interprets <literal>buf</literal> as an array of unsigned 32-bit numbers
+and swaps the byte order in-place.
+Throws an error if
+<link id="buf_length"><literal>buf.length</literal></link>
+is not a multiple of 4.
+</tag-desc>
+
+<tag-name id="buf_swap64"><literal>buf.swap64</literal>()</tag-name>
+<tag-desc>
+Interprets <literal>buf</literal> as an array of 64-bit numbers
+and swaps byte order in-place.
+Throws an error if
+<link id="buf_length"><literal>buf.length</literal></link>
+is not a multiple of 8.
+</tag-desc>
+
+<tag-name id="buf_tojson"><literal>buf.toJSON</literal>()</tag-name>
+<tag-desc>
+Returns a JSON representation of <literal>buf.</literal>
+<literal>JSON.stringify()</literal>
+implicitly calls this function when stringifying a Buffer instance.
+</tag-desc>
+
+<tag-name id="buf_tostring"><literal>buf.toString([<value>encoding</value>[,
+<value>start</value>[,
+<value>end</value>]]])</literal></tag-name>
+<tag-desc>
+Decodes <literal>buf</literal> to a string
+according to the specified character <value>encoding</value>.
+which can be <value>utf-8</value>,
+<value>hex</value>,
+<value>base64</value>,
+<value>base64url</value>.
+The <value>start</value> and <value>end</value> parameters
+may be passed to decode only a subset of Buffer.
+</tag-desc>
+
+<tag-name id="buf_write"><literal>buf.write(<value>string</value>[,
+<value>offset</value>[,
+<value>length</value>]][,
+<value>encoding</value>])</literal></tag-name>
+<tag-desc>
+Writes a <value>string</value> to <literal>buf</literal>
+at <value>offset</value>
+according to the character <value>encoding</value>.
+The <value>length</value> parameter is the number of bytes to write.
+If Buffer did not contain enough space to fit the entire string,
+only part of string will be written,
+however, partially encoded characters will not be written.
+The <value>encoding</value> can be
+<value>utf-8</value>,
+<value>hex</value>,
+<value>base64</value>,
+<value>base64url</value>.
+</tag-desc>
+
+<tag-name id="buf_writeintbe"><literal>buf.writeIntBE(<value>value</value>,
+<value>offset</value>,
+<value>byteLength</value>)</literal></tag-name>
+<tag-desc>
+Writes <value>byteLength</value> bytes of <value>value</value>
+to <literal>buf</literal>
+at the specified <value>offset</value> as big-endian.
+Supports up to 48 bits of accuracy.
+The <value>byteLength</value> parameter is an integer between 1 and 6
+specifying the number of bytes to read.
+<para>
+The following similar methods are also supported:
+<literal>buf.writeInt8</literal>,
+<literal>buf.writeInt16BE</literal>,
+<literal>buf.writeInt32BE</literal>.
+</para>
+</tag-desc>
+
+<tag-name id="buf_writeintle"><literal>buf.writeIntLE(<value>value</value>,
+<value>offset</value>,
+<value>byteLength</value>)</literal></tag-name>
+<tag-desc>
+Writes <value>byteLength</value> bytes of <value>value</value>
+to <literal>buf</literal>
+at the specified <value>offset</value> as little-endian.
+Supports up to 48 bits of accuracy.
+The <value>byteLength</value> parameter is an integer between 1 and 6
+specifying the number of bytes to read.
+<para>
+The following similar methods are also supported:
+<literal>buf.writeInt8</literal>,
+<literal>buf.writeInt16LE</literal>,
+<literal>buf.writeInt32LE</literal>.
+</para>
+</tag-desc>
+
+<tag-name id="buf_writeuintbe"><literal>buf.writeUIntBE(<value>value</value>,
+<value>offset</value>,
+<value>byteLength</value>)</literal></tag-name>
+<tag-desc>
+Writes <value>byteLength</value> bytes of <value>value</value>
+to <literal>buf</literal>
+at the specified <value>offset</value> as big-endian.
+Supports up to 48 bits of accuracy.
+The <value>byteLength</value> parameter is an integer between 1 and 6
+specifying the number of bytes to read.
+<para>
+The following similar methods are also supported:
+<literal>buf.writeUInt8</literal>,
+<literal>buf.writeUInt16BE</literal>,
+<literal>buf.writeUInt32BE</literal>.
+</para>
+</tag-desc>
+
+<tag-name id="buf_writeuintle"><literal>buf.writeUIntLE(<value>value</value>,
+<value>offset</value>,
+<value>byteLength</value>)</literal></tag-name>
+<tag-desc>
+Writes <value>byteLength</value> bytes of <value>value</value>
+to <literal>buf</literal>
+at the specified <value>offset</value> as little-endian.
+Supports up to 48 bits of accuracy.
+The <value>byteLength</value> parameter is an integer between 1 and 6
+specifying the number of bytes to read.
+<para>
+The following similar methods are also supported:
+<literal>buf.writeUInt8</literal>,
+<literal>buf.writeUInt16LE</literal>,
+<literal>buf.writeUInt32LE</literal>.
+</para>
+</tag-desc>
+
+<tag-name id="buf_writedoublebe"><literal>buf.writeDoubleBE(<value>value</value>,
+[<value>offset</value>])</literal></tag-name>
+<tag-desc>
+Writes the <value>value</value> to <literal>buf</literal>
+at the specified <value>offset</value> as big-endian.
+</tag-desc>
+
+<tag-name id="buf_writedoublele"><literal>buf.writeDoubleLE(<value>value</value>,
+[<value>offset</value>])</literal></tag-name>
+<tag-desc>
+Writes the <value>value</value> to <literal>buf</literal>
+at the specified <value>offset</value> as little-endian.
+</tag-desc>
+
+<tag-name id="buf_writefloatbe"><literal>buf.writeFloatBE(<value>value</value>,
+[<value>offset</value>])</literal></tag-name>
+<tag-desc>
+Writes the <value>value</value> to <literal>buf</literal>
+at the specified <value>offset</value> as big-endian.
+</tag-desc>
+
+<tag-name id="buf_writefloatle"><literal>buf.writeFloatLE(<value>value</value>,
+[<value>offset</value>])</literal></tag-name>
+<tag-desc>
+Writes the <value>value</value> to <literal>buf</literal>
+at the specified <value>offset</value> as little-endian.
+</tag-desc>
+
+</list>
+</para>
+
+</section>
+
+
 <section id="crypto" name="Crypto">
 
 <para>