Skip to content

Commit

Permalink
doc: two minor stream doc improvements
Browse files Browse the repository at this point in the history
per: nodejs/node-v0.x-archive#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: nodejs/node-v0.x-archive#25591
  • Loading branch information
jasnell committed Aug 4, 2015
1 parent c6d7974 commit 034b4d5
Showing 1 changed file with 7 additions and 1 deletion.
8 changes: 7 additions & 1 deletion doc/api/stream.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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.)
Expand Down

0 comments on commit 034b4d5

Please sign in to comment.