doc update to encodings supported by fs.ReadStream setEncoding

[mvolkmann]

The docs at http://nodejs.org/docs/latest/api/stream.html#stream_stream_setencoding_encoding
say that the encoding "can be 'utf8', 'ascii', or 'base64'".
Add 'binary', 'hex' and 'ucs2' to the list.

[bnoordhuis]

Mailing list thread: http://groups.google.com/group/nodejs/browse_thread/thread/ba9f57e1f45953ca

This is really two issues:

1. fs.ReadStream.setEncoding() accepts more than just 'utf8', 'ascii' and 'base64'
2. stream.Stream.setEncoding() doesn't really exist. The Stream interface is a protocol, it's up to implementing classes to provide the concrete implementation.

The first one would be easy to fix were it not for the fact that fs.ReadStream.setEncoding() is not separately documented (it links to the streams API page).

@isaacs: re the second issue: what are the plans for the stream API? .setEncoding() seems like an unfortunate addition.

[koichik]

Currently, 'ucs2' is not supported.

Because 'ucs2' is multi byte character encoding, StringDecoder should handle an incomplete character
(when a chunk breaks off at first 1 byte of a character, it is necessary to be combined with the next chunk),but does not.

Refs: #1681.

[isaacs]

I think perhaps setEncoding should just be removed from the Stream doc, and added in the documentation of the various streams where it's actually used.

A more thorough streams cleanup is planned for v0.9. A setEncoding method would be ok, perhaps using the string_decoder under the hood if necessary.

[papandreou]

Now that you're mentioning the rewrite -- in my opinion StringDecoder should be exposed as a standalone filter (read/writable stream) rather than being built into every readable stream. That would make it more composable and get rid of setEncoding:

readableStream.pipe(new StringDecoder('utf-8')).on('data', function (text) {...});

[chrisdickinson]

Encoding is now mentioned in the streams docs as referring to valid buffer encodings.