From 03d6aa07ea8d267adb2101b333849251d45dd134 Mon Sep 17 00:00:00 2001 From: isaacs Date: Mon, 27 Feb 2012 11:07:25 -0800 Subject: [PATCH] doc refactor: buffers --- doc/api/buffers.markdown | 228 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 177 insertions(+), 51 deletions(-) diff --git a/doc/api/buffers.markdown b/doc/api/buffers.markdown index 3bc9559..0186642 100644 --- a/doc/api/buffers.markdown +++ b/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,46 +11,63 @@ 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. -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'`. +* `'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'`. * `'utf8'` - Multi byte encoded Unicode characters. Many web pages and other document formats use UTF-8. * `'ucs2'` - 2-bytes, little endian encoded Unicode characters. It can encode -only BMP(Basic Multilingual Plane, U+0000 - U+FFFF). + only BMP(Basic Multilingual Plane, U+0000 - U+FFFF). * `'base64'` - Base64 string encoding. * `'binary'` - A way of encoding raw binary data into strings by using only -the first 8 bits of each character. This encoding method is deprecated and -should be avoided in favor of `Buffer` objects where possible. This encoding -will be removed in future versions of Node. + the first 8 bits of each character. This encoding method is deprecated and + should be avoided in favor of `Buffer` objects where possible. This encoding + 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] + + + 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.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.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.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.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.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. -- 2.7.4