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
- clear()
- close()
- decode(bytes, start, end)
- hasPendingInput()
- read()
- readFrom(source)
- readLine(includeNewline)
- toString()
Instance Properties
Class Encoder
Instance Methods
- clear()
- close()
- encode(string, start, end)
- toByteArray()
- toByteString()
- toString()
- writeTo(sink)
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 stringParameters
| io.Stream | source | the source stream |
See
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
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. 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 |