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

doc: sort buffer alphabetically 

Reorders, with minimal contextual duplication, the buffer documentation
alphabetically.

PR-URL: https://github.com/nodejs/node/pull/3662
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
v5.x
Tristian Flanagan 9 years ago
committed by Rod Vagg
parent
c7c05d8f02
commit
fb6a09cd0e
1 changed files with 366 additions and 337 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. 703
      doc/api/buffer.markdown

703
doc/api/buffer.markdown
View File

@ -57,6 +57,18 @@ arrays specification. `ArrayBuffer#slice()` makes a copy of the slice while
The Buffer class is a global type for dealing with binary data directly. The Buffer class is a global type for dealing with binary data directly.
It can be constructed in a variety of ways. It can be constructed in a variety of ways.
### new Buffer(array)
* `array` Array
Allocates a new buffer using an `array` of octets.
### new Buffer(buffer)
* `buffer` {Buffer}
Copies the passed `buffer` data onto a new `Buffer` instance.
### new Buffer(size) ### new Buffer(size)
* `size` Number * `size` Number
@ -70,18 +82,6 @@ Unlike `ArrayBuffers`, the underlying memory for buffers is not initialized. So
the contents of a newly created `Buffer` are unknown and could contain the contents of a newly created `Buffer` are unknown and could contain
sensitive data. Use `buf.fill(0)` to initialize a buffer to zeroes. sensitive data. Use `buf.fill(0)` to initialize a buffer to zeroes.
### new Buffer(array)
* `array` Array
Allocates a new buffer using an `array` of octets.
### new Buffer(buffer)
* `buffer` {Buffer}
Copies the passed `buffer` data onto a new `Buffer` instance.
### new Buffer(str[, encoding]) ### new Buffer(str[, encoding])
* `str` String - string to encode. * `str` String - string to encode.
@ -90,20 +90,6 @@ Copies the passed `buffer` data onto a new `Buffer` instance.
Allocates a new buffer containing the given `str`. Allocates a new buffer containing the given `str`.
`encoding` defaults to `'utf8'`. `encoding` defaults to `'utf8'`.
### Class Method: Buffer.isEncoding(encoding)
* `encoding` {String} The encoding string to test
Returns true if the `encoding` is a valid encoding argument, or false
otherwise.
### Class Method: Buffer.isBuffer(obj)
* `obj` Object
* Return: Boolean
Tests if `obj` is a `Buffer`.
### Class Method: Buffer.byteLength(string[, encoding]) ### Class Method: Buffer.byteLength(string[, encoding])
* `string` String * `string` String
@ -123,6 +109,17 @@ Example:
// ½ + ¼ = ¾: 9 characters, 12 bytes // ½ + ¼ = ¾: 9 characters, 12 bytes
### Class Method: Buffer.compare(buf1, buf2)
* `buf1` {Buffer}
* `buf2` {Buffer}
The same as [`buf1.compare(buf2)`](#buffer_buf_compare_otherbuffer). Useful
for sorting an Array of Buffers:
var arr = [Buffer('1234'), Buffer('0123')];
arr.sort(Buffer.compare);
### Class Method: Buffer.concat(list[, totalLength]) ### Class Method: Buffer.concat(list[, totalLength])
* `list` {Array} List of Buffer objects to concat * `list` {Array} List of Buffer objects to concat
@ -164,151 +161,32 @@ Example: build a single buffer from a list of three buffers:
// <Buffer 00 00 00 00 ...> // <Buffer 00 00 00 00 ...>
// 42 // 42
### Class Method: Buffer.compare(buf1, buf2) ### Class Method: Buffer.isBuffer(obj)
* `buf1` {Buffer}
* `buf2` {Buffer}
The same as [`buf1.compare(buf2)`](#buffer_buf_compare_otherbuffer). Useful
for sorting an Array of Buffers:
var arr = [Buffer('1234'), Buffer('0123')];
arr.sort(Buffer.compare);
### buf.length
* Number
The size of the buffer in bytes. Note that this is not necessarily the size
of the contents. `length` refers to the amount of memory allocated for the
buffer object. It does not change when the contents of the buffer are changed.
buf = new Buffer(1234);
console.log(buf.length);
buf.write("some string", 0, "ascii");
console.log(buf.length);
// 1234
// 1234
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.
buf = new Buffer(10);
buf.write("abcdefghj", 0, "ascii");
console.log(buf.length); // 10
buf = buf.slice(0,5);
console.log(buf.length); // 5
### 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'
Writes `string` to the buffer at `offset` using the given encoding.
`offset` defaults to `0`, `encoding` defaults to `'utf8'`. `length` is
the number of bytes to write. Returns number of octets written. If `buffer` did
not contain enough space to fit the entire string, it will write a partial
amount of the string. `length` defaults to `buffer.length - offset`.
The method will not write partial characters.
buf = new Buffer(256);
len = buf.write('\u00bd + \u00bc = \u00be', 0);
console.log(len + " bytes: " + buf.toString('utf8', 0, len));
### buf.writeUIntLE(value, offset, byteLength[, noAssert])
### buf.writeUIntBE(value, offset, byteLength[, noAssert])
### buf.writeIntLE(value, offset, byteLength[, noAssert])
### buf.writeIntBE(value, offset, byteLength[, noAssert])
* `value` {Number} Bytes to be written to buffer
* `offset` {Number} `0 <= offset <= buf.length`
* `byteLength` {Number} `0 < byteLength <= 6`
* `noAssert` {Boolean} Default: false
* Return: {Number}
Writes `value` to the buffer at the specified `offset` and `byteLength`.
Supports up to 48 bits of accuracy. For example:
var b = new Buffer(6);
b.writeUIntBE(0x1234567890ab, 0, 6);
// <Buffer 12 34 56 78 90 ab>
Set `noAssert` to `true` to skip validation of `value` and `offset`. Defaults
to `false`.
### buf.readUIntLE(offset, byteLength[, noAssert])
### buf.readUIntBE(offset, byteLength[, noAssert])
### buf.readIntLE(offset, byteLength[, noAssert])
### buf.readIntBE(offset, byteLength[, noAssert])
* `offset` {Number} `0 <= offset <= buf.length`
* `byteLength` {Number} `0 < byteLength <= 6`
* `noAssert` {Boolean} Default: false
* Return: {Number}
A generalized version of all numeric read methods. Supports up to 48 bits of
accuracy. For example:
var b = new Buffer(6);
b.writeUInt16LE(0x90ab, 0);
b.writeUInt32LE(0x12345678, 2);
b.readUIntLE(0, 6).toString(16); // Specify 6 bytes (48 bits)
// output: '1234567890ab'
Set `noAssert` to true to skip validation of `offset`. This means that `offset`
may be beyond the end of the buffer. Defaults to `false`.
### buf.toString([encoding][, start][, end])
* `encoding` String, Optional, Default: 'utf8'
* `start` Number, Optional, Default: 0
* `end` Number, Optional, Default: `buffer.length`
Decodes and returns a string from buffer data encoded using the specified * `obj` Object
character set encoding. If `encoding` is `undefined` or `null`, then `encoding` * Return: Boolean
defaults to `'utf8'`. The `start` and `end` parameters default to `0` and
`buffer.length` when `undefined`.
buf = new Buffer(26); Tests if `obj` is a `Buffer`.
for (var i = 0 ; i < 26 ; i++) {
buf[i] = i + 97; // 97 is ASCII a
}
buf.toString('ascii'); // outputs: abcdefghijklmnopqrstuvwxyz
buf.toString('ascii',0,5); // outputs: abcde
buf.toString('utf8',0,5); // outputs: abcde
buf.toString(undefined,0,5); // encoding defaults to 'utf8', outputs abcde
See `buffer.write()` example, above. ### Class Method: Buffer.isEncoding(encoding)
* `encoding` {String} The encoding string to test
### buf.toJSON() Returns true if the `encoding` is a valid encoding argument, or false
otherwise.
Returns a JSON-representation of the Buffer instance. `JSON.stringify` ### buffer.entries()
implicitly calls this function when stringifying a Buffer instance.
Example: Creates iterator for `[index, byte]` arrays.
var buf = new Buffer('test'); ### buffer.keys()
var json = JSON.stringify(buf);
console.log(json); Creates iterator for buffer keys (indices).
// '{"type":"Buffer","data":[116,101,115,116]}'
var copy = JSON.parse(json, function(key, value) { ### buffer.values()
return value && value.type === 'Buffer'
? new Buffer(value.data)
: value;
});
console.log(copy); Creates iterator for buffer values (bytes). This function is called automatically
// <Buffer 74 65 73 74> when `buffer` is used in a `for..of` statement.
### buf[index] ### buf[index]
@ -331,10 +209,6 @@ Example: copy an ASCII string into a buffer, one byte at a time:
// Node.js // Node.js
### buf.equals(otherBuffer)
* `otherBuffer` {Buffer}
Returns a boolean of whether `this` and `otherBuffer` have the same Returns a boolean of whether `this` and `otherBuffer` have the same
bytes. bytes.
@ -388,35 +262,22 @@ region in the same buffer
// efghijghijklmnopqrstuvwxyz // efghijghijklmnopqrstuvwxyz
### buf.equals(otherBuffer)
### buf.slice([start[, end]]) * `otherBuffer` {Buffer}
* `start` Number, Optional, Default: 0
* `end` Number, Optional, Default: `buffer.length`
Returns a new buffer which references the same memory as the old, but offset
and cropped by the `start` (defaults to `0`) and `end` (defaults to
`buffer.length`) indexes. Negative indexes start from the end of the buffer.
**Modifying the new buffer slice will modify memory in the original buffer!**
Example: build a Buffer with the ASCII alphabet, take a slice, then modify one
byte from the original Buffer.
var buf1 = new Buffer(26);
for (var i = 0 ; i < 26 ; i++) { ### buf.fill(value[, offset][, end])
buf1[i] = i + 97; // 97 is ASCII a
}
var buf2 = buf1.slice(0, 3); * `value`
console.log(buf2.toString('ascii', 0, buf2.length)); * `offset` Number, Optional
buf1[0] = 33; * `end` Number, Optional
console.log(buf2.toString('ascii', 0, buf2.length));
// abc Fills the buffer with the specified value. If the `offset` (defaults to `0`)
// !bc and `end` (defaults to `buffer.length`) are not given it will fill the entire
buffer.
var b = new Buffer(50);
b.fill("h");
### buf.indexOf(value[, byteOffset]) ### buf.indexOf(value[, byteOffset])
@ -430,80 +291,73 @@ Accepts a String, Buffer or Number. Strings are interpreted as UTF8. Buffers
will use the entire buffer. So in order to compare a partial Buffer use will use the entire buffer. So in order to compare a partial Buffer use
`Buffer#slice()`. Numbers can range from 0 to 255. `Buffer#slice()`. Numbers can range from 0 to 255.
### buf.readUInt8(offset[, noAssert]) ### buf.length
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
* Return: Number
Reads an unsigned 8 bit integer from the buffer at the specified offset. * Number
Set `noAssert` to true to skip validation of `offset`. This means that `offset` The size of the buffer in bytes. Note that this is not necessarily the size
may be beyond the end of the buffer. Defaults to `false`. of the contents. `length` refers to the amount of memory allocated for the
buffer object. It does not change when the contents of the buffer are changed.
Example: buf = new Buffer(1234);
var buf = new Buffer(4); console.log(buf.length);
buf.write("some string", 0, "ascii");
console.log(buf.length);
buf[0] = 0x3; // 1234
buf[1] = 0x4; // 1234
buf[2] = 0x23;
buf[3] = 0x42;
for (ii = 0; ii < buf.length; ii++) { While the `length` property is not immutable, changing the value of `length`
console.log(buf.readUInt8(ii)); 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.
// 0x3 buf = new Buffer(10);
// 0x4 buf.write("abcdefghj", 0, "ascii");
// 0x23 console.log(buf.length); // 10
// 0x42 buf = buf.slice(0,5);
console.log(buf.length); // 5
### buf.readUInt16LE(offset[, noAssert]) ### buf.readDoubleBE(offset[, noAssert])
### buf.readUInt16BE(offset[, noAssert]) ### buf.readDoubleLE(offset[, noAssert])
* `offset` Number * `offset` Number
* `noAssert` Boolean, Optional, Default: false * `noAssert` Boolean, Optional, Default: false
* Return: Number * Return: Number
Reads an unsigned 16 bit integer from the buffer at the specified offset with Reads a 64 bit double from the buffer at the specified offset with specified
specified endian format. endian format.
Set `noAssert` to true to skip validation of `offset`. This means that `offset` Set `noAssert` to true to skip validation of `offset`. This means that `offset`
may be beyond the end of the buffer. Defaults to `false`. may be beyond the end of the buffer. Defaults to `false`.
Example: Example:
var buf = new Buffer(4); var buf = new Buffer(8);
buf[0] = 0x3; buf[0] = 0x55;
buf[1] = 0x4; buf[1] = 0x55;
buf[2] = 0x23; buf[2] = 0x55;
buf[3] = 0x42; buf[3] = 0x55;
buf[4] = 0x55;
buf[5] = 0x55;
buf[6] = 0xd5;
buf[7] = 0x3f;
console.log(buf.readUInt16BE(0)); console.log(buf.readDoubleLE(0));
console.log(buf.readUInt16LE(0));
console.log(buf.readUInt16BE(1));
console.log(buf.readUInt16LE(1));
console.log(buf.readUInt16BE(2));
console.log(buf.readUInt16LE(2));
// 0x0304 // 0.3333333333333333
// 0x0403
// 0x0423
// 0x2304
// 0x2342
// 0x4223
### buf.readUInt32LE(offset[, noAssert]) ### buf.readFloatBE(offset[, noAssert])
### buf.readUInt32BE(offset[, noAssert]) ### buf.readFloatLE(offset[, noAssert])
* `offset` Number * `offset` Number
* `noAssert` Boolean, Optional, Default: false * `noAssert` Boolean, Optional, Default: false
* Return: Number * Return: Number
Reads an unsigned 32 bit integer from the buffer at the specified offset with Reads a 32 bit float from the buffer at the specified offset with specified
specified endian format. endian format.
Set `noAssert` to true to skip validation of `offset`. This means that `offset` Set `noAssert` to true to skip validation of `offset`. This means that `offset`
may be beyond the end of the buffer. Defaults to `false`. may be beyond the end of the buffer. Defaults to `false`.
@ -512,16 +366,14 @@ Example:
var buf = new Buffer(4); var buf = new Buffer(4);
buf[0] = 0x3; buf[0] = 0x00;
buf[1] = 0x4; buf[1] = 0x00;
buf[2] = 0x23; buf[2] = 0x80;
buf[3] = 0x42; buf[3] = 0x3f;
console.log(buf.readUInt32BE(0)); console.log(buf.readFloatLE(0));
console.log(buf.readUInt32LE(0));
// 0x03042342 // 0x01
// 0x42230403
### buf.readInt8(offset[, noAssert]) ### buf.readInt8(offset[, noAssert])
@ -537,8 +389,8 @@ may be beyond the end of the buffer. Defaults to `false`.
Works as `buffer.readUInt8`, except buffer contents are treated as two's Works as `buffer.readUInt8`, except buffer contents are treated as two's
complement signed values. complement signed values.
### buf.readInt16LE(offset[, noAssert])
### buf.readInt16BE(offset[, noAssert]) ### buf.readInt16BE(offset[, noAssert])
### buf.readInt16LE(offset[, noAssert])
* `offset` Number * `offset` Number
* `noAssert` Boolean, Optional, Default: false * `noAssert` Boolean, Optional, Default: false
@ -553,8 +405,8 @@ may be beyond the end of the buffer. Defaults to `false`.
Works as `buffer.readUInt16*`, except buffer contents are treated as two's Works as `buffer.readUInt16*`, except buffer contents are treated as two's
complement signed values. complement signed values.
### buf.readInt32LE(offset[, noAssert])
### buf.readInt32BE(offset[, noAssert]) ### buf.readInt32BE(offset[, noAssert])
### buf.readInt32LE(offset[, noAssert])
* `offset` Number * `offset` Number
* `noAssert` Boolean, Optional, Default: false * `noAssert` Boolean, Optional, Default: false
@ -569,15 +421,33 @@ may be beyond the end of the buffer. Defaults to `false`.
Works as `buffer.readUInt32*`, except buffer contents are treated as two's Works as `buffer.readUInt32*`, except buffer contents are treated as two's
complement signed values. complement signed values.
### buf.readFloatLE(offset[, noAssert]) ### buf.readIntBE(offset, byteLength[, noAssert])
### buf.readFloatBE(offset[, noAssert]) ### buf.readIntLE(offset, byteLength[, noAssert])
* `offset` {Number} `0 <= offset <= buf.length`
* `byteLength` {Number} `0 < byteLength <= 6`
* `noAssert` {Boolean} Default: false
* Return: {Number}
A generalized version of all numeric read methods. Supports up to 48 bits of
accuracy. For example:
var b = new Buffer(6);
b.writeUInt16LE(0x90ab, 0);
b.writeUInt32LE(0x12345678, 2);
b.readUIntLE(0, 6).toString(16); // Specify 6 bytes (48 bits)
// output: '1234567890ab'
Set `noAssert` to true to skip validation of `offset`. This means that `offset`
may be beyond the end of the buffer. Defaults to `false`.
### buf.readUInt8(offset[, noAssert])
* `offset` Number * `offset` Number
* `noAssert` Boolean, Optional, Default: false * `noAssert` Boolean, Optional, Default: false
* Return: Number * Return: Number
Reads a 32 bit float from the buffer at the specified offset with specified Reads an unsigned 8 bit integer from the buffer at the specified offset.
endian format.
Set `noAssert` to true to skip validation of `offset`. This means that `offset` Set `noAssert` to true to skip validation of `offset`. This means that `offset`
may be beyond the end of the buffer. Defaults to `false`. may be beyond the end of the buffer. Defaults to `false`.
@ -586,80 +456,201 @@ Example:
var buf = new Buffer(4); var buf = new Buffer(4);
buf[0] = 0x00; buf[0] = 0x3;
buf[1] = 0x00; buf[1] = 0x4;
buf[2] = 0x80; buf[2] = 0x23;
buf[3] = 0x3f; buf[3] = 0x42;
console.log(buf.readFloatLE(0)); for (ii = 0; ii < buf.length; ii++) {
console.log(buf.readUInt8(ii));
}
// 0x01 // 0x3
// 0x4
// 0x23
// 0x42
### buf.readDoubleLE(offset[, noAssert]) ### buf.readUInt16BE(offset[, noAssert])
### buf.readDoubleBE(offset[, noAssert]) ### buf.readUInt16LE(offset[, noAssert])
* `offset` Number * `offset` Number
* `noAssert` Boolean, Optional, Default: false * `noAssert` Boolean, Optional, Default: false
* Return: Number * Return: Number
Reads a 64 bit double from the buffer at the specified offset with specified Reads an unsigned 16 bit integer from the buffer at the specified offset with
endian format. specified endian format.
Set `noAssert` to true to skip validation of `offset`. This means that `offset` Set `noAssert` to true to skip validation of `offset`. This means that `offset`
may be beyond the end of the buffer. Defaults to `false`. may be beyond the end of the buffer. Defaults to `false`.
Example: Example:
var buf = new Buffer(8); var buf = new Buffer(4);
buf[0] = 0x55; buf[0] = 0x3;
buf[1] = 0x55; buf[1] = 0x4;
buf[2] = 0x55; buf[2] = 0x23;
buf[3] = 0x55; buf[3] = 0x42;
buf[4] = 0x55;
buf[5] = 0x55;
buf[6] = 0xd5;
buf[7] = 0x3f;
console.log(buf.readDoubleLE(0)); console.log(buf.readUInt16BE(0));
console.log(buf.readUInt16LE(0));
console.log(buf.readUInt16BE(1));
console.log(buf.readUInt16LE(1));
console.log(buf.readUInt16BE(2));
console.log(buf.readUInt16LE(2));
// 0.3333333333333333 // 0x0304
// 0x0403
// 0x0423
// 0x2304
// 0x2342
// 0x4223
### buf.writeUInt8(value, offset[, noAssert]) ### buf.readUInt32BE(offset[, noAssert])
### buf.readUInt32LE(offset[, noAssert])
* `value` Number
* `offset` Number * `offset` Number
* `noAssert` Boolean, Optional, Default: false * `noAssert` Boolean, Optional, Default: false
* Return: Number
Writes `value` to the buffer at the specified offset. Note, `value` must be a Reads an unsigned 32 bit integer from the buffer at the specified offset with
valid unsigned 8 bit integer. specified endian format.
Set `noAssert` to true to skip validation of `value` and `offset`. This means Set `noAssert` to true to skip validation of `offset`. This means that `offset`
that `value` may be too large for the specific function and `offset` may be may be beyond the end of the buffer. Defaults to `false`.
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`.
Example: Example:
var buf = new Buffer(4); var buf = new Buffer(4);
buf.writeUInt8(0x3, 0);
buf.writeUInt8(0x4, 1);
buf.writeUInt8(0x23, 2);
buf.writeUInt8(0x42, 3);
console.log(buf); buf[0] = 0x3;
buf[1] = 0x4;
buf[2] = 0x23;
buf[3] = 0x42;
// <Buffer 03 04 23 42> console.log(buf.readUInt32BE(0));
console.log(buf.readUInt32LE(0));
### buf.writeUInt16LE(value, offset[, noAssert]) // 0x03042342
### buf.writeUInt16BE(value, offset[, noAssert]) // 0x42230403
### buf.readUIntBE(offset, byteLength[, noAssert])
### buf.readUIntLE(offset, byteLength[, noAssert])
* `offset` {Number} `0 <= offset <= buf.length`
* `byteLength` {Number} `0 < byteLength <= 6`
* `noAssert` {Boolean} Default: false
* Return: {Number}
A generalized version of all numeric read methods. Supports up to 48 bits of
accuracy. For example:
var b = new Buffer(6);
b.writeUInt16LE(0x90ab, 0);
b.writeUInt32LE(0x12345678, 2);
b.readUIntLE(0, 6).toString(16); // Specify 6 bytes (48 bits)
// output: '1234567890ab'
### buf.slice([start[, end]])
* `start` Number, Optional, Default: 0
* `end` Number, Optional, Default: `buffer.length`
Returns a new buffer which references the same memory as the old, but offset
and cropped by the `start` (defaults to `0`) and `end` (defaults to
`buffer.length`) indexes. Negative indexes start from the end of the buffer.
**Modifying the new buffer slice will modify memory in the original buffer!**
Example: build a Buffer with the ASCII alphabet, take a slice, then modify one
byte from the original Buffer.
var buf1 = new Buffer(26);
for (var i = 0 ; i < 26 ; i++) {
buf1[i] = i + 97; // 97 is ASCII a
}
var buf2 = buf1.slice(0, 3);
console.log(buf2.toString('ascii', 0, buf2.length));
buf1[0] = 33;
console.log(buf2.toString('ascii', 0, buf2.length));
// abc
// !bc
### buf.toString([encoding][, start][, end])
* `encoding` String, Optional, Default: 'utf8'
* `start` Number, Optional, Default: 0
* `end` Number, Optional, Default: `buffer.length`
Decodes and returns a string from buffer data encoded 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`.
buf = new Buffer(26);
for (var i = 0 ; i < 26 ; i++) {
buf[i] = i + 97; // 97 is ASCII a
}
buf.toString('ascii'); // outputs: abcdefghijklmnopqrstuvwxyz
buf.toString('ascii',0,5); // outputs: abcde
buf.toString('utf8',0,5); // outputs: abcde
buf.toString(undefined,0,5); // encoding defaults to 'utf8', outputs abcde
See `buffer.write()` example, above.
### buf.toJSON()
Returns a JSON-representation of the Buffer instance. `JSON.stringify`
implicitly calls this function when stringifying a Buffer instance.
Example:
var buf = new Buffer('test');
var json = JSON.stringify(buf);
console.log(json);
// '{"type":"Buffer","data":[116,101,115,116]}'
var copy = JSON.parse(json, function(key, value) {
return value && value.type === 'Buffer'
? new Buffer(value.data)
: value;
});
console.log(copy);
// <Buffer 74 65 73 74>
### 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'
Writes `string` to the buffer at `offset` using the given encoding.
`offset` defaults to `0`, `encoding` defaults to `'utf8'`. `length` is
the number of bytes to write. Returns number of octets written. If `buffer` did
not contain enough space to fit the entire string, it will write a partial
amount of the string. `length` defaults to `buffer.length - offset`.
The method will not write partial characters.
buf = new Buffer(256);
len = buf.write('\u00bd + \u00bc = \u00be', 0);
console.log(len + " bytes: " + buf.toString('utf8', 0, len));
### buf.writeDoubleBE(value, offset[, noAssert])
### buf.writeDoubleLE(value, offset[, noAssert])
* `value` Number * `value` Number
* `offset` Number * `offset` Number
* `noAssert` Boolean, Optional, Default: false * `noAssert` Boolean, Optional, Default: false
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. Note, `value` must be a valid unsigned 16 bit integer. format. Note, `value` 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
@ -668,29 +659,27 @@ should not be used unless you are certain of correctness. Defaults to `false`.
Example: Example:
var buf = new Buffer(4); var buf = new Buffer(8);
buf.writeUInt16BE(0xdead, 0); buf.writeDoubleBE(0xdeadbeefcafebabe, 0);
buf.writeUInt16BE(0xbeef, 2);
console.log(buf); console.log(buf);
buf.writeUInt16LE(0xdead, 0); buf.writeDoubleLE(0xdeadbeefcafebabe, 0);
buf.writeUInt16LE(0xbeef, 2);
console.log(buf); console.log(buf);
// <Buffer de ad be ef> // <Buffer 43 eb d5 b7 dd f9 5f d7>
// <Buffer ad de ef be> // <Buffer d7 5f f9 dd b7 d5 eb 43>
### buf.writeUInt32LE(value, offset[, noAssert]) ### buf.writeFloatBE(value, offset[, noAssert])
### buf.writeUInt32BE(value, offset[, noAssert]) ### buf.writeFloatLE(value, offset[, noAssert])
* `value` Number * `value` Number
* `offset` Number * `offset` Number
* `noAssert` Boolean, Optional, Default: false * `noAssert` Boolean, Optional, Default: false
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. Note, `value` must be a valid unsigned 32 bit integer. format. Note, behavior is unspecified if `value` is not a 32 bit 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
@ -700,16 +689,16 @@ should not be used unless you are certain of correctness. Defaults to `false`.
Example: Example:
var buf = new Buffer(4); var buf = new Buffer(4);
buf.writeUInt32BE(0xfeedface, 0); buf.writeFloatBE(0xcafebabe, 0);
console.log(buf); console.log(buf);
buf.writeUInt32LE(0xfeedface, 0); buf.writeFloatLE(0xcafebabe, 0);
console.log(buf); console.log(buf);
// <Buffer fe ed fa ce> // <Buffer 4f 4a fe bb>
// <Buffer ce fa ed fe> // <Buffer bb fe 4a 4f>
### buf.writeInt8(value, offset[, noAssert]) ### buf.writeInt8(value, offset[, noAssert])
@ -728,8 +717,8 @@ should not be used unless you are certain of correctness. Defaults to `false`.
Works as `buffer.writeUInt8`, except value is written out as a two's complement Works as `buffer.writeUInt8`, except value is written out as a two's complement
signed integer into `buffer`. signed integer into `buffer`.
### buf.writeInt16LE(value, offset[, noAssert])
### buf.writeInt16BE(value, offset[, noAssert]) ### buf.writeInt16BE(value, offset[, noAssert])
### buf.writeInt16LE(value, offset[, noAssert])
* `value` Number * `value` Number
* `offset` Number * `offset` Number
@ -746,8 +735,8 @@ should not be used unless you are certain of correctness. Defaults to `false`.
Works as `buffer.writeUInt16*`, except value is written out as a two's Works as `buffer.writeUInt16*`, except value is written out as a two's
complement signed integer into `buffer`. complement signed integer into `buffer`.
### buf.writeInt32LE(value, offset[, noAssert])
### buf.writeInt32BE(value, offset[, noAssert]) ### buf.writeInt32BE(value, offset[, noAssert])
### buf.writeInt32LE(value, offset[, noAssert])
* `value` Number * `value` Number
* `offset` Number * `offset` Number
@ -764,15 +753,33 @@ should not be used unless you are certain of correctness. Defaults to `false`.
Works as `buffer.writeUInt32*`, except value is written out as a two's Works as `buffer.writeUInt32*`, except value is written out as a two's
complement signed integer into `buffer`. complement signed integer into `buffer`.
### buf.writeFloatLE(value, offset[, noAssert]) ### buf.writeIntBE(value, offset, byteLength[, noAssert])
### buf.writeFloatBE(value, offset[, noAssert]) ### buf.writeIntLE(value, offset, byteLength[, noAssert])
* `value` {Number} Bytes to be written to buffer
* `offset` {Number} `0 <= offset <= buf.length`
* `byteLength` {Number} `0 < byteLength <= 6`
* `noAssert` {Boolean} Default: false
* Return: {Number}
Writes `value` to the buffer at the specified `offset` and `byteLength`.
Supports up to 48 bits of accuracy. For example:
var b = new Buffer(6);
b.writeUIntBE(0x1234567890ab, 0, 6);
// <Buffer 12 34 56 78 90 ab>
Set `noAssert` to `true` to skip validation of `value` and `offset`. Defaults
to `false`.
### buf.writeUInt8(value, offset[, noAssert])
* `value` Number * `value` Number
* `offset` Number * `offset` Number
* `noAssert` Boolean, Optional, Default: false * `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset with specified endian Writes `value` to the buffer at the specified offset. Note, `value` must be a
format. Note, behavior is unspecified if `value` is not a 32 bit float. 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
@ -782,26 +789,24 @@ should not be used unless you are certain of correctness. Defaults to `false`.
Example: Example:
var buf = new Buffer(4); var buf = new Buffer(4);
buf.writeFloatBE(0xcafebabe, 0); buf.writeUInt8(0x3, 0);
buf.writeUInt8(0x4, 1);
console.log(buf); buf.writeUInt8(0x23, 2);
buf.writeUInt8(0x42, 3);
buf.writeFloatLE(0xcafebabe, 0);
console.log(buf); console.log(buf);
// <Buffer 4f 4a fe bb> // <Buffer 03 04 23 42>
// <Buffer bb fe 4a 4f>
### buf.writeDoubleLE(value, offset[, noAssert]) ### buf.writeUInt16BE(value, offset[, noAssert])
### buf.writeDoubleBE(value, offset[, noAssert]) ### buf.writeUInt16LE(value, offset[, noAssert])
* `value` Number * `value` Number
* `offset` Number * `offset` Number
* `noAssert` Boolean, Optional, Default: false * `noAssert` Boolean, Optional, Default: false
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. Note, `value` must be a valid 64 bit double. format. Note, `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
@ -810,43 +815,67 @@ should not be used unless you are certain of correctness. Defaults to `false`.
Example: Example:
var buf = new Buffer(8); var buf = new Buffer(4);
buf.writeDoubleBE(0xdeadbeefcafebabe, 0); buf.writeUInt16BE(0xdead, 0);
buf.writeUInt16BE(0xbeef, 2);
console.log(buf); console.log(buf);
buf.writeDoubleLE(0xdeadbeefcafebabe, 0); buf.writeUInt16LE(0xdead, 0);
buf.writeUInt16LE(0xbeef, 2);
console.log(buf); console.log(buf);
// <Buffer 43 eb d5 b7 dd f9 5f d7> // <Buffer de ad be ef>
// <Buffer d7 5f f9 dd b7 d5 eb 43> // <Buffer ad de ef be>
### buf.fill(value[, offset][, end]) ### buf.writeUInt32BE(value, offset[, noAssert])
### buf.writeUInt32LE(value, offset[, noAssert])
* `value` * `value` Number
* `offset` Number, Optional * `offset` Number
* `end` Number, Optional * `noAssert` Boolean, Optional, Default: false
Fills the buffer with the specified value. If the `offset` (defaults to `0`) Writes `value` to the buffer at the specified offset with specified endian
and `end` (defaults to `buffer.length`) are not given it will fill the entire format. Note, `value` must be a valid unsigned 32 bit integer.
buffer.
var b = new Buffer(50); Set `noAssert` to true to skip validation of `value` and `offset`. This means
b.fill("h"); 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`.
### buffer.values() Example:
Creates iterator for buffer values (bytes). This function is called automatically var buf = new Buffer(4);
when `buffer` is used in a `for..of` statement. buf.writeUInt32BE(0xfeedface, 0);
### buffer.keys() console.log(buf);
Creates iterator for buffer keys (indices). buf.writeUInt32LE(0xfeedface, 0);
### buffer.entries() console.log(buf);
Creates iterator for `[index, byte]` arrays. // <Buffer fe ed fa ce>
// <Buffer ce fa ed fe>
### buf.writeUIntBE(value, offset, byteLength[, noAssert])
### buf.writeUIntLE(value, offset, byteLength[, noAssert])
* `value` {Number} Bytes to be written to buffer
* `offset` {Number} `0 <= offset <= buf.length`
* `byteLength` {Number} `0 < byteLength <= 6`
* `noAssert` {Boolean} Default: false
* Return: {Number}
Writes `value` to the buffer at the specified `offset` and `byteLength`.
Supports up to 48 bits of accuracy. For example:
var b = new Buffer(6);
b.writeUIntBE(0x1234567890ab, 0, 6);
// <Buffer 12 34 56 78 90 ab>
Set `noAssert` to `true` to skip validation of `value` and `offset`. Defaults
to `false`.
## buffer.INSPECT_MAX_BYTES ## buffer.INSPECT_MAX_BYTES

Write Preview
Loading…
Cancel
Save