Browse Source

doc refactor: buffers

v0.9.1-release
isaacs 13 years ago
parent
commit
60aa852a03
  1. 214
      doc/api/buffers.markdown

214
doc/api/buffers.markdown

@ -1,4 +1,6 @@
## Buffers
# Buffer
Stability: 3 - Stable
Pure Javascript is Unicode friendly but not nice to binary data. When
dealing with TCP streams or the file system, it's necessary to handle octet
@ -9,13 +11,14 @@ Raw data is stored in instances of the `Buffer` class. A `Buffer` is similar
to an array of integers but corresponds to a raw memory allocation outside
the V8 heap. A `Buffer` cannot be resized.
The `Buffer` object is global.
The `Buffer` class is a global, making it very rare that one would need
to ever `require('buffer')`.
Converting between Buffers and JavaScript string objects requires an explicit encoding
method. Here are the different string encodings;
Converting between Buffers and JavaScript string objects requires an explicit
encoding method. Here are the different string encodings.
* `'ascii'` - for 7 bit ASCII data only. This encoding method is very fast, and will
strip the high bit if set.
* `'ascii'` - for 7 bit ASCII data only. This encoding method is very fast, and
will strip the high bit if set.
Note that this encoding converts a null character (`'\0'` or `'\u0000'`) into
`0x20` (character code of a space). If you want to convert a null character
into `0x00`, you should use `'utf8'`.
@ -34,21 +37,37 @@ will be removed in future versions of Node.
* `'hex'` - Encode each byte as two hexidecimal characters.
## Class: Buffer
The Buffer class is a global type for dealing with binary data directly.
It can be constructed in a variety of ways.
### new Buffer(size)
* `size` Number
Allocates a new buffer of `size` octets.
### new Buffer(array)
* `array` Array
Allocates a new buffer using an `array` of octets.
### new Buffer(str, [encoding])
* `str` String - string to encode.
* `encoding` String - encoding to use, Optional.
Allocates a new buffer containing the given `str`.
`encoding` defaults to `'utf8'`.
### buffer.write(string, [offset], [length], [encoding])
### buf.write(string, [offset], [length], [encoding])
* `string` String - data to be written to buffer
* `offset` Number, Optional, Default: 0
* `length` Number, Optional
* `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
@ -66,7 +85,11 @@ bytes written) is set in `Buffer._charsWritten` and will be overwritten the
next time `buf.write()` is called.
### buffer.toString(encoding, [start], [end])
### buf.toString([encoding], [start], [end])
* `encoding` String, Optional, Default: 'utf8'
* `start` Number, Optional, Default: 0
* `end` Number, Optional
Decodes and returns a string from buffer data encoded with `encoding`
(defaults to `'utf8'`) beginning at `start` (defaults to `0`) and ending at
@ -75,7 +98,10 @@ Decodes and returns a string from buffer data encoded with `encoding`
See `buffer.write()` example, above.
### buffer[index]
### buf[index]
<!--type=property-->
<!--name=[index]-->
Get and set the octet at `index`. The values refer to individual bytes,
so the legal range is between `0x00` and `0xFF` hex or `0` and `255`.
@ -93,11 +119,18 @@ Example: copy an ASCII string into a buffer, one byte at a time:
// node.js
### Buffer.isBuffer(obj)
### Class Method: Buffer.isBuffer(obj)
* `obj` Object
* Return: Boolean
Tests if `obj` is a `Buffer`.
### Buffer.byteLength(string, [encoding])
### Class Method: Buffer.byteLength(string, [encoding])
* `string` String
* `encoding` String, Optional, Default: 'utf8'
* Return: Number
Gives the actual byte length of a string. `encoding` defaults to `'utf8'`.
This is not the same as `String.prototype.length` since that returns the
@ -112,8 +145,9 @@ Example:
// ½ + ¼ = ¾: 9 characters, 12 bytes
### buf.length
### buffer.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
@ -128,7 +162,12 @@ buffer object. It does not change when the contents of the buffer are changed.
// 1234
// 1234
### buffer.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])
### 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: 0
Does copy between buffers. The source and target regions can be overlapped.
`targetStart` and `sourceStart` default to `0`.
@ -151,7 +190,10 @@ into `buf2`, starting at the 8th byte in `buf2`.
// !!!!!!!!qrst!!!!!!!!!!!!!
### buffer.slice([start], [end])
### buf.slice([start], [end])
* `start` Number, Optional, Default: 0
* `end` Number, Optional, Default: 0
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
@ -176,7 +218,11 @@ byte from the original Buffer.
// abc
// !bc
### buffer.readUInt8(offset, [noAssert])
### buf.readUInt8(offset, [noAssert])
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
* Return: Number
Reads an unsigned 8 bit integer from the buffer at the specified offset.
@ -201,8 +247,12 @@ Example:
// 0x23
// 0x42
### buffer.readUInt16LE(offset, [noAssert])
### buffer.readUInt16BE(offset, [noAssert])
### buf.readUInt16LE(offset, [noAssert])
### buf.readUInt16BE(offset, [noAssert])
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
* Return: Number
Reads an unsigned 16 bit integer from the buffer at the specified offset with
specified endian format.
@ -233,8 +283,12 @@ Example:
// 0x2342
// 0x4223
### buffer.readUInt32LE(offset, [noAssert])
### buffer.readUInt32BE(offset, [noAssert])
### buf.readUInt32LE(offset, [noAssert])
### buf.readUInt32BE(offset, [noAssert])
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
* Return: Number
Reads an unsigned 32 bit integer from the buffer at the specified offset with
specified endian format.
@ -257,7 +311,11 @@ Example:
// 0x03042342
// 0x42230403
### buffer.readInt8(offset, [noAssert])
### buf.readInt8(offset, [noAssert])
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
* Return: Number
Reads a signed 8 bit integer from the buffer at the specified offset.
@ -267,8 +325,12 @@ may be beyond the end of the buffer. Defaults to `false`.
Works as `buffer.readUInt8`, except buffer contents are treated as two's
complement signed values.
### buffer.readInt16LE(offset, [noAssert])
### buffer.readInt16BE(offset, [noAssert])
### buf.readInt16LE(offset, [noAssert])
### buf.readInt16BE(offset, [noAssert])
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
* Return: Number
Reads a signed 16 bit integer from the buffer at the specified offset with
specified endian format.
@ -279,8 +341,12 @@ may be beyond the end of the buffer. Defaults to `false`.
Works as `buffer.readUInt16*`, except buffer contents are treated as two's
complement signed values.
### buffer.readInt32LE(offset, [noAssert])
### buffer.readInt32BE(offset, [noAssert])
### buf.readInt32LE(offset, [noAssert])
### buf.readInt32BE(offset, [noAssert])
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
* Return: Number
Reads a signed 32 bit integer from the buffer at the specified offset with
specified endian format.
@ -291,8 +357,12 @@ may be beyond the end of the buffer. Defaults to `false`.
Works as `buffer.readUInt32*`, except buffer contents are treated as two's
complement signed values.
### buffer.readFloatLE(offset, [noAssert])
### buffer.readFloatBE(offset, [noAssert])
### buf.readFloatLE(offset, [noAssert])
### buf.readFloatBE(offset, [noAssert])
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
* Return: Number
Reads a 32 bit float from the buffer at the specified offset with specified
endian format.
@ -313,8 +383,12 @@ Example:
// 0x01
### buffer.readDoubleLE(offset, [noAssert])
### buffer.readDoubleBE(offset, [noAssert])
### buf.readDoubleLE(offset, [noAssert])
### buf.readDoubleBE(offset, [noAssert])
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
* Return: Number
Reads a 64 bit double from the buffer at the specified offset with specified
endian format.
@ -339,7 +413,11 @@ Example:
// 0.3333333333333333
### buffer.writeUInt8(value, offset, [noAssert])
### buf.writeUInt8(value, offset, [noAssert])
* `value` Number
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset. Note, `value` must be a
valid unsigned 8 bit integer.
@ -361,8 +439,12 @@ Example:
// <Buffer 03 04 23 42>
### buffer.writeUInt16LE(value, offset, [noAssert])
### buffer.writeUInt16BE(value, offset, [noAssert])
### buf.writeUInt16LE(value, offset, [noAssert])
### buf.writeUInt16BE(value, offset, [noAssert])
* `value` Number
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset with specified endian
format. Note, `value` must be a valid unsigned 16 bit integer.
@ -388,8 +470,12 @@ Example:
// <Buffer de ad be ef>
// <Buffer ad de ef be>
### buffer.writeUInt32LE(value, offset, [noAssert])
### buffer.writeUInt32BE(value, offset, [noAssert])
### buf.writeUInt32LE(value, offset, [noAssert])
### buf.writeUInt32BE(value, offset, [noAssert])
* `value` Number
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset with specified endian
format. Note, `value` must be a valid unsigned 32 bit integer.
@ -413,7 +499,11 @@ Example:
// <Buffer fe ed fa ce>
// <Buffer ce fa ed fe>
### buffer.writeInt8(value, offset, [noAssert])
### buf.writeInt8(value, offset, [noAssert])
* `value` Number
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset. Note, `value` must be a
valid signed 8 bit integer.
@ -426,8 +516,12 @@ 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
signed integer into `buffer`.
### buffer.writeInt16LE(value, offset, [noAssert])
### buffer.writeInt16BE(value, offset, [noAssert])
### buf.writeInt16LE(value, offset, [noAssert])
### buf.writeInt16BE(value, offset, [noAssert])
* `value` Number
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset with specified endian
format. Note, `value` must be a valid signed 16 bit integer.
@ -440,8 +534,12 @@ 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
complement signed integer into `buffer`.
### buffer.writeInt32LE(value, offset, [noAssert])
### buffer.writeInt32BE(value, offset, [noAssert])
### buf.writeInt32LE(value, offset, [noAssert])
### buf.writeInt32BE(value, offset, [noAssert])
* `value` Number
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset with specified endian
format. Note, `value` must be a valid signed 32 bit integer.
@ -454,8 +552,12 @@ 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
complement signed integer into `buffer`.
### buffer.writeFloatLE(value, offset, [noAssert])
### buffer.writeFloatBE(value, offset, [noAssert])
### buf.writeFloatLE(value, offset, [noAssert])
### buf.writeFloatBE(value, offset, [noAssert])
* `value` Number
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset with specified endian
format. Note, `value` must be a valid 32 bit float.
@ -479,8 +581,12 @@ Example:
// <Buffer 4f 4a fe bb>
// <Buffer bb fe 4a 4f>
### buffer.writeDoubleLE(value, offset, [noAssert])
### buffer.writeDoubleBE(value, offset, [noAssert])
### buf.writeDoubleLE(value, offset, [noAssert])
### buf.writeDoubleBE(value, offset, [noAssert])
* `value` Number
* `offset` Number
* `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset with specified endian
format. Note, `value` must be a valid 64 bit double.
@ -504,7 +610,11 @@ Example:
// <Buffer 43 eb d5 b7 dd f9 5f d7>
// <Buffer d7 5f f9 dd b7 d5 eb 43>
### buffer.fill(value, [offset], [end])
### buf.fill(value, [offset], [end])
* `value`
* `offset` Number, Optional
* `end` Number, Optional
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
@ -513,7 +623,23 @@ buffer.
var b = new Buffer(50);
b.fill("h");
### INSPECT_MAX_BYTES
## buffer.INSPECT_MAX_BYTES
* Number, Default: 50
How many bytes will be returned when `buffer.inspect()` is called. This can
be overridden by user modules.
Note that this is a property on the buffer module returned by
`require('buffer')`, not on the Buffer global, or a buffer instance.
## Class: SlowBuffer
This class is primarily for internal use. JavaScript programs should
use Buffer instead of using SlowBuffer.
In order to avoid the overhead of allocating many C++ Buffer objects for
small blocks of memory in the lifetime of a server, Node allocates memory
in 8Kb (8192 byte) chunks. If a buffer is smaller than this size, then it
will be backed by a parent SlowBuffer object. If it is larger than this,
then Node will allocate a SlowBuffer slab for it directly.

Loading…
Cancel
Save