doc refactor: buffers

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
+Converting between Buffers and JavaScript string objects requires an explicit
-method.  Here are the different string encodings;
+encoding method.  Here are the different string encodings.
 
-* `'ascii'` - for 7 bit ASCII data only.  This encoding method is very fast, and will
+* `'ascii'` - for 7 bit ASCII data only.  This encoding method is very fast, and
-strip the high bit if set.
+  will strip the high bit if set.
-Note that this encoding converts a null character (`'\0'` or `'\u0000'`) into
+  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
+  `0x20` (character code of a space). If you want to convert a null character
-into `0x00`, you should use `'utf8'`.
+  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
+  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
+  should be avoided in favor of `Buffer` objects where possible. This encoding
-will be removed in future versions of Node.
+  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])
+### buf.readUInt16LE(offset, [noAssert])
-### buffer.readUInt16BE(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])
+### buf.readUInt32LE(offset, [noAssert])
-### buffer.readUInt32BE(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])
+### buf.readInt16LE(offset, [noAssert])
-### buffer.readInt16BE(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])
+### buf.readInt32LE(offset, [noAssert])
-### buffer.readInt32BE(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])
+### buf.readFloatLE(offset, [noAssert])
-### buffer.readFloatBE(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])
+### buf.readDoubleLE(offset, [noAssert])
-### buffer.readDoubleBE(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])
+### buf.writeUInt16LE(value, offset, [noAssert])
-### buffer.writeUInt16BE(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])
+### buf.writeUInt32LE(value, offset, [noAssert])
-### buffer.writeUInt32BE(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])
+### buf.writeInt16LE(value, offset, [noAssert])
-### buffer.writeInt16BE(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])
+### buf.writeInt32LE(value, offset, [noAssert])
-### buffer.writeInt32BE(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])
+### buf.writeFloatLE(value, offset, [noAssert])
-### buffer.writeFloatBE(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])
+### buf.writeDoubleLE(value, offset, [noAssert])
-### buffer.writeDoubleBE(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.