diff options
| author | James M Snell <jasnell@gmail.com> | 2015-07-01 12:52:47 -0700 |
|---|---|---|
| committer | James M Snell <jasnell@gmail.com> | 2015-08-03 20:44:42 -0700 |
| commit | 14000b97d463d9110cbd322c1a9ebf6c99530167 (patch) | |
| tree | 7f659286a1a99b5097da15b09cf5f3d5ff7c63d9 | |
| parent | 8cbf7cb0218ec0124c6edf035cb50824d2ee709f (diff) | |
| download | node-14000b97d463d9110cbd322c1a9ebf6c99530167.tar.gz | |
doc: two minor stream doc improvements
per: https://github.com/joyent/node/issues/14596
1. document that a runtime error will occur if you attempt
to unshift after the end event
2. document that calling read after the end event will return
null and will not trigger a runtime error
Reviewed-By: James M Snell <jasnell@gmail.com>
PR-URL: https://github.com/joyent/node/pull/25591
| -rw-r--r-- | doc/api/stream.markdown | 8 |
1 files changed, 7 insertions, 1 deletions
diff --git a/doc/api/stream.markdown b/doc/api/stream.markdown index b3859d343..42cb7e3d7 100644 --- a/doc/api/stream.markdown +++ b/doc/api/stream.markdown @@ -228,7 +228,7 @@ returns it. If there is no data available, then it will return If you pass in a `size` argument, then it will return that many bytes. If `size` bytes are not available, then it will return `null`, -unless we've ended, in which case it will return the data remaining +unless we've ended, in which case it will return the data remaining in the buffer. If you do not specify a `size` argument, then it will return all the @@ -251,6 +251,9 @@ readable.on('readable', function() { If this method returns a data chunk, then it will also trigger the emission of a [`'data'` event][]. +Note that calling `readable.read([size])` after the `end` event has been +triggered will return `null`. No runtime error will be raised. + #### readable.setEncoding(encoding) * `encoding` {String} The encoding to use. @@ -422,6 +425,9 @@ parser, which needs to "un-consume" some data that it has optimistically pulled out of the source, so that the stream can be passed on to some other party. +Note that `stream.unshift(chunk)` cannot be called after the `end` event +has been triggered; a runtime error will be raised. + If you find that you must often call `stream.unshift(chunk)` in your programs, consider implementing a [Transform][] stream instead. (See API for Stream Implementors, below.) |