Encodings/B

Draft 1

This document describes an interface for converting streams of bytes to characters and vice versa.

It pays special attention on the requirements of asynchronous streaming where no assumptions can be made about character alignment.

The Decoder and Encoder classes also provide convenience methods to attach them to input or output streams for synchonous operation.

Specification

Platforms implementing this specifications provide an encoding module exporting the classes described below.

Decoder

Constructor

[new] Decoder(encoding string, [strict boolean], [capacity number]) Decoder

Create a new Decoder instance that will decode bytes to characters using the given encoding.

A decoder encapsulates an character buffer for decoded output, and a binary input buffer for storing partial character input between invocations of decode(). The initial size of the output buffer is set to capacity or a default value if capacity is undefined. All buffers are growable and will be resized as required.

If strict is true, the decoder will throw Errors on illegal input; otherwise, it will silently accept illegal input.

Instance Methods

decode(buffer Binary, [start number], [end number]) Decoder

Try to decode the content of buffer, appending the result to the internal character buffer. If start and end are defined and valid indices for buffer, only the region between start (inclusive) and end (exclusive) are decoded.

If the Decoder was constructed with true as strict argument, this method throws an Error if the input is not valid for the decoder's encoding.

The method returns this decoder for chainability.

toString() string

Return the content of the internal character buffer as string. This includes all content decoded since the Decoder was created or clear() was invoked on it.

clear() Decoder

Reset the output buffer, discarding all content decoded so far. This does not reset the input buffer, so any bytes representing a partial character are kept for later invocations of decode().

The method returns this decoder for chainability.

hasPendingInput() boolean

Return true if there any bytes representing a partial character in the decoder's internal input buffer, false otherwise.

close() Decoder

Closes the decoder. The decoder must not be used after close() was invoked.

If the Decoder was constructed in strict mode, this method throws an Error if there are any pending bytes in its input buffer.

The method returns this decoder for chainability.

readFrom(source Stream)

If this method is invoked, input is read from source which must be a readable stream.

readLine(includeNewline) string

Return a string containing all decoded characters up to the first line break, or null if no line break was found in the current output buffer. A line break is either "\

", "\ ", or "\ \ ". If Boolean(includeNewline) is true the line break is included with the return value.

If a source stream was defined using the readFrom method, more bytes are read form the source stream until a line break or EOF is encountered.

Instance Properties

length number

Return the length of the decoded output in character units. This property is not writable.

Encoder

Constructor

[new] Encoder(encoding string, [strict boolean], [capacity number]) Encoder

Create a new Encoder instance that will encode characters to bytes using the given encoding.

An encoder encapsulates an byte buffer for encoded output. The initial size of the size of the buffer is set to capacity or a default value if capacity is undefined, and will grow to accommodate encoded output as required.

If strict is true, the decoder will throw Errors on illegal input; otherwise, it will silently accept illegal input.

Instance Methods

encode(str string, [start number], [end number]) Encoder

Try to encode the content of str, appending the result to the internal byte buffer. If start and end are defined and valid indices for str, only the region between start (inclusive) and end (exclusive) are decoded.

If the Encoder was constructed with true as strict argument, this method throws an Error if the input is not valid for the decoder's encoding.

The method returns this encoder for chainability.

toBuffer|ByteArray|ByteString() Buffer|ByteArray|ByteString

Return the content of the internal byte buffer as a binary buffer. This includes all content encoded since the Encoder was created or clear() was invoked on it.

clear() Encoder

Reset the output buffer, discarding all content encoder so far.

The method returns this decoder for chainability.

close() Encoder

Closes the encoder. The encoder must not be used after close() was invoked.

If the Decoder was constructed in strict mode, this method throws an Error if the encoder .

The method returns this decoder for chainability.

writeTo(sink Stream)

If this method is invoked, all output is directly written to the sink which must be a writable stream instead of keeping it in the internal output buffer.

Instance Properties

length number

Return the length of the encoded output in bytes. This property is not writable.

Implementations

An implementation of this proposal is available and used for all text streams in RingoJS