lukechilds
/
node
mirror of https://github.com/lukechilds/node.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

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 <jasnell@gmail.com>
v5.x
Timothy Gu 9 years ago
committed by Rod Vagg
parent
17888b122c
commit
d47dadcc1f
1 changed files with 218 additions and 210 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 428
      doc/api/buffer.markdown

428
doc/api/buffer.markdown
View File

@ -150,7 +150,7 @@ It can be constructed in a variety of ways.
### new Buffer(array) ### new Buffer(array)
* `array` Array * `array` {Array}
Allocates a new Buffer using an `array` of octets. Allocates a new Buffer using an `array` of octets.
@ -205,7 +205,7 @@ console.log(buf);
### new Buffer(size) ### new Buffer(size)
* `size` Number * `size` {Number}
Allocates a new Buffer of `size` bytes. The `size` must be less than 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 or equal to the value of `require('buffer').kMaxLength` (on 64-bit
@ -230,12 +230,11 @@ console.log(buf);
### new Buffer(str[, encoding]) ### new Buffer(str[, encoding])
* `str` String - string to encode. * `str` {String} String to encode.
* `encoding` String - encoding to use, Optional. * `encoding` {String} Default: `'utf8'`
Creates a new Buffer containing the given JavaScript string `str`. If Creates a new Buffer containing the given JavaScript string `str`. If
provided, the `encoding` parameter identifies the strings character encoding. provided, the `encoding` parameter identifies the strings character encoding.
If not provided, `encoding` defaults to `'utf8'`.
```js ```js
const buf1 = new Buffer('this is a tést'); const buf1 = new Buffer('this is a tést');
@ -251,13 +250,13 @@ console.log(buf2.toString());
### Class Method: Buffer.byteLength(string[, encoding]) ### Class Method: Buffer.byteLength(string[, encoding])
* `string` String * `string` {String}
* `encoding` String, Optional, Default: 'utf8' * `encoding` {String} Default: `'utf8'`
* Return: Number * Return: {Number}
Returns the actual byte length of a string. If not specified, `encoding` Returns the actual byte length of a string. This is not the same as
defaults to `'utf8'`. This is not the same as [`String.prototype.length`][] [`String.prototype.length`][] since that returns the number of *characters* in
since that returns the number of *characters* in a string. a string.
Example: Example:
@ -274,6 +273,7 @@ console.log(`${str}: ${str.length} characters, ` +
* `buf1` {Buffer} * `buf1` {Buffer}
* `buf2` {Buffer} * `buf2` {Buffer}
* Return: {Number}
Compares `buf1` to `buf2` typically for the purpose of sorting arrays of Compares `buf1` to `buf2` typically for the purpose of sorting arrays of
Buffers. This is equivalent is calling `buf1.compare(buf2)`. 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 * `list` {Array} List of Buffer objects to concat
* `totalLength` {Number} Total length of the Buffers in the list when concatenated * `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 Returns a new Buffer which is the result of concatenating all the Buffers in
the `list` together. the `list` together.
@ -318,85 +319,19 @@ console.log(bufA.length);
### Class Method: Buffer.isBuffer(obj) ### Class Method: Buffer.isBuffer(obj)
* `obj` Object * `obj` {Object}
* Return: Boolean * Return: {Boolean}
Returns 'true' if `obj` is a Buffer. Returns 'true' if `obj` is a Buffer.
### Class Method: Buffer.isEncoding(encoding) ### Class Method: Buffer.isEncoding(encoding)
* `encoding` {String} The encoding string to test * `encoding` {String} The encoding string to test
* Return: {Boolean}
Returns true if the `encoding` is a valid encoding argument, or false Returns true if the `encoding` is a valid encoding argument, or false
otherwise. 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] ### buf[index]
<!--type=property--> <!--type=property-->
@ -423,6 +358,7 @@ console.log(buf);
### buf.compare(otherBuffer) ### buf.compare(otherBuffer)
* `otherBuffer` {Buffer} * `otherBuffer` {Buffer}
* Return: {Number}
Compares two Buffer instances and returns a number indicating whether `buf` Compares two Buffer instances and returns a number indicating whether `buf`
comes before, after, or is the same as the `otherBuffer` in sort order. 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]) ### buf.copy(targetBuffer[, targetStart][, sourceStart][, sourceEnd])
* `targetBuffer` Buffer object - Buffer to copy into * `targetBuffer` {Buffer} Buffer to copy into
* `targetStart` Number, Optional, Default: 0 * `targetStart` {Number} Default: 0
* `sourceStart` Number, Optional, Default: 0 * `sourceStart` {Number} Default: 0
* `sourceEnd` Number, Optional, Default: `buffer.length` * `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 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 if the target memory region overlaps with the source.
`targetStart` and `sourceStart` parameters default to `0` while `sourceEnd`
defaults to `buffer.length`.
Returns the number of bytes copied.
Example: build two Buffers, then copy `buf1` from byte 16 through byte 19 Example: build two Buffers, then copy `buf1` from byte 16 through byte 19
into `buf2`, starting at the 8th byte in `buf2`. into `buf2`, starting at the 8th byte in `buf2`.
@ -498,9 +431,31 @@ console.log(buf.toString());
// efghijghijklmnopqrstuvwxyz // 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) ### buf.equals(otherBuffer)
* `otherBuffer` {Buffer} * `otherBuffer` {Buffer}
* Return: {Boolean}
Returns a boolean indicating whether `this` and `otherBuffer` have exactly the Returns a boolean indicating whether `this` and `otherBuffer` have exactly the
same bytes. same bytes.
@ -518,13 +473,14 @@ console.log(buf1.equals(buf3));
### buf.fill(value[, offset][, end]) ### buf.fill(value[, offset][, end])
* `value` * `value` {String or Number}
* `offset` Number, Optional * `offset` {Number} Default: 0
* `end` Number, Optional * `end` {Number} Default: `buffer.length`
* Return: {Buffer}
Fills the Buffer with the specified value. If the `offset` (defaults to `0`) Fills the Buffer with the specified value. If the `offset` and `end` are not
and `end` (defaults to `buffer.length`) are not given it will fill the entire given it will fill the entire Buffer. The method returns a reference to the
Buffer. The method returns a reference to the Buffer so calls can be chained. Buffer so calls can be chained.
```js ```js
const b = new Buffer(50).fill('h'); const b = new Buffer(50).fill('h');
@ -534,10 +490,10 @@ console.log(b.toString());
### buf.indexOf(value[, byteOffset][, encoding]) ### buf.indexOf(value[, byteOffset][, encoding])
* `value` String, Buffer or Number * `value` {String, Buffer or Number}
* `byteOffset` Number, Optional, Default: 0 * `byteOffset` {Number} Default: 0
* `encoding` String, Optional, Default: `utf8` * `encoding` {String} Default: `'utf8'`
* Return: Number * Return: {Number}
Operates similar to [`Array#indexOf()`][] in that it returns either the 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 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]) ### buf.includes(value[, byteOffset][, encoding])
* `value` String, Buffer or Number * `value` {String, Buffer or Number}
* `byteOffset` Number, Optional, Default: 0 * `byteOffset` {Number} Default: 0
* `encoding` String, Optional, Default: 'utf8' * `encoding` {String} Default: `'utf8'`
* Return: {Boolean}
Operates similar to [Array#includes()][]. The `value` can be a String, Buffer Operates similar to [Array#includes()][]. The `value` can be a String, Buffer
or Number. Strings are interpreted as UTF8 unless overridden with the or Number. Strings are interpreted as UTF8 unless overridden with the
@ -600,9 +557,29 @@ buf.includes('this', 4);
// returns false // 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 ### buf.length
* Number * {Number}
Returns the amount of memory allocated for the Buffer in number of bytes. Note 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 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.readDoubleBE(offset[, noAssert])
### buf.readDoubleLE(offset[, noAssert]) ### buf.readDoubleLE(offset[, noAssert])
* `offset` Number * `offset` {Number} `0 <= offset <= buf.length - 8`
* `noAssert` Boolean, Optional, Default: false * `noAssert` {Boolean} Default: false
* Return: Number * Return: {Number}
Reads a 64-bit double from the Buffer at the specified `offset` with specified Reads a 64-bit double from the Buffer at the specified `offset` with specified
endian format (`readDoubleBE()` returns big endian, `readDoubleLE()` returns endian format (`readDoubleBE()` returns big endian, `readDoubleLE()` returns
little endian). little endian).
Setting `noAssert` to `true` skips validation of the `offset`. This allows the 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` `offset` to be beyond the end of the Buffer.
defaults to `false`.
```js ```js
const buf = new Buffer([1,2,3,4,5,6,7,8]); 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.readFloatBE(offset[, noAssert])
### buf.readFloatLE(offset[, noAssert]) ### buf.readFloatLE(offset[, noAssert])
* `offset` Number * `offset` {Number} `0 <= offset <= buf.length - 4`
* `noAssert` Boolean, Optional, Default: false * `noAssert` {Boolean} Default: false
* Return: Number * Return: {Number}
Reads a 32-bit float from the Buffer at the specified `offset` with specified Reads a 32-bit float from the Buffer at the specified `offset` with specified
endian format (`readFloatBE()` returns big endian, `readFloatLE()` returns endian format (`readFloatBE()` returns big endian, `readFloatLE()` returns
little endian). little endian).
Setting `noAssert` to `true` skips validation of the `offset`. This allows the 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` `offset` to be beyond the end of the Buffer.
defaults to `false`.
```js ```js
const buf = new Buffer([1,2,3,4]); 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]) ### buf.readInt8(offset[, noAssert])
* `offset` Number * `offset` {Number} `0 <= offset <= buf.length - 1`
* `noAssert` Boolean, Optional, Default: false * `noAssert` {Boolean} Default: false
* Return: Number * Return: {Number}
Reads a signed 8-bit integer from the Buffer at the specified `offset`. 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 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` `offset` to be beyond the end of the Buffer.
defaults to `false`.
Integers read from the Buffer are interpreted as two's complement signed values. 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.readInt16BE(offset[, noAssert])
### buf.readInt16LE(offset[, noAssert]) ### buf.readInt16LE(offset[, noAssert])
* `offset` Number * `offset` {Number} `0 <= offset <= buf.length - 2`
* `noAssert` Boolean, Optional, Default: false * `noAssert` {Boolean} Default: false
* Return: Number * Return: {Number}
Reads a signed 16-bit integer from the Buffer at the specified `offset` with Reads a signed 16-bit integer from the Buffer at the specified `offset` with
the specified endian format (`readInt16BE()` returns big endian, the specified endian format (`readInt16BE()` returns big endian,
`readInt16LE()` returns little endian). `readInt16LE()` returns little endian).
Setting `noAssert` to `true` skips validation of the `offset`. This allows the 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` `offset` to be beyond the end of the Buffer.
defaults to `false`.
Integers read from the Buffer are interpreted as two's complement signed values. 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.readInt32BE(offset[, noAssert])
### buf.readInt32LE(offset[, noAssert]) ### buf.readInt32LE(offset[, noAssert])
* `offset` Number * `offset` {Number} `0 <= offset <= buf.length - 4`
* `noAssert` Boolean, Optional, Default: false * `noAssert` {Boolean} Default: false
* Return: Number * Return: {Number}
Reads a signed 32-bit integer from the Buffer at the specified `offset` with Reads a signed 32-bit integer from the Buffer at the specified `offset` with
the specified endian format (`readInt32BE()` returns big endian, the specified endian format (`readInt32BE()` returns big endian,
`readInt32LE()` returns little endian). `readInt32LE()` returns little endian).
Setting `noAssert` to `true` skips validation of the `offset`. This allows the 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` `offset` to be beyond the end of the Buffer.
defaults to `false`.
Integers read from the Buffer are interpreted as two's complement signed values. 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.readIntBE(offset, byteLength[, noAssert])
### buf.readIntLE(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` * `byteLength` {Number} `0 < byteLength <= 6`
* `noAssert` {Boolean} Default: false * `noAssert` {Boolean} Default: false
* Return: {Number} * Return: {Number}
@ -792,20 +764,18 @@ buf.readIntBE(0, 6).toString(16);
``` ```
Setting `noAssert` to `true` skips validation of the `offset`. This allows the 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` `offset` to be beyond the end of the Buffer.
defaults to `false`.
### buf.readUInt8(offset[, noAssert]) ### buf.readUInt8(offset[, noAssert])
* `offset` Number * `offset` {Number} `0 <= offset <= buf.length - 1`
* `noAssert` Boolean, Optional, Default: false * `noAssert` {Boolean} Default: false
* Return: Number * Return: {Number}
Reads an unsigned 8-bit integer from the Buffer at the specified `offset`. 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 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` `offset` to be beyond the end of the Buffer.
defaults to `false`.
```js ```js
const buf = new Buffer([1,-2,3,4]); const buf = new Buffer([1,-2,3,4]);
@ -819,17 +789,16 @@ buf.readUInt8(1);
### buf.readUInt16BE(offset[, noAssert]) ### buf.readUInt16BE(offset[, noAssert])
### buf.readUInt16LE(offset[, noAssert]) ### buf.readUInt16LE(offset[, noAssert])
* `offset` Number * `offset` {Number} `0 <= offset <= buf.length - 2`
* `noAssert` Boolean, Optional, Default: false * `noAssert` {Boolean} Default: false
* Return: Number * Return: {Number}
Reads an unsigned 16-bit integer from the Buffer at the specified `offset` with Reads an unsigned 16-bit integer from the Buffer at the specified `offset` with
specified endian format (`readInt32BE()` returns big endian, specified endian format (`readInt32BE()` returns big endian,
`readInt32LE()` returns little endian). `readInt32LE()` returns little endian).
Setting `noAssert` to `true` skips validation of the `offset`. This allows the 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` `offset` to be beyond the end of the Buffer.
defaults to `false`.
Example: Example:
@ -853,17 +822,16 @@ buf.readUInt16LE(2);
### buf.readUInt32BE(offset[, noAssert]) ### buf.readUInt32BE(offset[, noAssert])
### buf.readUInt32LE(offset[, noAssert]) ### buf.readUInt32LE(offset[, noAssert])
* `offset` Number * `offset` {Number} `0 <= offset <= buf.length - 4`
* `noAssert` Boolean, Optional, Default: false * `noAssert` {Boolean} Default: false
* Return: Number * Return: {Number}
Reads an unsigned 32-bit integer from the Buffer at the specified `offset` with Reads an unsigned 32-bit integer from the Buffer at the specified `offset` with
specified endian format (`readInt32BE()` returns big endian, specified endian format (`readInt32BE()` returns big endian,
`readInt32LE()` returns little endian). `readInt32LE()` returns little endian).
Setting `noAssert` to `true` skips validation of the `offset`. This allows the 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` `offset` to be beyond the end of the Buffer.
defaults to `false`.
Example: Example:
@ -879,7 +847,7 @@ console.log(buf.readUInt32LE(0));
### buf.readUIntBE(offset, byteLength[, noAssert]) ### buf.readUIntBE(offset, byteLength[, noAssert])
### buf.readUIntLE(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` * `byteLength` {Number} `0 < byteLength <= 6`
* `noAssert` {Boolean} Default: false * `noAssert` {Boolean} Default: false
* Return: {Number} * Return: {Number}
@ -900,19 +868,19 @@ buf.readUIntBE(0, 6).toString(16);
``` ```
Setting `noAssert` to `true` skips validation of the `offset`. This allows the 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` `offset` to be beyond the end of the Buffer.
defaults to `false`.
### buf.slice([start[, end]]) ### buf.slice([start[, end]])
* `start` Number, Optional, Default: 0 * `start` {Number} Default: 0
* `end` Number, Optional, Default: `buffer.length` * `end` {Number} Default: `buffer.length`
* Return: {Buffer}
Returns a new Buffer that references the same memory as the original, but offset Returns a new Buffer that references the same memory as the original, but
and cropped by the `start` (defaults to `0`) and `end` (defaults to offset and cropped by the `start` and `end` indices.
`buffer.length`) indexes.
**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 Example: build a Buffer with the ASCII alphabet, take a slice, then modify one
byte from the original Buffer. byte from the original Buffer.
@ -948,14 +916,13 @@ buf.slice(-5, -2).toString();
### buf.toString([encoding][, start][, end]) ### buf.toString([encoding][, start][, end])
* `encoding` String, Optional, Default: 'utf8' * `encoding` {String} Default: `'utf8'`
* `start` Number, Optional, Default: 0 * `start` {Number} Default: 0
* `end` Number, Optional, Default: `buffer.length` * `end` {Number} Default: `buffer.length`
* Return: {String}
Decodes and returns a string from the Buffer data using the specified Decodes and returns a string from the Buffer data using the specified
character set `encoding`. If `encoding` is `undefined` or `null`, then character set `encoding`.
`encoding` defaults to `'utf8'`. The `start` and `end` parameters default to
`0` and `buffer.length` when `undefined`.
```js ```js
const buf = new Buffer(26); const buf = new Buffer(26);
@ -974,6 +941,8 @@ buf.toString(undefined,0,5);
### buf.toJSON() ### buf.toJSON()
* Return: {Object}
Returns a JSON representation of the Buffer instance. `JSON.stringify` Returns a JSON representation of the Buffer instance. `JSON.stringify`
implicitly calls this function when stringifying a Buffer instance. implicitly calls this function when stringifying a Buffer instance.
@ -996,20 +965,51 @@ console.log(copy.toString());
// Prints: 'test' // 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]) ### buf.write(string[, offset][, length][, encoding])
* `string` String - data to be written to buffer * `string` {String} Bytes to be written to buffer
* `offset` Number, Optional, Default: 0 * `offset` {Number} Default: 0
* `length` Number, Optional, Default: `buffer.length - offset` * `length` {Number} Default: `buffer.length - offset`
* `encoding` String, Optional, Default: 'utf8' * `encoding` {String} Default: `'utf8'`
* Return: {Number} Numbers of bytes written
Writes `string` to the Buffer at `offset` using the given `encoding`. 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. If the Buffer did not
The `length` parameter is the number of bytes to write, when undefined `length` contain enough space to fit the entire string, only a partial amount of the
defaults to `buffer.length - offset`. If the Buffer did not contain enough string will be written however, it will not write only partially encoded
space to fit the entire string, only a partial amount of the string will be characters.
written however, it will not write only partially encoded characters. The
return value indicates the number of octets written.
```js ```js
const buf = new Buffer(256); const buf = new Buffer(256);
@ -1021,9 +1021,10 @@ console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`);
### buf.writeDoubleBE(value, offset[, noAssert]) ### buf.writeDoubleBE(value, offset[, noAssert])
### buf.writeDoubleLE(value, offset[, noAssert]) ### buf.writeDoubleLE(value, offset[, noAssert])
* `value` Number * `value` {Number} Bytes to be written to Buffer
* `offset` Number * `offset` {Number} `0 <= offset <= buf.length - 8`
* `noAssert` Boolean, Optional, Default: false * `noAssert` {Boolean} Default: false
* Return: {Number} Numbers of bytes written
Writes `value` to the Buffer at the specified `offset` with specified endian Writes `value` to the Buffer at the specified `offset` with specified endian
format (`writeDoubleBE()` writes big endian, `writeDoubleLE()` writes little 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 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 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 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: Example:
@ -1052,9 +1053,10 @@ console.log(buf);
### buf.writeFloatBE(value, offset[, noAssert]) ### buf.writeFloatBE(value, offset[, noAssert])
### buf.writeFloatLE(value, offset[, noAssert]) ### buf.writeFloatLE(value, offset[, noAssert])
* `value` Number * `value` {Number} Bytes to be written to Buffer
* `offset` Number * `offset` {Number} `0 <= offset <= buf.length - 4`
* `noAssert` Boolean, Optional, Default: false * `noAssert` {Boolean} Default: false
* Return: {Number} Numbers of bytes written
Writes `value` to the Buffer at the specified `offset` with specified endian Writes `value` to the Buffer at the specified `offset` with specified endian
format (`writeFloatBE()` writes big endian, `writeFloatLE()` writes little 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 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 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 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: Example:
@ -1083,9 +1085,10 @@ console.log(buf);
### buf.writeInt8(value, offset[, noAssert]) ### buf.writeInt8(value, offset[, noAssert])
* `value` Number * `value` {Number} Bytes to be written to Buffer
* `offset` Number * `offset` {Number} `0 <= offset <= buf.length - 1`
* `noAssert` Boolean, Optional, Default: false * `noAssert` {Boolean} Default: false
* Return: {Number} Numbers of bytes written
Writes `value` to the Buffer at the specified `offset`. The `value` must be a Writes `value` to the Buffer at the specified `offset`. The `value` must be a
valid signed 8-bit integer. 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 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 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 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. 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.writeInt16BE(value, offset[, noAssert])
### buf.writeInt16LE(value, offset[, noAssert]) ### buf.writeInt16LE(value, offset[, noAssert])
* `value` Number * `value` {Number} Bytes to be written to Buffer
* `offset` Number * `offset` {Number} `0 <= offset <= buf.length - 2`
* `noAssert` Boolean, Optional, Default: false * `noAssert` {Boolean} Default: false
* Return: {Number} Numbers of bytes written
Writes `value` to the Buffer at the specified `offset` with specified endian Writes `value` to the Buffer at the specified `offset` with specified endian
format (`writeInt16BE()` writes big endian, `writeInt16LE()` writes little 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 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 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 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. 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.writeInt32BE(value, offset[, noAssert])
### buf.writeInt32LE(value, offset[, noAssert]) ### buf.writeInt32LE(value, offset[, noAssert])
* `value` Number * `value` {Number} Bytes to be written to Buffer
* `offset` Number * `offset` {Number} `0 <= offset <= buf.length - 4`
* `noAssert` Boolean, Optional, Default: false * `noAssert` {Boolean} Default: false
* Return: {Number} Numbers of bytes written
Writes `value` to the Buffer at the specified `offset` with specified endian Writes `value` to the Buffer at the specified `offset` with specified endian
format (`writeInt32BE()` writes big endian, `writeInt32LE()` writes little 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 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 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 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. 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]) ### buf.writeIntLE(value, offset, byteLength[, noAssert])
* `value` {Number} Bytes to be written to Buffer * `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` * `byteLength` {Number} `0 < byteLength <= 6`
* `noAssert` {Boolean} Default: false * `noAssert` {Boolean} Default: false
* Return: {Number} * Return: {Number} Numbers of bytes written
Writes `value` to the Buffer at the specified `offset` and `byteLength`. Writes `value` to the Buffer at the specified `offset` and `byteLength`.
Supports up to 48 bits of accuracy. For example: 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 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 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 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]) ### buf.writeUInt8(value, offset[, noAssert])
* `value` Number * `value` {Number} Bytes to be written to Buffer
* `offset` Number * `offset` {Number} `0 <= offset <= buf.length - 1`
* `noAssert` Boolean, Optional, Default: false * `noAssert` {Boolean} Default: false
* Return: {Number} Numbers of bytes written
Writes `value` to the Buffer at the specified `offset`. The `value` must be a Writes `value` to the Buffer at the specified `offset`. The `value` must be a
valid unsigned 8-bit integer. 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 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 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 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: Example:
@ -1216,9 +1222,10 @@ console.log(buf);
### buf.writeUInt16BE(value, offset[, noAssert]) ### buf.writeUInt16BE(value, offset[, noAssert])
### buf.writeUInt16LE(value, offset[, noAssert]) ### buf.writeUInt16LE(value, offset[, noAssert])
* `value` Number * `value` {Number} Bytes to be written to Buffer
* `offset` Number * `offset` {Number} `0 <= offset <= buf.length - 2`
* `noAssert` Boolean, Optional, Default: false * `noAssert` {Boolean} Default: false
* Return: {Number} Numbers of bytes written
Writes `value` to the Buffer at the specified `offset` with specified endian Writes `value` to the Buffer at the specified `offset` with specified endian
format (`writeUInt16BE()` writes big endian, `writeUInt16LE()` writes little 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 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 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 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: Example:
@ -1249,9 +1256,10 @@ console.log(buf);
### buf.writeUInt32BE(value, offset[, noAssert]) ### buf.writeUInt32BE(value, offset[, noAssert])
### buf.writeUInt32LE(value, offset[, noAssert]) ### buf.writeUInt32LE(value, offset[, noAssert])
* `value` Number * `value` {Number} Bytes to be written to Buffer
* `offset` Number * `offset` {Number} `0 <= offset <= buf.length - 4`
* `noAssert` Boolean, Optional, Default: false * `noAssert` {Boolean} Default: false
* Return: {Number} Numbers of bytes written
Writes `value` to the Buffer at the specified `offset` with specified endian Writes `value` to the Buffer at the specified `offset` with specified endian
format (`writeUInt32BE()` writes big endian, `writeUInt32LE()` writes little 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 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 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 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: Example:
@ -1281,10 +1289,10 @@ console.log(buf);
### buf.writeUIntLE(value, offset, byteLength[, noAssert]) ### buf.writeUIntLE(value, offset, byteLength[, noAssert])
* `value` {Number} Bytes to be written to Buffer * `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` * `byteLength` {Number} `0 < byteLength <= 6`
* `noAssert` {Boolean} Default: false * `noAssert` {Boolean} Default: false
* Return: {Number} * Return: {Number} Numbers of bytes written
Writes `value` to the Buffer at the specified `offset` and `byteLength`. Writes `value` to the Buffer at the specified `offset` and `byteLength`.
Supports up to 48 bits of accuracy. For example: 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 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 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 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 ## buffer.INSPECT_MAX_BYTES
* Number, Default: 50 * {Number} Default: 50
Returns the maximum number of bytes that will be returned when Returns the maximum number of bytes that will be returned when
`buffer.inspect()` is called. This can be overridden by user modules. See `buffer.inspect()` is called. This can be overridden by user modules. See

Write Preview
Loading…
Cancel
Save