Permalink
Browse files

update node

  • Loading branch information...
1 parent 14e7ede commit 328f9ce9d247fd6538761b68a78a163477c58f78 @tj committed Nov 4, 2013
Showing with 5,013 additions and 1,410 deletions.
  1. +1 −1 node.assert.md
  2. +126 −60 node.buffer.md
  3. +171 −52 node.child_process.md
  4. +271 −122 node.cluster.md
  5. +322 −135 node.crypto.md
  6. +32 −1 node.debugger.md
  7. +71 −17 node.dgram.md
  8. +37 −23 node.dns.md
  9. +214 −45 node.domain.md
  10. +45 −8 node.events.md
  11. +243 −103 node.fs.md
  12. +63 −22 node.globals.md
  13. +396 −252 node.http.md
  14. +59 −23 node.https.md
  15. +62 −16 node.modules.md
  16. +107 −35 node.net.md
  17. +42 −12 node.os.md
  18. +50 −7 node.path.md
  19. +517 −63 node.process.md
  20. +1 −1 node.readline.md
  21. +24 −1 node.repl.md
  22. +1,452 −106 node.stream.md
  23. +33 −0 node.timers.md
  24. +250 −97 node.tls.md
  25. +1 −1 node.tty.md
  26. +5 −1 node.url.md
  27. +140 −43 node.util.md
  28. +176 −138 node.vm.md
  29. +102 −25 node.zlib.md
View
@@ -74,7 +74,7 @@ Custom error validation:
"unexpected error"
);
-## assert.doesNotThrow(block, [error], [message])
+## assert.doesNotThrow(block, [message])
Expects `block` not to throw an error, see assert.throws for details.
View
@@ -2,7 +2,7 @@
Stability: 3 - Stable
-Pure Javascript is Unicode friendly but not nice to binary data. When
+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
streams. Node has several strategies for manipulating, creating, and
consuming octet streams.
@@ -19,9 +19,6 @@ 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'`.
* `'utf8'` - Multibyte encoded Unicode characters. Many web pages and other
document formats use UTF-8.
@@ -65,6 +62,76 @@ Allocates a new buffer using an `array` of octets.
Allocates a new buffer containing the given `str`.
`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])
+
+* `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
+number of *characters* in a string.
+
+Example:
+
+ str = '\u00bd + \u00bc = \u00be';
+
+ console.log(str + ": " + str.length + " characters, " +
+ Buffer.byteLength(str, 'utf8') + " bytes");
+
+ // ½ + ¼ = ¾: 9 characters, 12 bytes
+
+### Class Method: Buffer.concat(list, [totalLength])
+
+* `list` {Array} List of Buffer objects to concat
+* `totalLength` {Number} Total length of the buffers when concatenated
+
+Returns a buffer which is the result of concatenating all the buffers in
+the list together.
+
+If the list has no items, or if the totalLength is 0, then it returns a
+zero-length buffer.
+
+If the list has exactly one item, then the first item of the list is
+returned.
+
+If the list has more than one item, then a new Buffer is created.
+
+If totalLength is not provided, it is read from the buffers in the list.
+However, this adds an additional loop to the function, so it is faster
+to provide the length explicitly.
+
+### 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
+
### buf.write(string, [offset], [length], [encoding])
* `string` String - data to be written to buffer
@@ -83,10 +150,6 @@ The method will not write partial characters.
len = buf.write('\u00bd + \u00bc = \u00be', 0);
console.log(len + " bytes: " + buf.toString('utf8', 0, len));
-The number of characters written (which may be different than the number of
-bytes written) is set in `Buffer._charsWritten` and will be overwritten the
-next time `buf.write()` is called.
-
### buf.toString([encoding], [start], [end])
@@ -101,6 +164,28 @@ Decodes and returns a string from buffer data encoded with `encoding`
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[index]
<!--type=property-->
@@ -122,49 +207,6 @@ Example: copy an ASCII string into a buffer, one byte at a time:
// node.js
-### Class Method: Buffer.isBuffer(obj)
-
-* `obj` Object
-* Return: Boolean
-
-Tests if `obj` is a `Buffer`.
-
-### 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
-number of *characters* in a string.
-
-Example:
-
- str = '\u00bd + \u00bc = \u00be';
-
- console.log(str + ": " + str.length + " characters, " +
- Buffer.byteLength(str, 'utf8') + " bytes");
-
- // ½ + ¼ = ¾: 9 characters, 12 bytes
-
-### 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
-
### buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])
* `targetBuffer` Buffer object - Buffer to copy into
@@ -176,6 +218,9 @@ Does copy between buffers. The source and target regions can be overlapped.
`targetStart` and `sourceStart` default to `0`.
`sourceEnd` defaults to `buffer.length`.
+All values passed that are `undefined`/`NaN` or are out of bounds are set equal
+to their respective defaults.
+
Example: build two Buffers, then copy `buf1` from byte 16 through byte 19
into `buf2`, starting at the 8th byte in `buf2`.
@@ -200,7 +245,7 @@ into `buf2`, starting at the 8th byte in `buf2`.
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.
+`buffer.length`) indexes. Negative indexes start from the end of the buffer.
**Modifying the new buffer slice will modify memory in the original buffer!**
@@ -563,7 +608,7 @@ complement signed integer into `buffer`.
* `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.
+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
that `value` may be too large for the specific function and `offset` may be
@@ -626,6 +671,10 @@ buffer.
var b = new Buffer(50);
b.fill("h");
+### buf.toArrayBuffer()
+
+Creates a new `ArrayBuffer` with the copied memory of the buffer instance.
+
## buffer.INSPECT_MAX_BYTES
* Number, Default: 50
@@ -638,11 +687,28 @@ Note that this is a property on the buffer module returned by
## Class: SlowBuffer
-This class is primarily for internal use. JavaScript programs should
-use Buffer instead of using SlowBuffer.
+Returns an un-pooled `Buffer`.
+
+In order to avoid the garbage collection overhead of creating many individually
+allocated Buffers, by default allocations under 4KB are sliced from a single
+larger allocated object. This approach improves both performance and memory
+usage since v8 does not need to track and cleanup as many `Persistent` objects.
+
+In the case where a developer may need to retain a small chunk of memory from a
+pool for an indeterminate amount of time it may be appropriate to create an
+un-pooled Buffer instance using SlowBuffer and copy out the relevant bits.
+
+ // need to keep around a few small chunks of memory
+ var store = [];
+
+ socket.on('readable', function() {
+ var data = socket.read();
+ // allocate for retained data
+ var sb = new SlowBuffer(10);
+ // copy the data into the new allocation
+ data.copy(sb, 0, 0, 10);
+ store.push(sb);
+ });
-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.
+Though this should used sparingly and only be a last resort *after* a developer
+has actively observed undue memory retention in their applications.
Oops, something went wrong.

0 comments on commit 328f9ce

Please sign in to comment.