RingoJS

Module ringo/encoding

Low-level support for character encoding and decoding. It uses the packages java.nio and java.nio.charset for the underlying operations.

Example

const enc = new Encoder('utf-8');
enc.encode('I \u2665 JS').encode('I \u2665 JS');
const bs = enc.toByteString();

// prints 'I ♥ JSI ♥ JS'
console.log(bs.decodeToString('utf-8'));

const dec = new Decoder('ISO-8859-1');
const ba = new ByteArray([246, 228, 252]);

// prints öäü
console.log(dec.decode(ba));

Class Decoder

Instance Methods

Instance Properties

Class Encoder

Instance Methods

Instance Properties


Decoder (charset, strict, capacity)

Creates a new Decoder to transform a ByteString or ByteArray to a string.

Example

// throws an Error: MALFORMED[1]
const dec = new Decoder('ASCII', true);
dec.decode(new ByteArray([246, 228, 252, 999999]));

// replaces 999999 with a substitutions character ���
const dec = new Decoder('ASCII');
dec.decode(new ByteArray([246, 228, 252, 999999]));

Parameters

String charset

the charset name

Boolean strict

if true, unmappable characters stop the decoder and throw an exception, otherwise malformed input is replaced with a substitution character

Number capacity

initial capacity for the input byte buffer and output character buffer. The output buffer's size depends on the average bytes used per character by the charset.


Decoder.prototype. clear ()

Clears the character buffer.

Example

dec.decode(someByteArray);
dec.toString(); // returns the decoded string
dec.clear();
dec.toString(); // returns ''

Decoder.prototype. close ()

Closes the decoder for further input. A closed decoder throws a java.nio.BufferOverflowException if decode() is called again.

Returns

Decoder

the decoder


Decoder.prototype. decode (bytes, start, end)

Decode bytes from the given buffer.

Parameters

binary.Binary bytes

a ByteString or ByteArray

Number start

The start index, or 0 if undefined

Number end

the end index, or bytes.length if undefined


Decoder.prototype. hasPendingInput ()

Checks if all bytes are already decoded or if there is pending input.

Returns

Boolean

true if there not all bytes are decoded, false otherwise


Decoder.prototype. length

The character buffer's length which uses the Java primitive char internally. Each character in the buffer is a 16-bit Unicode character.

Example

// an emoji in 4 raw bytes
const ba = new ByteArray([0xF0,0x9F,0x98,0x98]);

// a UTF-8 based decoder
const dec = new Decoder("UTF-8");

// prints 😘
console.log(dec.decode(ba));

// prints "2 chars vs. 4 bytes"
console.log(dec.length + " chars vs. " + ba.length + " bytes");

Decoder.prototype. read ()

Reads the whole stream and returns it as a string. This method is only useful if the decoder has a connected stream.

Returns

String

the decoded string

See


Decoder.prototype. readFrom (source)

Sets the source stream to read from. Using io streams is an alternative to reading from plain binary ByteArray or ByteString objects.

Example

const stream = new MemoryStream();
stream.write(...); // write some bytes into the stream
stream.position = 0; // reset the pointer

const dec = new Decoder('ASCII');
dec.readFrom(stream); // connect the stream with the decoder
dec.read(); // returns the stream's content as string

Parameters

io.Stream source

the source stream


Decoder.prototype. readLine (includeNewline)

Reads a stream line by line and returns it as a string. This method is only useful if the decoder has a connected stream.

Parameters

Boolean includeNewline

if true, the newline character is included in the result, otherwise not

Returns

String

the decoded string or null if stream is empty

See


Decoder.prototype. toString ()

Returns the decoded string.

Returns

String

the decoded string


Encoder (charset, strict, capacity)

Creates a new Encoder to transform string into a binary ByteString or ByteArray.

Parameters

String charset

the charset name

Boolean strict

if true, unmappable characters stop the decoder and throw an exception, otherwise malformed input is replaced with a substitution character

Number capacity

initial capacity for the input character buffer and output byte buffer. The binary buffer's size depends on the average bytes used per character by the charset.


Encoder.prototype. clear ()

Clears the byte buffer.

Returns

Encoder

the cleared encoder


Encoder.prototype. close ()

Closes the encoder.

Returns

Encoder

the now closed encoder


Encoder.prototype. encode (string, start, end)

Encodes the given string into the encoder's binary buffer.

Example

// this will only encode 'e' and 'f'
enc.encode("abcdef", 4, 6);

Parameters

String string

the string to encode

Number start

optional index of the first character to encode

Number end

optional index of the character after the last character to encode


Encoder.prototype. length

The underlying byte buffer's length.


Encoder.prototype. toByteArray ()

Converts the encoded bytes into a ByteArray.

Returns

ByteArray

the resulting ByteArray


Encoder.prototype. toByteString ()

Converts the encoded bytes into a ByteString.

Returns

ByteString

the resulting ByteString


Encoder.prototype. toString ()


Encoder.prototype. writeTo (sink)

Sets the output stream to write into. Using io streams as destination is an alternative to writing into plain binary ByteArray or ByteString objects.

Parameters

Stream sink

the destination stream