From e3d5d4d6e967c307f04d480f05add0bab80727e5 Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Sat, 30 Mar 2019 20:33:25 +0200 Subject: [PATCH 01/10] doc: remove duplication in description --- doc/api/buffer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/buffer.md b/doc/api/buffer.md index f5e5dd2f765538..fb99c70b196bee 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -530,7 +530,7 @@ console.log(buf); // Prints: ``` -Allocates a new `Buffer` of `size` bytes. If `size` is larger than +If `size` is larger than [`buffer.constants.MAX_LENGTH`] or smaller than 0, [`ERR_INVALID_OPT_VALUE`] is thrown. A zero-length `Buffer` is created if `size` is 0. From ac2caec3846fba22d0b351c7e5791145844b91ba Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Sun, 31 Mar 2019 11:14:42 +0300 Subject: [PATCH 02/10] doc: fix possible typo --- doc/api/buffer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/buffer.md b/doc/api/buffer.md index fb99c70b196bee..d238b61d2a3188 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -1034,7 +1034,7 @@ changes: compare `buf`. * `targetStart` {integer} The offset within `target` at which to begin comparison. **Default:** `0`. -* `targetEnd` {integer} The offset with `target` at which to end comparison +* `targetEnd` {integer} The offset within `target` at which to end comparison (not inclusive). **Default:** `target.length`. * `sourceStart` {integer} The offset within `buf` at which to begin comparison. **Default:** `0`. From 78f629a67858108f599248e03e52c1c2229dcdc6 Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Sun, 31 Mar 2019 11:02:42 +0300 Subject: [PATCH 03/10] doc: add missing types --- doc/api/buffer.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/doc/api/buffer.md b/doc/api/buffer.md index d238b61d2a3188..d1e1357088d1c9 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -515,8 +515,8 @@ changes: --> * `size` {integer} The desired length of the new `Buffer`. -* `fill` {string|Buffer|integer} A value to pre-fill the new `Buffer` with. - **Default:** `0`. +* `fill` {string|Buffer|Uint8Array|integer} A value to pre-fill the new `Buffer` + with. **Default:** `0`. * `encoding` {string} If `fill` is a string, this is its encoding. **Default:** `'utf8'`. @@ -958,6 +958,8 @@ type: property name: [index] --> +* `index` {integer} + The index operator `[index]` can be used to get and set the octet at position `index` in `buf`. The values refer to individual bytes, so the legal value range is between `0x00` and `0xFF` (hex) or `0` and `255` (decimal). @@ -1176,8 +1178,8 @@ changes: description: The arguments can now be `Uint8Array`s. --> -* `otherBuffer` {Buffer} A `Buffer` or [`Uint8Array`] with which to compare - `buf`. +* `otherBuffer` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`] with which to + compare `buf`. * Returns: {boolean} Returns `true` if both `buf` and `otherBuffer` have exactly the same bytes, @@ -1217,7 +1219,7 @@ changes: description: The `encoding` parameter is supported now. --> -* `value` {string|Buffer|integer} The value with which to fill `buf`. +* `value` {string|Buffer|Uint8Array|integer} The value with which to fill `buf`. * `offset` {integer} Number of bytes to skip before starting to fill `buf`. **Default:** `0`. * `end` {integer} Where to stop filling `buf` (not inclusive). **Default:** @@ -1271,7 +1273,7 @@ console.log(buf.fill('zz', 'hex')); added: v5.3.0 --> -* `value` {string|Buffer|integer} What to search for. +* `value` {string|Buffer|Uint8Array|integer} What to search for. * `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`. * `encoding` {string} If `value` is a string, this is its encoding. **Default:** `'utf8'`. @@ -2515,6 +2517,7 @@ changes: * `source` {Buffer|Uint8Array} A `Buffer` or `Uint8Array` instance. * `fromEnc` {string} The current encoding. * `toEnc` {string} To target encoding. +* Returns: {Buffer} Re-encodes the given `Buffer` or `Uint8Array` instance from one character encoding to another. Returns a new `Buffer` instance. From 87d70b0669e02ea6c1ed0896c8dd89e8b73aa6b8 Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Sun, 31 Mar 2019 11:08:16 +0300 Subject: [PATCH 04/10] doc: unify number/integer types --- doc/api/buffer.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/api/buffer.md b/doc/api/buffer.md index d1e1357088d1c9..969668dd7a977a 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -867,11 +867,11 @@ A `TypeError` will be thrown if `buffer` is not a `Buffer`. added: v8.2.0 --> -* `object` {Object} An object supporting `Symbol.toPrimitive` or `valueOf()` -* `offsetOrEncoding` {number|string} A byte-offset or encoding, depending on +* `object` {Object} An object supporting `Symbol.toPrimitive` or `valueOf()`. +* `offsetOrEncoding` {integer|string} A byte-offset or encoding, depending on the value returned either by `object.valueOf()` or `object[Symbol.toPrimitive]()`. -* `length` {number} A length, depending on the value returned either by +* `length` {integer} A length, depending on the value returned either by `object.valueOf()` or `object[Symbol.toPrimitive]()`. For objects whose `valueOf()` function returns a value not strictly equal to From 83052d2bfe0a8c9d2d1d826c740c333726ecdd43 Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Sat, 30 Mar 2019 20:45:19 +0200 Subject: [PATCH 05/10] doc: fix error notes in `Buffer.from()` variants Make notes about `TypeError` conditions in `Buffer.from()` variants more accurate. --- doc/api/buffer.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 969668dd7a977a..afeef8b3c203ae 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -787,7 +787,8 @@ Allocates a new `Buffer` using an `array` of octets. const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]); ``` -A `TypeError` will be thrown if `array` is not an `Array`. +A `TypeError` will be thrown if `array` is not an `Array` or other type +appropriate for `Buffer.from()` variants. ### Class Method: Buffer.from(arrayBuffer[, byteOffset[, length]]) * `offset` {integer} Number of bytes to skip before starting to read. Must - satisfy `0 <= offset <= buf.length - 8`. + satisfy `0 <= offset <= buf.length - 8`. **Default:** `0`. * Returns: {number} Reads a 64-bit double from `buf` at the specified `offset` with specified @@ -1571,8 +1571,8 @@ console.log(buf.readDoubleLE(1)); // Throws ERR_OUT_OF_RANGE ``` -### buf.readFloatBE(offset) -### buf.readFloatLE(offset) +### buf.readFloatBE([offset]) +### buf.readFloatLE([offset]) * `offset` {integer} Number of bytes to skip before starting to read. Must - satisfy `0 <= offset <= buf.length - 4`. + satisfy `0 <= offset <= buf.length - 4`. **Default:** `0`. * Returns: {number} Reads a 32-bit float from `buf` at the specified `offset` with specified @@ -1601,7 +1601,7 @@ console.log(buf.readFloatLE(1)); // Throws ERR_OUT_OF_RANGE ``` -### buf.readInt8(offset) +### buf.readInt8([offset]) * `offset` {integer} Number of bytes to skip before starting to read. Must - satisfy `0 <= offset <= buf.length - 1`. + satisfy `0 <= offset <= buf.length - 1`. **Default:** `0`. * Returns: {integer} Reads a signed 8-bit integer from `buf` at the specified `offset`. @@ -1630,8 +1630,8 @@ console.log(buf.readInt8(2)); // Throws ERR_OUT_OF_RANGE ``` -### buf.readInt16BE(offset) -### buf.readInt16LE(offset) +### buf.readInt16BE([offset]) +### buf.readInt16LE([offset]) * `offset` {integer} Number of bytes to skip before starting to read. Must - satisfy `0 <= offset <= buf.length - 2`. + satisfy `0 <= offset <= buf.length - 2`. **Default:** `0`. * Returns: {integer} Reads a signed 16-bit integer from `buf` at the specified `offset` with @@ -1662,8 +1662,8 @@ console.log(buf.readInt16LE(1)); // Throws ERR_OUT_OF_RANGE ``` -### buf.readInt32BE(offset) -### buf.readInt32LE(offset) +### buf.readInt32BE([offset]) +### buf.readInt32LE([offset]) * `offset` {integer} Number of bytes to skip before starting to read. Must - satisfy `0 <= offset <= buf.length - 4`. + satisfy `0 <= offset <= buf.length - 4`. **Default:** `0`. * Returns: {integer} Reads a signed 32-bit integer from `buf` at the specified `offset` with @@ -1728,7 +1728,7 @@ console.log(buf.readIntBE(1, 0).toString(16)); // Throws ERR_OUT_OF_RANGE ``` -### buf.readUInt8(offset) +### buf.readUInt8([offset]) * `offset` {integer} Number of bytes to skip before starting to read. Must - satisfy `0 <= offset <= buf.length - 1`. + satisfy `0 <= offset <= buf.length - 1`. **Default:** `0`. * Returns: {integer} Reads an unsigned 8-bit integer from `buf` at the specified `offset`. @@ -1755,8 +1755,8 @@ console.log(buf.readUInt8(2)); // Throws ERR_OUT_OF_RANGE ``` -### buf.readUInt16BE(offset) -### buf.readUInt16LE(offset) +### buf.readUInt16BE([offset]) +### buf.readUInt16LE([offset]) * `offset` {integer} Number of bytes to skip before starting to read. Must - satisfy `0 <= offset <= buf.length - 2`. + satisfy `0 <= offset <= buf.length - 2`. **Default:** `0`. * Returns: {integer} Reads an unsigned 16-bit integer from `buf` at the specified `offset` with @@ -1789,8 +1789,8 @@ console.log(buf.readUInt16LE(2).toString(16)); // Throws ERR_OUT_OF_RANGE ``` -### buf.readUInt32BE(offset) -### buf.readUInt32LE(offset) +### buf.readUInt32BE([offset]) +### buf.readUInt32LE([offset]) * `offset` {integer} Number of bytes to skip before starting to read. Must - satisfy `0 <= offset <= buf.length - 4`. + satisfy `0 <= offset <= buf.length - 4`. **Default:** `0`. * Returns: {integer} Reads an unsigned 32-bit integer from `buf` at the specified `offset` with @@ -2144,8 +2144,8 @@ console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`); // Prints: 12 bytes: ½ + ¼ = ¾ ``` -### buf.writeDoubleBE(value, offset) -### buf.writeDoubleLE(value, offset) +### buf.writeDoubleBE(value[, offset]) +### buf.writeDoubleLE(value[, offset]) * `value` {string|Buffer|Uint8Array|integer} What to search for. -* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`. +* `byteOffset` {integer} Where to begin searching in `buf`. If negative, then + offset is calculated from the end of `buf`. **Default:** `0`. * `encoding` {string} If `value` is a string, this is its encoding. **Default:** `'utf8'`. * Returns: {boolean} `true` if `value` was found in `buf`, `false` otherwise. @@ -1321,7 +1322,8 @@ changes: --> * `value` {string|Buffer|Uint8Array|integer} What to search for. -* `byteOffset` {integer} Where to begin searching in `buf`. **Default:** `0`. +* `byteOffset` {integer} Where to begin searching in `buf`. If negative, then + offset is calculated from the end of `buf`. **Default:** `0`. * `encoding` {string} If `value` is a string, this is the encoding used to determine the binary representation of the string that will be searched for in `buf`. **Default:** `'utf8'`. @@ -1423,8 +1425,9 @@ changes: --> * `value` {string|Buffer|Uint8Array|integer} What to search for. -* `byteOffset` {integer} Where to begin searching in `buf`. - **Default:** [`buf.length`]` - 1`. +* `byteOffset` {integer} Where to begin searching in `buf`. If negative, then + offset is calculated from the end of `buf`. **Default:** + [`buf.length`]` - 1`. * `encoding` {string} If `value` is a string, this is the encoding used to determine the binary representation of the string that will be searched for in `buf`. **Default:** `'utf8'`. From fbf4c705b9a3e0178190763158b3482dfff63e11 Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Sat, 30 Mar 2019 19:59:44 +0200 Subject: [PATCH 09/10] doc: unify periods in comments "Prints: ..." comments were excepted to avoid confusion. --- doc/api/buffer.md | 98 +++++++++++++++++++++++------------------------ 1 file changed, 49 insertions(+), 49 deletions(-) diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 6ea304128de4c6..4f6e909a579daf 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -230,9 +230,9 @@ const arr = new Uint16Array(2); arr[0] = 5000; arr[1] = 4000; -// Copies the contents of `arr` +// Copies the contents of `arr`. const buf1 = Buffer.from(arr); -// Shares memory with `arr` +// Shares memory with `arr`. const buf2 = Buffer.from(arr.buffer); console.log(buf1); @@ -322,7 +322,7 @@ changes: Allocates a new `Buffer` using an `array` of octets. ```js -// Creates a new Buffer containing the UTF-8 bytes of the string 'buffer' +// Creates a new Buffer containing the UTF-8 bytes of the string 'buffer'. const buf = new Buffer([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]); ``` @@ -370,13 +370,13 @@ const arr = new Uint16Array(2); arr[0] = 5000; arr[1] = 4000; -// Shares memory with `arr` +// Shares memory with `arr`. const buf = new Buffer(arr.buffer); console.log(buf); // Prints: -// Changing the original Uint16Array changes the Buffer also +// Changing the original Uint16Array changes the Buffer also. arr[1] = 6000; console.log(buf); @@ -585,7 +585,7 @@ initialized*. The contents of the newly created `Buffer` are unknown and const buf = Buffer.allocUnsafe(10); console.log(buf); -// Prints: (contents may vary): +// Prints (contents may vary): buf.fill(0); @@ -638,16 +638,16 @@ to create an un-pooled `Buffer` instance using `Buffer.allocUnsafeSlow()` and then copying out the relevant bits. ```js -// Need to keep around a few small chunks of memory +// Need to keep around a few small chunks of memory. const store = []; socket.on('readable', () => { let data; while (null !== (data = readable.read())) { - // Allocate for retained data + // Allocate for retained data. const sb = Buffer.allocUnsafeSlow(10); - // Copy the data into the new allocation + // Copy the data into the new allocation. data.copy(sb, 0, 0, 10); store.push(sb); @@ -722,7 +722,7 @@ const arr = [buf1, buf2]; console.log(arr.sort(Buffer.compare)); // Prints: [ , ] -// (This result is equal to: [buf2, buf1]) +// (This result is equal to: [buf2, buf1].) ``` ### Class Method: Buffer.concat(list[, totalLength]) @@ -784,7 +784,7 @@ added: v5.10.0 Allocates a new `Buffer` using an `array` of octets. ```js -// Creates a new Buffer containing UTF-8 bytes of the string 'buffer' +// Creates a new Buffer containing UTF-8 bytes of the string 'buffer'. const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]); ``` @@ -813,13 +813,13 @@ const arr = new Uint16Array(2); arr[0] = 5000; arr[1] = 4000; -// Shares memory with `arr` +// Shares memory with `arr`. const buf = Buffer.from(arr.buffer); console.log(buf); // Prints: -// Changing the original Uint16Array changes the Buffer also +// Changing the original Uint16Array changes the Buffer also. arr[1] = 6000; console.log(buf); @@ -1076,7 +1076,7 @@ console.log(buf2.compare(buf3)); // Prints: 1 console.log([buf1, buf2, buf3].sort(Buffer.compare)); // Prints: [ , , ] -// (This result is equal to: [buf1, buf3, buf2]) +// (This result is equal to: [buf1, buf3, buf2].) ``` The optional `targetStart`, `targetEnd`, `sourceStart`, and `sourceEnd` @@ -1121,11 +1121,11 @@ const buf1 = Buffer.allocUnsafe(26); const buf2 = Buffer.allocUnsafe(26).fill('!'); for (let i = 0; i < 26; i++) { - // 97 is the decimal ASCII value for 'a' + // 97 is the decimal ASCII value for 'a'. buf1[i] = i + 97; } -// Copy `buf1` bytes 16 through 19 into `buf2` starting at byte 8 of `buf2` +// Copy `buf1` bytes 16 through 19 into `buf2` starting at byte 8 of `buf2`. buf1.copy(buf2, 8, 16, 20); console.log(buf2.toString('ascii', 0, 25)); @@ -1139,7 +1139,7 @@ console.log(buf2.toString('ascii', 0, 25)); const buf = Buffer.allocUnsafe(26); for (let i = 0; i < 26; i++) { - // 97 is the decimal ASCII value for 'a' + // 97 is the decimal ASCII value for 'a'. buf[i] = i + 97; } @@ -1374,13 +1374,13 @@ behavior matches [`String#indexOf()`]. ```js const b = Buffer.from('abcdef'); -// Passing a value that's a number, but not a valid byte -// Prints: 2, equivalent to searching for 99 or 'c' +// Passing a value that's a number, but not a valid byte. +// Prints: 2, equivalent to searching for 99 or 'c'. console.log(b.indexOf(99.9)); console.log(b.indexOf(256 + 99)); -// Passing a byteOffset that coerces to NaN or 0 -// Prints: 1, searching the whole buffer +// Passing a byteOffset that coerces to NaN or 0. +// Prints: 1, searching the whole buffer. console.log(b.indexOf('b', undefined)); console.log(b.indexOf('b', {})); console.log(b.indexOf('b', null)); @@ -1474,18 +1474,18 @@ This behavior matches [`String#lastIndexOf()`]. ```js const b = Buffer.from('abcdef'); -// Passing a value that's a number, but not a valid byte -// Prints: 2, equivalent to searching for 99 or 'c' +// Passing a value that's a number, but not a valid byte. +// Prints: 2, equivalent to searching for 99 or 'c'. console.log(b.lastIndexOf(99.9)); console.log(b.lastIndexOf(256 + 99)); -// Passing a byteOffset that coerces to NaN -// Prints: 1, searching the whole buffer +// Passing a byteOffset that coerces to NaN. +// Prints: 1, searching the whole buffer. console.log(b.lastIndexOf('b', undefined)); console.log(b.lastIndexOf('b', {})); -// Passing a byteOffset that coerces to 0 -// Prints: -1, equivalent to passing 0 +// Passing a byteOffset that coerces to 0. +// Prints: -1, equivalent to passing 0. console.log(b.lastIndexOf('b', null)); console.log(b.lastIndexOf('b', [])); ``` @@ -1571,7 +1571,7 @@ console.log(buf.readDoubleBE(0)); console.log(buf.readDoubleLE(0)); // Prints: 5.447603722011605e-270 console.log(buf.readDoubleLE(1)); -// Throws ERR_OUT_OF_RANGE +// Throws ERR_OUT_OF_RANGE. ``` ### buf.readFloatBE([offset]) @@ -1601,7 +1601,7 @@ console.log(buf.readFloatBE(0)); console.log(buf.readFloatLE(0)); // Prints: 1.539989614439558e-36 console.log(buf.readFloatLE(1)); -// Throws ERR_OUT_OF_RANGE +// Throws ERR_OUT_OF_RANGE. ``` ### buf.readInt8([offset]) @@ -1630,7 +1630,7 @@ console.log(buf.readInt8(0)); console.log(buf.readInt8(1)); // Prints: 5 console.log(buf.readInt8(2)); -// Throws ERR_OUT_OF_RANGE +// Throws ERR_OUT_OF_RANGE. ``` ### buf.readInt16BE([offset]) @@ -1662,7 +1662,7 @@ console.log(buf.readInt16BE(0)); console.log(buf.readInt16LE(0)); // Prints: 1280 console.log(buf.readInt16LE(1)); -// Throws ERR_OUT_OF_RANGE +// Throws ERR_OUT_OF_RANGE. ``` ### buf.readInt32BE([offset]) @@ -1694,7 +1694,7 @@ console.log(buf.readInt32BE(0)); console.log(buf.readInt32LE(0)); // Prints: 83886080 console.log(buf.readInt32LE(1)); -// Throws ERR_OUT_OF_RANGE +// Throws ERR_OUT_OF_RANGE. ``` ### buf.readIntBE(offset, byteLength) @@ -1726,9 +1726,9 @@ console.log(buf.readIntLE(0, 6).toString(16)); console.log(buf.readIntBE(0, 6).toString(16)); // Prints: 1234567890ab console.log(buf.readIntBE(1, 6).toString(16)); -// Throws ERR_OUT_OF_RANGE +// Throws ERR_OUT_OF_RANGE. console.log(buf.readIntBE(1, 0).toString(16)); -// Throws ERR_OUT_OF_RANGE +// Throws ERR_OUT_OF_RANGE. ``` ### buf.readUInt8([offset]) @@ -1755,7 +1755,7 @@ console.log(buf.readUInt8(0)); console.log(buf.readUInt8(1)); // Prints: 254 console.log(buf.readUInt8(2)); -// Throws ERR_OUT_OF_RANGE +// Throws ERR_OUT_OF_RANGE. ``` ### buf.readUInt16BE([offset]) @@ -1789,7 +1789,7 @@ console.log(buf.readUInt16BE(1).toString(16)); console.log(buf.readUInt16LE(1).toString(16)); // Prints: 5634 console.log(buf.readUInt16LE(2).toString(16)); -// Throws ERR_OUT_OF_RANGE +// Throws ERR_OUT_OF_RANGE. ``` ### buf.readUInt32BE([offset]) @@ -1819,7 +1819,7 @@ console.log(buf.readUInt32BE(0).toString(16)); console.log(buf.readUInt32LE(0).toString(16)); // Prints: 78563412 console.log(buf.readUInt32LE(1).toString(16)); -// Throws ERR_OUT_OF_RANGE +// Throws ERR_OUT_OF_RANGE. ``` ### buf.readUIntBE(offset, byteLength) @@ -1851,7 +1851,7 @@ console.log(buf.readUIntBE(0, 6).toString(16)); console.log(buf.readUIntLE(0, 6).toString(16)); // Prints: ab9078563412 console.log(buf.readUIntBE(1, 6).toString(16)); -// Throws ERR_OUT_OF_RANGE +// Throws ERR_OUT_OF_RANGE. ``` ### buf.slice([start[, end]]) @@ -1889,7 +1889,7 @@ because the allocated memory of the two objects overlap. const buf1 = Buffer.allocUnsafe(26); for (let i = 0; i < 26; i++) { - // 97 is the decimal ASCII value for 'a' + // 97 is the decimal ASCII value for 'a'. buf1[i] = i + 97; } @@ -1912,15 +1912,15 @@ const buf = Buffer.from('buffer'); console.log(buf.slice(-6, -1).toString()); // Prints: buffe -// (Equivalent to buf.slice(0, 5)) +// (Equivalent to buf.slice(0, 5).) console.log(buf.slice(-6, -2).toString()); // Prints: buff -// (Equivalent to buf.slice(0, 4)) +// (Equivalent to buf.slice(0, 4).) console.log(buf.slice(-5, -2).toString()); // Prints: uff -// (Equivalent to buf.slice(1, 4)) +// (Equivalent to buf.slice(1, 4).) ``` ### buf.swap16() @@ -1948,7 +1948,7 @@ console.log(buf1); const buf2 = Buffer.from([0x1, 0x2, 0x3]); buf2.swap16(); -// Throws ERR_INVALID_BUFFER_SIZE +// Throws ERR_INVALID_BUFFER_SIZE. ``` One convenient use of `buf.swap16()` is to perform a fast in-place conversion @@ -1984,7 +1984,7 @@ console.log(buf1); const buf2 = Buffer.from([0x1, 0x2, 0x3]); buf2.swap32(); -// Throws ERR_INVALID_BUFFER_SIZE +// Throws ERR_INVALID_BUFFER_SIZE. ``` ### buf.swap64() @@ -2011,7 +2011,7 @@ console.log(buf1); const buf2 = Buffer.from([0x1, 0x2, 0x3]); buf2.swap64(); -// Throws ERR_INVALID_BUFFER_SIZE +// Throws ERR_INVALID_BUFFER_SIZE. ``` Note that JavaScript cannot encode 64-bit integers. This method is intended @@ -2065,7 +2065,7 @@ as [`buffer.constants.MAX_STRING_LENGTH`][]. const buf1 = Buffer.allocUnsafe(26); for (let i = 0; i < 26; i++) { - // 97 is the decimal ASCII value for 'a' + // 97 is the decimal ASCII value for 'a'. buf1[i] = i + 97; } @@ -2573,16 +2573,16 @@ pool for an indeterminate amount of time, it may be appropriate to create an un-pooled `Buffer` instance using `SlowBuffer` then copy out the relevant bits. ```js -// Need to keep around a few small chunks of memory +// Need to keep around a few small chunks of memory. const store = []; socket.on('readable', () => { let data; while (null !== (data = readable.read())) { - // Allocate for retained data + // Allocate for retained data. const sb = SlowBuffer(10); - // Copy the data into the new allocation + // Copy the data into the new allocation. data.copy(sb, 0, 0, 10); store.push(sb); From 56da51aaa2c3277dca3e888845b8ae45e1faef4c Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Sun, 31 Mar 2019 11:37:33 +0300 Subject: [PATCH 10/10] doc: unify link formatting --- doc/api/buffer.md | 234 +++++++++++++++++++++++----------------------- 1 file changed, 118 insertions(+), 116 deletions(-) diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 4f6e909a579daf..202bd841714431 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -4,13 +4,14 @@ > Stability: 2 - Stable -Prior to the introduction of [`TypedArray`], the JavaScript language had no +Prior to the introduction of [`TypedArray`][], the JavaScript language had no mechanism for reading or manipulating streams of binary data. The `Buffer` class was introduced as part of the Node.js API to enable interaction with octet streams in TCP streams, file system operations, and other contexts. -With [`TypedArray`] now available, the `Buffer` class implements the -[`Uint8Array`] API in a manner that is more optimized and suitable for Node.js. +With [`TypedArray`][] now available, the `Buffer` class implements the +[`Uint8Array`][] API in a manner that is more optimized and suitable for +Node.js. Instances of the `Buffer` class are similar to arrays of integers from `0` to `255` (other integers are coerced to this range by `& 255` operation) but @@ -62,8 +63,8 @@ differently based on what arguments are provided: `new Buffer(num)` will return a `Buffer` with initialized memory. * Passing a string, array, or `Buffer` as the first argument copies the passed object's data into the `Buffer`. -* Passing an [`ArrayBuffer`] or a [`SharedArrayBuffer`] returns a `Buffer` that - shares allocated memory with the given array buffer. +* Passing an [`ArrayBuffer`][] or a [`SharedArrayBuffer`][] returns a `Buffer` + that shares allocated memory with the given array buffer. Because the behavior of `new Buffer()` is different depending on the type of the first argument, security and reliability issues can be inadvertently introduced @@ -72,18 +73,18 @@ performed. To make the creation of `Buffer` instances more reliable and less error-prone, the various forms of the `new Buffer()` constructor have been **deprecated** -and replaced by separate `Buffer.from()`, [`Buffer.alloc()`], and -[`Buffer.allocUnsafe()`] methods. +and replaced by separate `Buffer.from()`, [`Buffer.alloc()`][], and +[`Buffer.allocUnsafe()`][] methods. *Developers should migrate all existing uses of the `new Buffer()` constructors to one of these new APIs.* -* [`Buffer.from(array)`] returns a new `Buffer` that *contains a copy* of the +* [`Buffer.from(array)`][] returns a new `Buffer` that *contains a copy* of the provided octets. * [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][`Buffer.from(arrayBuf)`] returns a new `Buffer` that *shares the same allocated memory* as the given - [`ArrayBuffer`]. -* [`Buffer.from(buffer)`] returns a new `Buffer` that *contains a copy* of the + [`ArrayBuffer`][]. +* [`Buffer.from(buffer)`][] returns a new `Buffer` that *contains a copy* of the contents of the given `Buffer`. * [`Buffer.from(string[, encoding])`][`Buffer.from(string)`] returns a new `Buffer` that *contains a copy* of the provided string. @@ -98,10 +99,10 @@ to one of these new APIs.* uninitialized, the allocated segment of memory might contain old data that is potentially sensitive. -`Buffer` instances returned by [`Buffer.allocUnsafe()`] *may* be allocated off +`Buffer` instances returned by [`Buffer.allocUnsafe()`][] *may* be allocated off a shared internal memory pool if `size` is less than or equal to half -[`Buffer.poolSize`]. Instances returned by [`Buffer.allocUnsafeSlow()`] *never* -use the shared internal memory pool. +[`Buffer.poolSize`][]. Instances returned by [`Buffer.allocUnsafeSlow()`][] +*never* use the shared internal memory pool. ### The `--zero-fill-buffers` command line option -`Buffer` instances are also [`Uint8Array`] instances. However, there are subtle -incompatibilities with [`TypedArray`]. For example, while -[`ArrayBuffer#slice()`] creates a copy of the slice, the implementation of +`Buffer` instances are also [`Uint8Array`][] instances. However, there are +subtle incompatibilities with [`TypedArray`][]. For example, while +[`ArrayBuffer#slice()`][] creates a copy of the slice, the implementation of [`Buffer#slice()`][`buf.slice()`] creates a view over the existing `Buffer` without copying, making [`Buffer#slice()`][`buf.slice()`] far more efficient. -It is also possible to create new [`TypedArray`] instances from a `Buffer` with -the following caveats: +It is also possible to create new [`TypedArray`][] instances from a `Buffer` +with the following caveats: -1. The `Buffer` object's memory is copied to the [`TypedArray`], not shared. +1. The `Buffer` object's memory is copied to the [`TypedArray`][], not shared. 2. The `Buffer` object's memory is interpreted as an array of distinct elements, and not as a byte array of the target type. That is, -`new Uint32Array(Buffer.from([1, 2, 3, 4]))` creates a 4-element [`Uint32Array`] - with elements `[1, 2, 3, 4]`, not a [`Uint32Array`] with a single element - `[0x1020304]` or `[0x4030201]`. +`new Uint32Array(Buffer.from([1, 2, 3, 4]))` creates a 4-element +[`Uint32Array`][] with elements `[1, 2, 3, 4]`, not a [`Uint32Array`][] with a +single element `[0x1020304]` or `[0x4030201]`. It is possible to create a new `Buffer` that shares the same allocated memory as -a [`TypedArray`] instance by using the `TypedArray` object's `.buffer` property. +a [`TypedArray`][] instance by using the `TypedArray` object's `.buffer` +property. ```js const arr = new Uint16Array(2); @@ -248,8 +250,8 @@ console.log(buf2); // Prints: ``` -Note that when creating a `Buffer` using a [`TypedArray`]'s `.buffer`, it is -possible to use only a portion of the underlying [`ArrayBuffer`] by passing in +Note that when creating a `Buffer` using a [`TypedArray`][]'s `.buffer`, it is +possible to use only a portion of the underlying [`ArrayBuffer`][] by passing in `byteOffset` and `length` parameters. ```js @@ -260,8 +262,8 @@ console.log(buf.length); // Prints: 16 ``` -The `Buffer.from()` and [`TypedArray.from()`] have different signatures and -implementations. Specifically, the [`TypedArray`] variants accept a second +The `Buffer.from()` and [`TypedArray.from()`][] have different signatures and +implementations. Specifically, the [`TypedArray`][] variants accept a second argument that is a mapping function that is invoked on every element of the typed array: @@ -270,8 +272,8 @@ typed array: The `Buffer.from()` method, however, does not support the use of a mapping function: -* [`Buffer.from(array)`] -* [`Buffer.from(buffer)`] +* [`Buffer.from(array)`][] +* [`Buffer.from(buffer)`][] * [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][`Buffer.from(arrayBuf)`] * [`Buffer.from(string[, encoding])`][`Buffer.from(string)`] @@ -291,8 +293,8 @@ for (const b of buf) { // 3 ``` -Additionally, the [`buf.values()`], [`buf.keys()`], and -[`buf.entries()`] methods can be used to create iterators. +Additionally, the [`buf.values()`][], [`buf.keys()`][], and +[`buf.entries()`][] methods can be used to create iterators. ## Class: Buffer @@ -315,7 +317,7 @@ changes: description: Calling this constructor emits a deprecation warning now. --> -> Stability: 0 - Deprecated: Use [`Buffer.from(array)`] instead. +> Stability: 0 - Deprecated: Use [`Buffer.from(array)`][] instead. * `array` {integer[]} An array of bytes to copy from. @@ -350,16 +352,16 @@ changes: > [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][`Buffer.from(arrayBuf)`] > instead. -* `arrayBuffer` {ArrayBuffer|SharedArrayBuffer} An [`ArrayBuffer`], - [`SharedArrayBuffer`] or the `.buffer` property of a [`TypedArray`]. +* `arrayBuffer` {ArrayBuffer|SharedArrayBuffer} An [`ArrayBuffer`][], + [`SharedArrayBuffer`][] or the `.buffer` property of a [`TypedArray`][]. * `byteOffset` {integer} Index of first byte to expose. **Default:** `0`. * `length` {integer} Number of bytes to expose. **Default:** `arrayBuffer.length - byteOffset`. -This creates a view of the [`ArrayBuffer`] or [`SharedArrayBuffer`] without +This creates a view of the [`ArrayBuffer`][] or [`SharedArrayBuffer`][] without copying the underlying memory. For example, when passed a reference to the -`.buffer` property of a [`TypedArray`] instance, the newly created `Buffer` will -share the same allocated memory as the [`TypedArray`]. +`.buffer` property of a [`TypedArray`][] instance, the newly created `Buffer` +will share the same allocated memory as the [`TypedArray`][]. The optional `byteOffset` and `length` arguments specify a memory range within the `arrayBuffer` that will be shared by the `Buffer`. @@ -399,10 +401,10 @@ changes: description: Calling this constructor emits a deprecation warning now. --> -> Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`] instead. +> Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`][] instead. -* `buffer` {Buffer|Uint8Array} An existing `Buffer` or [`Uint8Array`] from which - to copy data. +* `buffer` {Buffer|Uint8Array} An existing `Buffer` or [`Uint8Array`][] from + which to copy data. Copies the passed `buffer` data onto a new `Buffer` instance. @@ -438,14 +440,14 @@ changes: description: Calling this constructor emits a deprecation warning now. --> -> Stability: 0 - Deprecated: Use [`Buffer.alloc()`] instead (also see -> [`Buffer.allocUnsafe()`]). +> Stability: 0 - Deprecated: Use [`Buffer.alloc()`][] instead (also see +> [`Buffer.allocUnsafe()`][]). * `size` {integer} The desired length of the new `Buffer`. Allocates a new `Buffer` of `size` bytes. If `size` is larger than -[`buffer.constants.MAX_LENGTH`] or smaller than 0, [`ERR_INVALID_OPT_VALUE`] is -thrown. A zero-length `Buffer` is created if `size` is 0. +[`buffer.constants.MAX_LENGTH`][] or smaller than 0, [`ERR_INVALID_OPT_VALUE`][] +is thrown. A zero-length `Buffer` is created if `size` is 0. Prior to Node.js 8.0.0, the underlying memory for `Buffer` instances created in this way is *not initialized*. The contents of a newly created @@ -532,8 +534,8 @@ console.log(buf); ``` If `size` is larger than -[`buffer.constants.MAX_LENGTH`] or smaller than 0, [`ERR_INVALID_OPT_VALUE`] is -thrown. A zero-length `Buffer` is created if `size` is 0. +[`buffer.constants.MAX_LENGTH`][] or smaller than 0, [`ERR_INVALID_OPT_VALUE`][] +is thrown. A zero-length `Buffer` is created if `size` is 0. If `fill` is specified, the allocated `Buffer` will be initialized by calling [`buf.fill(fill)`][`buf.fill()`]. @@ -555,8 +557,8 @@ console.log(buf); // Prints: ``` -Calling [`Buffer.alloc()`] can be significantly slower than the alternative -[`Buffer.allocUnsafe()`] but ensures that the newly created `Buffer` instance +Calling [`Buffer.alloc()`][] can be significantly slower than the alternative +[`Buffer.allocUnsafe()`][] but ensures that the newly created `Buffer` instance contents will *never contain sensitive data*. A `TypeError` will be thrown if `size` is not a number. @@ -573,12 +575,12 @@ changes: * `size` {integer} The desired length of the new `Buffer`. Allocates a new `Buffer` of `size` bytes. If `size` is larger than -[`buffer.constants.MAX_LENGTH`] or smaller than 0, [`ERR_INVALID_OPT_VALUE`] is -thrown. A zero-length `Buffer` is created if `size` is 0. +[`buffer.constants.MAX_LENGTH`][] or smaller than 0, [`ERR_INVALID_OPT_VALUE`][] +is thrown. A zero-length `Buffer` is created if `size` is 0. The underlying memory for `Buffer` instances created in this way is *not initialized*. The contents of the newly created `Buffer` are unknown and -*may contain sensitive data*. Use [`Buffer.alloc()`] instead to initialize +*may contain sensitive data*. Use [`Buffer.alloc()`][] instead to initialize `Buffer` instances with zeroes. ```js @@ -596,18 +598,18 @@ console.log(buf); A `TypeError` will be thrown if `size` is not a number. Note that the `Buffer` module pre-allocates an internal `Buffer` instance of -size [`Buffer.poolSize`] that is used as a pool for the fast allocation of new -`Buffer` instances created using [`Buffer.allocUnsafe()`] and the deprecated +size [`Buffer.poolSize`][] that is used as a pool for the fast allocation of new +`Buffer` instances created using [`Buffer.allocUnsafe()`][] and the deprecated `new Buffer(size)` constructor only when `size` is less than or equal to -`Buffer.poolSize >> 1` (floor of [`Buffer.poolSize`] divided by two). +`Buffer.poolSize >> 1` (floor of [`Buffer.poolSize`][] divided by two). Use of this pre-allocated internal memory pool is a key difference between calling `Buffer.alloc(size, fill)` vs. `Buffer.allocUnsafe(size).fill(fill)`. Specifically, `Buffer.alloc(size, fill)` will *never* use the internal `Buffer` pool, while `Buffer.allocUnsafe(size).fill(fill)` *will* use the internal -`Buffer` pool if `size` is less than or equal to half [`Buffer.poolSize`]. The +`Buffer` pool if `size` is less than or equal to half [`Buffer.poolSize`][]. The difference is subtle but can be important when an application requires the -additional performance that [`Buffer.allocUnsafe()`] provides. +additional performance that [`Buffer.allocUnsafe()`][] provides. ### Class Method: Buffer.allocUnsafeSlow(size) -* `list` {Buffer[] | Uint8Array[]} List of `Buffer` or [`Uint8Array`] instances - to concat. +* `list` {Buffer[] | Uint8Array[]} List of `Buffer` or [`Uint8Array`][] + instances to concat. * `totalLength` {integer} Total length of the `Buffer` instances in `list` when concatenated. * Returns: {Buffer} @@ -796,16 +798,16 @@ appropriate for `Buffer.from()` variants. added: v5.10.0 --> -* `arrayBuffer` {ArrayBuffer|SharedArrayBuffer} An [`ArrayBuffer`], - [`SharedArrayBuffer`], or the `.buffer` property of a [`TypedArray`]. +* `arrayBuffer` {ArrayBuffer|SharedArrayBuffer} An [`ArrayBuffer`][], + [`SharedArrayBuffer`][], or the `.buffer` property of a [`TypedArray`][]. * `byteOffset` {integer} Index of first byte to expose. **Default:** `0`. * `length` {integer} Number of bytes to expose. **Default:** `arrayBuffer.length - byteOffset`. -This creates a view of the [`ArrayBuffer`] without copying the underlying +This creates a view of the [`ArrayBuffer`][] without copying the underlying memory. For example, when passed a reference to the `.buffer` property of a -[`TypedArray`] instance, the newly created `Buffer` will share the same -allocated memory as the [`TypedArray`]. +[`TypedArray`][] instance, the newly created `Buffer` will share the same +allocated memory as the [`TypedArray`][]. ```js const arr = new Uint16Array(2); @@ -837,16 +839,16 @@ console.log(buf.length); // Prints: 2 ``` -A `TypeError` will be thrown if `arrayBuffer` is not an [`ArrayBuffer`] or a -[`SharedArrayBuffer`] or other type appropriate for `Buffer.from()` variants. +A `TypeError` will be thrown if `arrayBuffer` is not an [`ArrayBuffer`][] or a +[`SharedArrayBuffer`][] or other type appropriate for `Buffer.from()` variants. ### Class Method: Buffer.from(buffer) -* `buffer` {Buffer|Uint8Array} An existing `Buffer` or [`Uint8Array`] from which - to copy data. +* `buffer` {Buffer|Uint8Array} An existing `Buffer` or [`Uint8Array`][] from + which to copy data. Copies the passed `buffer` data onto a new `Buffer` instance. @@ -1039,7 +1041,7 @@ changes: description: Additional parameters for specifying offsets are supported now. --> -* `target` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`] with which to +* `target` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`][] with which to compare `buf`. * `targetStart` {integer} The offset within `target` at which to begin comparison. **Default:** `0`. @@ -1048,7 +1050,7 @@ changes: * `sourceStart` {integer} The offset within `buf` at which to begin comparison. **Default:** `0`. * `sourceEnd` {integer} The offset within `buf` at which to end comparison - (not inclusive). **Default:** [`buf.length`]. + (not inclusive). **Default:** [`buf.length`][]. * Returns: {integer} Compares `buf` with `target` and returns a number indicating whether `buf` @@ -1095,7 +1097,7 @@ console.log(buf1.compare(buf2, 5, 6, 5)); // Prints: 1 ``` -[`ERR_OUT_OF_RANGE`] is thrown if `targetStart < 0`, `sourceStart < 0`, +[`ERR_OUT_OF_RANGE`][] is thrown if `targetStart < 0`, `sourceStart < 0`, `targetEnd > target.byteLength`, or `sourceEnd > source.byteLength`. ### buf.copy(target[, targetStart[, sourceStart[, sourceEnd]]]) @@ -1103,13 +1105,13 @@ console.log(buf1.compare(buf2, 5, 6, 5)); added: v0.1.90 --> -* `target` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`] to copy into. +* `target` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`][] to copy into. * `targetStart` {integer} The offset within `target` at which to begin writing. **Default:** `0`. * `sourceStart` {integer} The offset within `buf` from which to begin copying. **Default:** `0`. * `sourceEnd` {integer} The offset within `buf` at which to stop copying (not - inclusive). **Default:** [`buf.length`]. + inclusive). **Default:** [`buf.length`][]. * Returns: {integer} The number of bytes copied. Copies data from a region of `buf` to a region in `target` even if the `target` @@ -1156,8 +1158,8 @@ added: v1.1.0 * Returns: {Iterator} -Creates and returns an [iterator] of `[index, byte]` pairs from the contents of -`buf`. +Creates and returns an [iterator][] of `[index, byte]` pairs from the contents +of `buf`. ```js // Log the entire contents of a `Buffer`. @@ -1185,7 +1187,7 @@ changes: description: The arguments can now be `Uint8Array`s. --> -* `otherBuffer` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`] with which to +* `otherBuffer` {Buffer|Uint8Array} A `Buffer` or [`Uint8Array`][] with which to compare `buf`. * Returns: {boolean} @@ -1230,7 +1232,7 @@ changes: * `offset` {integer} Number of bytes to skip before starting to fill `buf`. **Default:** `0`. * `end` {integer} Where to stop filling `buf` (not inclusive). **Default:** - [`buf.length`]. + [`buf.length`][]. * `encoding` {string} The encoding for `value` if `value` is a string. **Default:** `'utf8'`. * Returns: {Buffer} A reference to `buf`. @@ -1334,8 +1336,8 @@ If `value` is: * a string, `value` is interpreted according to the character encoding in `encoding`. - * a `Buffer` or [`Uint8Array`], `value` will be used in its entirety. - To compare a partial `Buffer`, use [`buf.slice()`]. + * a `Buffer` or [`Uint8Array`][], `value` will be used in its entirety. + To compare a partial `Buffer`, use [`buf.slice()`][]. * a number, `value` will be interpreted as an unsigned 8-bit integer value between `0` and `255`. @@ -1369,7 +1371,7 @@ an integer between 0 and 255. If `byteOffset` is not a number, it will be coerced to a number. If the result of coercion is `NaN` or `0`, then the entire buffer will be searched. This -behavior matches [`String#indexOf()`]. +behavior matches [`String#indexOf()`][]. ```js const b = Buffer.from('abcdef'); @@ -1398,7 +1400,7 @@ added: v1.1.0 * Returns: {Iterator} -Creates and returns an [iterator] of `buf` keys (indices). +Creates and returns an [iterator][] of `buf` keys (indices). ```js const buf = Buffer.from('buffer'); @@ -1427,14 +1429,14 @@ changes: * `value` {string|Buffer|Uint8Array|integer} What to search for. * `byteOffset` {integer} Where to begin searching in `buf`. If negative, then offset is calculated from the end of `buf`. **Default:** - [`buf.length`]` - 1`. + [`buf.length`][]` - 1`. * `encoding` {string} If `value` is a string, this is the encoding used to determine the binary representation of the string that will be searched for in `buf`. **Default:** `'utf8'`. * Returns: {integer} The index of the last occurrence of `value` in `buf`, or `-1` if `buf` does not contain `value`. -Identical to [`buf.indexOf()`], except the last occurrence of `value` is found +Identical to [`buf.indexOf()`][], except the last occurrence of `value` is found rather than the first occurrence. ```js @@ -1469,7 +1471,7 @@ an integer between 0 and 255. If `byteOffset` is not a number, it will be coerced to a number. Any arguments that coerce to `NaN`, like `{}` or `undefined`, will search the whole buffer. -This behavior matches [`String#lastIndexOf()`]. +This behavior matches [`String#lastIndexOf()`][]. ```js const b = Buffer.from('abcdef'); @@ -1519,7 +1521,7 @@ console.log(buf.length); While the `length` property is not immutable, changing the value of `length` can result in undefined and inconsistent behavior. Applications that wish to modify the length of a `Buffer` should therefore treat `length` as read-only and -use [`buf.slice()`] to create a new `Buffer`. +use [`buf.slice()`][] to create a new `Buffer`. ```js let buf = Buffer.allocUnsafe(10); @@ -1540,7 +1542,7 @@ console.log(buf.length); deprecated: v8.0.0 --> -> Stability: 0 - Deprecated: Use [`buf.buffer`] instead. +> Stability: 0 - Deprecated: Use [`buf.buffer`][] instead. The `buf.parent` property is a deprecated alias for `buf.buffer`. @@ -1870,14 +1872,14 @@ changes: * `start` {integer} Where the new `Buffer` will start. **Default:** `0`. * `end` {integer} Where the new `Buffer` will end (not inclusive). - **Default:** [`buf.length`]. + **Default:** [`buf.length`][]. * Returns: {Buffer} Returns a new `Buffer` that references the same memory as the original, but offset and cropped by the `start` and `end` indices. -Specifying `end` greater than [`buf.length`] will return the same result as -that of `end` equal to [`buf.length`]. +Specifying `end` greater than [`buf.length`][] will return the same result as +that of `end` equal to [`buf.length`][]. Modifying the new `Buffer` slice will modify the memory in the original `Buffer` because the allocated memory of the two objects overlap. @@ -1931,8 +1933,8 @@ added: v5.10.0 * Returns: {Buffer} A reference to `buf`. Interprets `buf` as an array of unsigned 16-bit integers and swaps the -byte order *in-place*. Throws [`ERR_INVALID_BUFFER_SIZE`] if [`buf.length`] is -not a multiple of 2. +byte order *in-place*. Throws [`ERR_INVALID_BUFFER_SIZE`][] if [`buf.length`][] +is not a multiple of 2. ```js const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]); @@ -1967,8 +1969,8 @@ added: v5.10.0 * Returns: {Buffer} A reference to `buf`. Interprets `buf` as an array of unsigned 32-bit integers and swaps the -byte order *in-place*. Throws [`ERR_INVALID_BUFFER_SIZE`] if [`buf.length`] is -not a multiple of 4. +byte order *in-place*. Throws [`ERR_INVALID_BUFFER_SIZE`][] if [`buf.length`][] +is not a multiple of 4. ```js const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]); @@ -1995,7 +1997,7 @@ added: v6.3.0 * Returns: {Buffer} A reference to `buf`. Interprets `buf` as an array of 64-bit numbers and swaps byte order *in-place*. -Throws [`ERR_INVALID_BUFFER_SIZE`] if [`buf.length`] is not a multiple of 8. +Throws [`ERR_INVALID_BUFFER_SIZE`][] if [`buf.length`][] is not a multiple of 8. ```js const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]); @@ -2024,7 +2026,7 @@ added: v0.9.2 * Returns: {Object} -Returns a JSON representation of `buf`. [`JSON.stringify()`] implicitly calls +Returns a JSON representation of `buf`. [`JSON.stringify()`][] implicitly calls this function when stringifying a `Buffer` instance. ```js @@ -2052,7 +2054,7 @@ added: v0.1.90 * `encoding` {string} The character encoding to use. **Default:** `'utf8'`. * `start` {integer} The byte offset to start decoding at. **Default:** `0`. * `end` {integer} The byte offset to stop decoding at (not inclusive). - **Default:** [`buf.length`]. + **Default:** [`buf.length`][]. * Returns: {string} Decodes `buf` to a string according to the specified character encoding in @@ -2091,7 +2093,7 @@ added: v1.1.0 * Returns: {Iterator} -Creates and returns an [iterator] for `buf` values (bytes). This function is +Creates and returns an [iterator][] for `buf` values (bytes). This function is called automatically when a `Buffer` is used in a `for..of` statement. ```js @@ -2498,7 +2500,7 @@ added: v0.5.4 Returns the maximum number of bytes that will be returned when `buf.inspect()` is called. This can be overridden by user modules. See -[`util.inspect()`] for more details on `buf.inspect()` behavior. +[`util.inspect()`][] for more details on `buf.inspect()` behavior. Note that this is a property on the `buffer` module returned by `require('buffer')`, not on the `Buffer` global or a `Buffer` instance. @@ -2560,7 +2562,7 @@ Note that this is a property on the `buffer` module returned by deprecated: v6.0.0 --> -> Stability: 0 - Deprecated: Use [`Buffer.allocUnsafeSlow()`] instead. +> Stability: 0 - Deprecated: Use [`Buffer.allocUnsafeSlow()`][] instead. Returns an un-pooled `Buffer`. @@ -2598,13 +2600,13 @@ has observed undue memory retention in their applications. deprecated: v6.0.0 --> -> Stability: 0 - Deprecated: Use [`Buffer.allocUnsafeSlow()`] instead. +> Stability: 0 - Deprecated: Use [`Buffer.allocUnsafeSlow()`][] instead. * `size` {integer} The desired length of the new `SlowBuffer`. Allocates a new `Buffer` of `size` bytes. If `size` is larger than -[`buffer.constants.MAX_LENGTH`] or smaller than 0, [`ERR_INVALID_OPT_VALUE`] is -thrown. A zero-length `Buffer` is created if `size` is 0. +[`buffer.constants.MAX_LENGTH`][] or smaller than 0, [`ERR_INVALID_OPT_VALUE`][] +is thrown. A zero-length `Buffer` is created if `size` is 0. The underlying memory for `SlowBuffer` instances is *not initialized*. The contents of a newly created `SlowBuffer` are unknown and may contain sensitive