From aeac623141a7a58c691d0fb638ae8002eeb34e7a Mon Sep 17 00:00:00 2001 From: Timothy Gu Date: Mon, 25 Jan 2016 19:05:43 -0800 Subject: [PATCH] doc: make buffer methods styles consistent - Maintain alphabetical order - Add documentation for `offset` and `value` where absent - Add return value documentation where absent - Remove redundant "Optional" - Move defaults to parameter enumerations PR-URL: https://github.com/nodejs/node/pull/4873 Reviewed-By: James M Snell --- doc/api/buffer.markdown | 428 ++++++++++++++++++++++++------------------------ 1 file changed, 218 insertions(+), 210 deletions(-) diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown index 8be347a..9296c5b 100644 --- a/doc/api/buffer.markdown +++ b/doc/api/buffer.markdown @@ -150,7 +150,7 @@ It can be constructed in a variety of ways. ### new Buffer(array) -* `array` Array +* `array` {Array} Allocates a new Buffer using an `array` of octets. @@ -205,7 +205,7 @@ console.log(buf); ### new Buffer(size) -* `size` Number +* `size` {Number} Allocates a new Buffer of `size` bytes. The `size` must be less than or equal to the value of `require('buffer').kMaxLength` (on 64-bit @@ -230,12 +230,11 @@ console.log(buf); ### new Buffer(str[, encoding]) -* `str` String - string to encode. -* `encoding` String - encoding to use, Optional. +* `str` {String} String to encode. +* `encoding` {String} Default: `'utf8'` Creates a new Buffer containing the given JavaScript string `str`. If provided, the `encoding` parameter identifies the strings character encoding. -If not provided, `encoding` defaults to `'utf8'`. ```js const buf1 = new Buffer('this is a tést'); @@ -251,13 +250,13 @@ console.log(buf2.toString()); ### Class Method: Buffer.byteLength(string[, encoding]) -* `string` String -* `encoding` String, Optional, Default: 'utf8' -* Return: Number +* `string` {String} +* `encoding` {String} Default: `'utf8'` +* Return: {Number} -Returns the actual byte length of a string. If not specified, `encoding` -defaults to `'utf8'`. This is not the same as [`String.prototype.length`][] -since that returns the number of *characters* in a string. +Returns the actual byte length of a string. This is not the same as +[`String.prototype.length`][] since that returns the number of *characters* in +a string. Example: @@ -274,6 +273,7 @@ console.log(`${str}: ${str.length} characters, ` + * `buf1` {Buffer} * `buf2` {Buffer} +* Return: {Number} Compares `buf1` to `buf2` typically for the purpose of sorting arrays of Buffers. This is equivalent is calling `buf1.compare(buf2)`. @@ -287,6 +287,7 @@ arr.sort(Buffer.compare); * `list` {Array} List of Buffer objects to concat * `totalLength` {Number} Total length of the Buffers in the list when concatenated +* Return: {Buffer} Returns a new Buffer which is the result of concatenating all the Buffers in the `list` together. @@ -318,85 +319,19 @@ console.log(bufA.length); ### Class Method: Buffer.isBuffer(obj) -* `obj` Object -* Return: Boolean +* `obj` {Object} +* Return: {Boolean} Returns 'true' if `obj` is a Buffer. ### Class Method: Buffer.isEncoding(encoding) * `encoding` {String} The encoding string to test +* Return: {Boolean} Returns true if the `encoding` is a valid encoding argument, or false otherwise. -### buffer.entries() - -Creates and returns an [iterator][] of `[index, byte]` pairs from the Buffer -contents. - -```js -const buf = new Buffer('buffer'); -for (var pair of buf.entries()) { - console.log(pair); -} -// prints: -// [0, 98] -// [1, 117] -// [2, 102] -// [3, 102] -// [4, 101] -// [5, 114] -``` - -### buffer.keys() - -Creates and returns an [iterator][] of Buffer keys (indices). - -```js -const buf = new Buffer('buffer'); -for (var key of buf.keys()) { - console.log(key); -} -// prints: -// 0 -// 1 -// 2 -// 3 -// 4 -// 5 -``` - -### buffer.values() - -Creates and returns an [iterator][] for Buffer values (bytes). This function is -called automatically when the Buffer is used in a `for..of` statement. - -```js -const buf = new Buffer('buffer'); -for (var value of buf.values()) { - console.log(value); -} -// prints: -// 98 -// 117 -// 102 -// 102 -// 101 -// 114 - -for (var value of buf) { - console.log(value); -} -// prints: -// 98 -// 117 -// 102 -// 102 -// 101 -// 114 -``` - ### buf[index] @@ -423,6 +358,7 @@ console.log(buf); ### buf.compare(otherBuffer) * `otherBuffer` {Buffer} +* Return: {Number} Compares two Buffer instances and returns a number indicating whether `buf` comes before, after, or is the same as the `otherBuffer` in sort order. @@ -454,17 +390,14 @@ console.log(buf2.compare(buf3)); ### buf.copy(targetBuffer[, targetStart][, sourceStart][, sourceEnd]) -* `targetBuffer` Buffer object - Buffer to copy into -* `targetStart` Number, Optional, Default: 0 -* `sourceStart` Number, Optional, Default: 0 -* `sourceEnd` Number, Optional, Default: `buffer.length` +* `targetBuffer` {Buffer} Buffer to copy into +* `targetStart` {Number} Default: 0 +* `sourceStart` {Number} Default: 0 +* `sourceEnd` {Number} Default: `buffer.length` +* Return: {Number} The number of bytes copied. Copies data from a region of this Buffer to a region in the target Buffer even -if the target memory region overlaps with the source. If `undefined`, the -`targetStart` and `sourceStart` parameters default to `0` while `sourceEnd` -defaults to `buffer.length`. - -Returns the number of bytes copied. +if the target memory region overlaps with the source. Example: build two Buffers, then copy `buf1` from byte 16 through byte 19 into `buf2`, starting at the 8th byte in `buf2`. @@ -498,9 +431,31 @@ console.log(buf.toString()); // efghijghijklmnopqrstuvwxyz ``` +### buf.entries() + +* Return: {Iterator} + +Creates and returns an [iterator][] of `[index, byte]` pairs from the Buffer +contents. + +```js +const buf = new Buffer('buffer'); +for (var pair of buf.entries()) { + console.log(pair); +} +// prints: +// [0, 98] +// [1, 117] +// [2, 102] +// [3, 102] +// [4, 101] +// [5, 114] +``` + ### buf.equals(otherBuffer) * `otherBuffer` {Buffer} +* Return: {Boolean} Returns a boolean indicating whether `this` and `otherBuffer` have exactly the same bytes. @@ -518,13 +473,14 @@ console.log(buf1.equals(buf3)); ### buf.fill(value[, offset][, end]) -* `value` -* `offset` Number, Optional -* `end` Number, Optional +* `value` {String or Number} +* `offset` {Number} Default: 0 +* `end` {Number} Default: `buffer.length` +* Return: {Buffer} -Fills the Buffer with the specified value. If the `offset` (defaults to `0`) -and `end` (defaults to `buffer.length`) are not given it will fill the entire -Buffer. The method returns a reference to the Buffer so calls can be chained. +Fills the Buffer with the specified value. If the `offset` and `end` are not +given it will fill the entire Buffer. The method returns a reference to the +Buffer so calls can be chained. ```js const b = new Buffer(50).fill('h'); @@ -534,10 +490,10 @@ console.log(b.toString()); ### buf.indexOf(value[, byteOffset][, encoding]) -* `value` String, Buffer or Number -* `byteOffset` Number, Optional, Default: 0 -* `encoding` String, Optional, Default: `utf8` -* Return: Number +* `value` {String, Buffer or Number} +* `byteOffset` {Number} Default: 0 +* `encoding` {String} Default: `'utf8'` +* Return: {Number} Operates similar to [`Array#indexOf()`][] in that it returns either the starting index position of `value` in Buffer or `-1` if the Buffer does not @@ -571,9 +527,10 @@ utf16Buffer.indexOf('\u03a3', -4, 'ucs2'); ### buf.includes(value[, byteOffset][, encoding]) -* `value` String, Buffer or Number -* `byteOffset` Number, Optional, Default: 0 -* `encoding` String, Optional, Default: 'utf8' +* `value` {String, Buffer or Number} +* `byteOffset` {Number} Default: 0 +* `encoding` {String} Default: `'utf8'` +* Return: {Boolean} Operates similar to [Array#includes()][]. The `value` can be a String, Buffer or Number. Strings are interpreted as UTF8 unless overridden with the @@ -600,9 +557,29 @@ buf.includes('this', 4); // returns false ``` +### buf.keys() + +* Return: {Iterator} + +Creates and returns an [iterator][] of Buffer keys (indices). + +```js +const buf = new Buffer('buffer'); +for (var key of buf.keys()) { + console.log(key); +} +// prints: +// 0 +// 1 +// 2 +// 3 +// 4 +// 5 +``` + ### buf.length -* Number +* {Number} Returns the amount of memory allocated for the Buffer in number of bytes. Note that this does not necessarily reflect the amount of usable data within the @@ -638,17 +615,16 @@ console.log(buf.length); ### buf.readDoubleBE(offset[, noAssert]) ### buf.readDoubleLE(offset[, noAssert]) -* `offset` Number -* `noAssert` Boolean, Optional, Default: false -* Return: Number +* `offset` {Number} `0 <= offset <= buf.length - 8` +* `noAssert` {Boolean} Default: false +* Return: {Number} Reads a 64-bit double from the Buffer at the specified `offset` with specified endian format (`readDoubleBE()` returns big endian, `readDoubleLE()` returns little endian). Setting `noAssert` to `true` skips validation of the `offset`. This allows the -`offset` to be beyond the end of the Buffer. When not specified, `noAssert` -defaults to `false`. +`offset` to be beyond the end of the Buffer. ```js const buf = new Buffer([1,2,3,4,5,6,7,8]); @@ -667,17 +643,16 @@ buf.readDoubleLE(1, true); // Warning: reads passed end of buffer! ### buf.readFloatBE(offset[, noAssert]) ### buf.readFloatLE(offset[, noAssert]) -* `offset` Number -* `noAssert` Boolean, Optional, Default: false -* Return: Number +* `offset` {Number} `0 <= offset <= buf.length - 4` +* `noAssert` {Boolean} Default: false +* Return: {Number} Reads a 32-bit float from the Buffer at the specified `offset` with specified endian format (`readFloatBE()` returns big endian, `readFloatLE()` returns little endian). Setting `noAssert` to `true` skips validation of the `offset`. This allows the -`offset` to be beyond the end of the Buffer. When not specified, `noAssert` -defaults to `false`. +`offset` to be beyond the end of the Buffer. ```js const buf = new Buffer([1,2,3,4]); @@ -695,15 +670,14 @@ buf.readFloatLE(1, true); // Warning: reads passed end of buffer! ### buf.readInt8(offset[, noAssert]) -* `offset` Number -* `noAssert` Boolean, Optional, Default: false -* Return: Number +* `offset` {Number} `0 <= offset <= buf.length - 1` +* `noAssert` {Boolean} Default: false +* Return: {Number} Reads a signed 8-bit integer from the Buffer at the specified `offset`. Setting `noAssert` to `true` skips validation of the `offset`. This allows the -`offset` to be beyond the end of the Buffer. When not specified, `noAssert` -defaults to `false`. +`offset` to be beyond the end of the Buffer. Integers read from the Buffer are interpreted as two's complement signed values. @@ -719,17 +693,16 @@ buf.readInt8(1); ### buf.readInt16BE(offset[, noAssert]) ### buf.readInt16LE(offset[, noAssert]) -* `offset` Number -* `noAssert` Boolean, Optional, Default: false -* Return: Number +* `offset` {Number} `0 <= offset <= buf.length - 2` +* `noAssert` {Boolean} Default: false +* Return: {Number} Reads a signed 16-bit integer from the Buffer at the specified `offset` with the specified endian format (`readInt16BE()` returns big endian, `readInt16LE()` returns little endian). Setting `noAssert` to `true` skips validation of the `offset`. This allows the -`offset` to be beyond the end of the Buffer. When not specified, `noAssert` -defaults to `false`. +`offset` to be beyond the end of the Buffer. Integers read from the Buffer are interpreted as two's complement signed values. @@ -745,17 +718,16 @@ buf.readInt16LE(1); ### buf.readInt32BE(offset[, noAssert]) ### buf.readInt32LE(offset[, noAssert]) -* `offset` Number -* `noAssert` Boolean, Optional, Default: false -* Return: Number +* `offset` {Number} `0 <= offset <= buf.length - 4` +* `noAssert` {Boolean} Default: false +* Return: {Number} Reads a signed 32-bit integer from the Buffer at the specified `offset` with the specified endian format (`readInt32BE()` returns big endian, `readInt32LE()` returns little endian). Setting `noAssert` to `true` skips validation of the `offset`. This allows the -`offset` to be beyond the end of the Buffer. When not specified, `noAssert` -defaults to `false`. +`offset` to be beyond the end of the Buffer. Integers read from the Buffer are interpreted as two's complement signed values. @@ -771,7 +743,7 @@ buf.readInt32LE(1); ### buf.readIntBE(offset, byteLength[, noAssert]) ### buf.readIntLE(offset, byteLength[, noAssert]) -* `offset` {Number} `0 <= offset <= buf.length` +* `offset` {Number} `0 <= offset <= buf.length - byteLength` * `byteLength` {Number} `0 < byteLength <= 6` * `noAssert` {Boolean} Default: false * Return: {Number} @@ -792,20 +764,18 @@ buf.readIntBE(0, 6).toString(16); ``` Setting `noAssert` to `true` skips validation of the `offset`. This allows the -`offset` to be beyond the end of the Buffer. When not specified, `noAssert` -defaults to `false`. +`offset` to be beyond the end of the Buffer. ### buf.readUInt8(offset[, noAssert]) -* `offset` Number -* `noAssert` Boolean, Optional, Default: false -* Return: Number +* `offset` {Number} `0 <= offset <= buf.length - 1` +* `noAssert` {Boolean} Default: false +* Return: {Number} Reads an unsigned 8-bit integer from the Buffer at the specified `offset`. Setting `noAssert` to `true` skips validation of the `offset`. This allows the -`offset` to be beyond the end of the Buffer. When not specified, `noAssert` -defaults to `false`. +`offset` to be beyond the end of the Buffer. ```js const buf = new Buffer([1,-2,3,4]); @@ -819,17 +789,16 @@ buf.readUInt8(1); ### buf.readUInt16BE(offset[, noAssert]) ### buf.readUInt16LE(offset[, noAssert]) -* `offset` Number -* `noAssert` Boolean, Optional, Default: false -* Return: Number +* `offset` {Number} `0 <= offset <= buf.length - 2` +* `noAssert` {Boolean} Default: false +* Return: {Number} Reads an unsigned 16-bit integer from the Buffer at the specified `offset` with specified endian format (`readInt32BE()` returns big endian, `readInt32LE()` returns little endian). Setting `noAssert` to `true` skips validation of the `offset`. This allows the -`offset` to be beyond the end of the Buffer. When not specified, `noAssert` -defaults to `false`. +`offset` to be beyond the end of the Buffer. Example: @@ -853,17 +822,16 @@ buf.readUInt16LE(2); ### buf.readUInt32BE(offset[, noAssert]) ### buf.readUInt32LE(offset[, noAssert]) -* `offset` Number -* `noAssert` Boolean, Optional, Default: false -* Return: Number +* `offset` {Number} `0 <= offset <= buf.length - 4` +* `noAssert` {Boolean} Default: false +* Return: {Number} Reads an unsigned 32-bit integer from the Buffer at the specified `offset` with specified endian format (`readInt32BE()` returns big endian, `readInt32LE()` returns little endian). Setting `noAssert` to `true` skips validation of the `offset`. This allows the -`offset` to be beyond the end of the Buffer. When not specified, `noAssert` -defaults to `false`. +`offset` to be beyond the end of the Buffer. Example: @@ -879,7 +847,7 @@ console.log(buf.readUInt32LE(0)); ### buf.readUIntBE(offset, byteLength[, noAssert]) ### buf.readUIntLE(offset, byteLength[, noAssert]) -* `offset` {Number} `0 <= offset <= buf.length` +* `offset` {Number} `0 <= offset <= buf.length - byteLength` * `byteLength` {Number} `0 < byteLength <= 6` * `noAssert` {Boolean} Default: false * Return: {Number} @@ -900,19 +868,19 @@ buf.readUIntBE(0, 6).toString(16); ``` Setting `noAssert` to `true` skips validation of the `offset`. This allows the -`offset` to be beyond the end of the Buffer. When not specified, `noAssert` -defaults to `false`. +`offset` to be beyond the end of the Buffer. ### buf.slice([start[, end]]) -* `start` Number, Optional, Default: 0 -* `end` Number, Optional, Default: `buffer.length` +* `start` {Number} Default: 0 +* `end` {Number} Default: `buffer.length` +* Return: {Buffer} -Returns a new Buffer that references the same memory as the original, but offset -and cropped by the `start` (defaults to `0`) and `end` (defaults to -`buffer.length`) indexes. +Returns a new Buffer that references the same memory as the original, but +offset and cropped by the `start` and `end` indices. -**Note that modifying the new Buffer slice will modify the memory in the original Buffer because the allocated memory of the two objects overlap.** +**Note that modifying the new Buffer slice will modify the memory in the +original Buffer because the allocated memory of the two objects overlap.** Example: build a Buffer with the ASCII alphabet, take a slice, then modify one byte from the original Buffer. @@ -948,14 +916,13 @@ buf.slice(-5, -2).toString(); ### buf.toString([encoding][, start][, end]) -* `encoding` String, Optional, Default: 'utf8' -* `start` Number, Optional, Default: 0 -* `end` Number, Optional, Default: `buffer.length` +* `encoding` {String} Default: `'utf8'` +* `start` {Number} Default: 0 +* `end` {Number} Default: `buffer.length` +* Return: {String} Decodes and returns a string from the Buffer data using the specified -character set `encoding`. If `encoding` is `undefined` or `null`, then -`encoding` defaults to `'utf8'`. The `start` and `end` parameters default to -`0` and `buffer.length` when `undefined`. +character set `encoding`. ```js const buf = new Buffer(26); @@ -974,6 +941,8 @@ buf.toString(undefined,0,5); ### buf.toJSON() +* Return: {Object} + Returns a JSON representation of the Buffer instance. `JSON.stringify` implicitly calls this function when stringifying a Buffer instance. @@ -996,20 +965,51 @@ console.log(copy.toString()); // Prints: 'test' ``` +### buf.values() + +* Return: {Iterator} + +Creates and returns an [iterator][] for Buffer values (bytes). This function is +called automatically when the Buffer is used in a `for..of` statement. + +```js +const buf = new Buffer('buffer'); +for (var value of buf.values()) { + console.log(value); +} +// prints: +// 98 +// 117 +// 102 +// 102 +// 101 +// 114 + +for (var value of buf) { + console.log(value); +} +// prints: +// 98 +// 117 +// 102 +// 102 +// 101 +// 114 +``` + ### buf.write(string[, offset][, length][, encoding]) -* `string` String - data to be written to buffer -* `offset` Number, Optional, Default: 0 -* `length` Number, Optional, Default: `buffer.length - offset` -* `encoding` String, Optional, Default: 'utf8' +* `string` {String} Bytes to be written to buffer +* `offset` {Number} Default: 0 +* `length` {Number} Default: `buffer.length - offset` +* `encoding` {String} Default: `'utf8'` +* Return: {Number} Numbers of bytes written Writes `string` to the Buffer at `offset` using the given `encoding`. -When undefined, `offset` defaults to `0`, and `encoding` defaults to `'utf8'`. -The `length` parameter is the number of bytes to write, when undefined `length` -defaults to `buffer.length - offset`. If the Buffer did not contain enough -space to fit the entire string, only a partial amount of the string will be -written however, it will not write only partially encoded characters. The -return value indicates the number of octets written. +The `length` parameter is the number of bytes to write. If the Buffer did not +contain enough space to fit the entire string, only a partial amount of the +string will be written however, it will not write only partially encoded +characters. ```js const buf = new Buffer(256); @@ -1021,9 +1021,10 @@ console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`); ### buf.writeDoubleBE(value, offset[, noAssert]) ### buf.writeDoubleLE(value, offset[, noAssert]) -* `value` Number -* `offset` Number -* `noAssert` Boolean, Optional, Default: false +* `value` {Number} Bytes to be written to Buffer +* `offset` {Number} `0 <= offset <= buf.length - 8` +* `noAssert` {Boolean} Default: false +* Return: {Number} Numbers of bytes written Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeDoubleBE()` writes big endian, `writeDoubleLE()` writes little @@ -1032,7 +1033,7 @@ endian). The `value` argument must be a valid 64-bit double. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be beyond the end of the Buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to `false`. +should not be used unless you are certain of correctness. Example: @@ -1052,9 +1053,10 @@ console.log(buf); ### buf.writeFloatBE(value, offset[, noAssert]) ### buf.writeFloatLE(value, offset[, noAssert]) -* `value` Number -* `offset` Number -* `noAssert` Boolean, Optional, Default: false +* `value` {Number} Bytes to be written to Buffer +* `offset` {Number} `0 <= offset <= buf.length - 4` +* `noAssert` {Boolean} Default: false +* Return: {Number} Numbers of bytes written Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeFloatBE()` writes big endian, `writeFloatLE()` writes little @@ -1064,7 +1066,7 @@ float. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be beyond the end of the Buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to `false`. +should not be used unless you are certain of correctness. Example: @@ -1083,9 +1085,10 @@ console.log(buf); ### buf.writeInt8(value, offset[, noAssert]) -* `value` Number -* `offset` Number -* `noAssert` Boolean, Optional, Default: false +* `value` {Number} Bytes to be written to Buffer +* `offset` {Number} `0 <= offset <= buf.length - 1` +* `noAssert` {Boolean} Default: false +* Return: {Number} Numbers of bytes written Writes `value` to the Buffer at the specified `offset`. The `value` must be a valid signed 8-bit integer. @@ -1093,7 +1096,7 @@ valid signed 8-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be beyond the end of the Buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to `false`. +should not be used unless you are certain of correctness. The `value` is interpreted and written as a two's complement signed integer. @@ -1108,9 +1111,10 @@ console.log(buf); ### buf.writeInt16BE(value, offset[, noAssert]) ### buf.writeInt16LE(value, offset[, noAssert]) -* `value` Number -* `offset` Number -* `noAssert` Boolean, Optional, Default: false +* `value` {Number} Bytes to be written to Buffer +* `offset` {Number} `0 <= offset <= buf.length - 2` +* `noAssert` {Boolean} Default: false +* Return: {Number} Numbers of bytes written Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeInt16BE()` writes big endian, `writeInt16LE()` writes little @@ -1119,7 +1123,7 @@ endian). The `value` must be a valid signed 16-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be beyond the end of the Buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to `false`. +should not be used unless you are certain of correctness. The `value` is interpreted and written as a two's complement signed integer. @@ -1134,9 +1138,10 @@ console.log(buf); ### buf.writeInt32BE(value, offset[, noAssert]) ### buf.writeInt32LE(value, offset[, noAssert]) -* `value` Number -* `offset` Number -* `noAssert` Boolean, Optional, Default: false +* `value` {Number} Bytes to be written to Buffer +* `offset` {Number} `0 <= offset <= buf.length - 4` +* `noAssert` {Boolean} Default: false +* Return: {Number} Numbers of bytes written Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeInt32BE()` writes big endian, `writeInt32LE()` writes little @@ -1145,7 +1150,7 @@ endian). The `value` must be a valid signed 32-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be beyond the end of the Buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to `false`. +should not be used unless you are certain of correctness. The `value` is interpreted and written as a two's complement signed integer. @@ -1161,10 +1166,10 @@ console.log(buf); ### buf.writeIntLE(value, offset, byteLength[, noAssert]) * `value` {Number} Bytes to be written to Buffer -* `offset` {Number} `0 <= offset <= buf.length` +* `offset` {Number} `0 <= offset <= buf.length - byteLength` * `byteLength` {Number} `0 < byteLength <= 6` * `noAssert` {Boolean} Default: false -* Return: {Number} +* Return: {Number} Numbers of bytes written Writes `value` to the Buffer at the specified `offset` and `byteLength`. Supports up to 48 bits of accuracy. For example: @@ -1184,13 +1189,14 @@ console.log(buf2); Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be beyond the end of the Buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to `false`. +should not be used unless you are certain of correctness. ### buf.writeUInt8(value, offset[, noAssert]) -* `value` Number -* `offset` Number -* `noAssert` Boolean, Optional, Default: false +* `value` {Number} Bytes to be written to Buffer +* `offset` {Number} `0 <= offset <= buf.length - 1` +* `noAssert` {Boolean} Default: false +* Return: {Number} Numbers of bytes written Writes `value` to the Buffer at the specified `offset`. The `value` must be a valid unsigned 8-bit integer. @@ -1198,7 +1204,7 @@ valid unsigned 8-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be beyond the end of the Buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to `false`. +should not be used unless you are certain of correctness. Example: @@ -1216,9 +1222,10 @@ console.log(buf); ### buf.writeUInt16BE(value, offset[, noAssert]) ### buf.writeUInt16LE(value, offset[, noAssert]) -* `value` Number -* `offset` Number -* `noAssert` Boolean, Optional, Default: false +* `value` {Number} Bytes to be written to Buffer +* `offset` {Number} `0 <= offset <= buf.length - 2` +* `noAssert` {Boolean} Default: false +* Return: {Number} Numbers of bytes written Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeUInt16BE()` writes big endian, `writeUInt16LE()` writes little @@ -1227,7 +1234,7 @@ endian). The `value` must be a valid unsigned 16-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be beyond the end of the Buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to `false`. +should not be used unless you are certain of correctness. Example: @@ -1249,9 +1256,10 @@ console.log(buf); ### buf.writeUInt32BE(value, offset[, noAssert]) ### buf.writeUInt32LE(value, offset[, noAssert]) -* `value` Number -* `offset` Number -* `noAssert` Boolean, Optional, Default: false +* `value` {Number} Bytes to be written to Buffer +* `offset` {Number} `0 <= offset <= buf.length - 4` +* `noAssert` {Boolean} Default: false +* Return: {Number} Numbers of bytes written Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeUInt32BE()` writes big endian, `writeUInt32LE()` writes little @@ -1260,7 +1268,7 @@ endian). The `value` must be a valid unsigned 32-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be beyond the end of the Buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to `false`. +should not be used unless you are certain of correctness. Example: @@ -1281,10 +1289,10 @@ console.log(buf); ### buf.writeUIntLE(value, offset, byteLength[, noAssert]) * `value` {Number} Bytes to be written to Buffer -* `offset` {Number} `0 <= offset <= buf.length` +* `offset` {Number} `0 <= offset <= buf.length - byteLength` * `byteLength` {Number} `0 < byteLength <= 6` * `noAssert` {Boolean} Default: false -* Return: {Number} +* Return: {Number} Numbers of bytes written Writes `value` to the Buffer at the specified `offset` and `byteLength`. Supports up to 48 bits of accuracy. For example: @@ -1299,11 +1307,11 @@ console.log(buf); Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be beyond the end of the Buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to `false`. +should not be used unless you are certain of correctness. ## buffer.INSPECT_MAX_BYTES -* Number, Default: 50 +* {Number} Default: 50 Returns the maximum number of bytes that will be returned when `buffer.inspect()` is called. This can be overridden by user modules. See -- 2.7.4