Converters for JSON and UTF-8, as well as support for creating additional converters.
An instance of the default implementation of the AsciiCodec
.
This instance provides a convenient access to the most common ASCII use cases.
Examples:
var encoded = ASCII.encode("This is ASCII!"); var decoded = ASCII.decode([0x54, 0x68, 0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x41, 0x53, 0x43, 0x49, 0x49, 0x21]);
An instance of the default implementation of the JsonCodec
.
This instance provides a convenient access to the most common JSON use cases.
Examples:
var encoded = JSON.encode([1, 2, { "a": null }]); var decoded = JSON.decode('["foo", { "bar": 499 }]');
An instance of the default implementation of the Latin1Codec
.
This instance provides a convenient access to the most common ISO Latin 1 use cases.
Examples:
var encoded = LATIN1.encode("blåbærgrød"); var decoded = LATIN1.decode([0x62, 0x6c, 0xe5, 0x62, 0xe6, 0x72, 0x67, 0x72, 0xf8, 0x64]);
The Unicode Replacement character U+FFFD
(�).
An instance of the default implementation of the Utf8Codec
.
This instance provides a convenient access to the most common UTF-8 use cases.
Examples:
var encoded = UTF8.encode("Îñţérñåţîöñåļîžåţîờñ"); var decoded = UTF8.decode([0x62, 0x6c, 0xc3, 0xa5, 0x62, 0xc3, 0xa6, 0x72, 0x67, 0x72, 0xc3, 0xb8, 0x64]);
An AsciiCodec
allows encoding strings as ASCII bytes and decoding ASCII bytes to strings.
Instantiates a new AsciiCodec
.
If allowInvalid
is true, the decode
method and the converter returned by decoder
will default to allowing invalid values. If allowing invalid values, the values will be decoded into the Unicode Replacement character (U+FFFD). If not, an exception will be thrown. Calls to the decode
method can choose to override this default.
Encoders will not accept invalid (non Latin-1) characters.
Decodes the ASCII bytes
(a list of unsigned 7-bit integers) to the corresponding string.
If bytes
contains values that are not in the range 0 .. 127, the decoder will eventually throw a FormatException
.
If allowInvalid
is not provided, it defaults to the value used to create this AsciiCodec
.
Starts a chunked conversion.
The converter works more efficiently if the given sink
is a StringConversionSink
.
This class converts strings of only ASCII characters to bytes.
The ByteConversionSink
provides an interface for converters to efficiently transmit byte data.
Instead of limiting the interface to one non-chunked list of bytes it accepts its input in chunks (themselves being lists of bytes).
Adds the next chunk
to this
.
Adds the bytes defined by start
and end
-exclusive to this
.
If isLast
is true
closes this
.
Contrary to add
the given chunk
must not be held onto. Once the method returns, it is safe to overwrite the data in it.
This class provides a base-class for converters that need to accept byte inputs.
Adds chunked data to this sink.
This method is also used when converters are used as StreamTransformer
s.
Adds the next chunk
to this
.
Adds the bytes defined by start
and end
-exclusive to this
.
If isLast
is true
closes this
.
Contrary to add
the given chunk
must not be held onto. Once the method returns, it is safe to overwrite the data in it.
Closes the sink.
This signals the end of the chunked conversion. This method is called when converters are used as StreamTransformer
's.
A ChunkedConversionSink
is used to transmit data more efficiently between two converters during chunked conversions.
Adds chunked data to this sink.
This method is also used when converters are used as StreamTransformer
s.
Closes the sink.
This signals the end of the chunked conversion. This method is called when converters are used as StreamTransformer
's.
A ClosableStringSink
extends the StringSink
interface by adding a close
method.
Creates a new instance combining a StringSink
sink
and a callback onClose
which is invoked when the returned instance is closed.
Closes this
and flushes any outstanding data.
A Codec
encodes and (if supported) decodes data.
Codecs can be fused. For example fusing JSON
and UTF8
produces an encoder that can convert Json objects directly to bytes, or can decode bytes directly to json objects.
Fused codecs generally attempt to optimize the operations and can be faster than executing each step of an encoding separately.
Codecs are still experimental and are subject to change without notice.
Returns the decoder of this
, converting from T
to S
.
It may be stateful an should not be reused.
Returns the encoder from S
to T
.
It may be stateful and should not be reused.
Inverts this
.
The encoder
and decoder
of the resulting codec are swapped.
Fuses this
with other
.
When encoding, the resulting codec encodes with this
before encoding with other
.
When decoding, the resulting codec decodes with other
before decoding with this
.
In some cases one needs to use the inverted
codecs to be able to fuse them correctly. That is, the output type of this
(T
) must match the input type of the second codec other
.
Examples:
final JSON_TO_BYTES = JSON.fuse(UTF8); List<int> bytes = JSON_TO_BYTES.encode(["json-object"]); var decoded = JSON_TO_BYTES.decode(bytes); assert(decoded is List && decoded[0] == "json-object"); var inverted = JSON.inverted; var jsonIdentity = JSON.fuse(inverted); var jsonObject = jsonIdentity.encode(["1", 2]); assert(jsonObject is List && jsonObject[0] == "1" && jsonObject[1] == 2);
A Converter
converts data from one representation into another.
Converters are still experimental and are subject to change without notice.
Converts input
and returns the result of the conversion.
Fuses this
with other
.
Encoding with the resulting converter is equivalent to converting with this
before converting with other
.
Starts a chunked conversion.
Open-ended Encoding enum.
Name of the encoding.
If the encoding is standardized, this is the lower-case version of one of the IANA official names for the character set (see http://www.iana.org/assignments/character-sets/character-sets.xml)
Gets an Encoding
object from the name of the character set name. The names used are the IANA official names for the character set (see http://www.iana.org/assignments/character-sets/character-sets.xml).
The name
passed is case insensitive.
If character set is not supported null
is returned.
Converts input
and returns the result of the conversion.
Starts a chunked conversion.
Returns a string representation of this object.
A JsonCodec
encodes JSON objects to strings and decodes strings to JSON objects.
Creates a JsonCodec
with the given reviver.
The reviver
function is called once for each object or list property that has been parsed during decoding. The key
argument is either the integer list index for a list property, the map string for object properties, or null
for the final result.
Parses the string and returns the resulting Json object.
The optional reviver
function is called once for each object or list property that has been parsed during decoding. The key
argument is either the integer list index for a list property, the map string for object properties, or null
for the final result.
The default reviver
(when not provided) is the identity function.
Reports that an object could not be stringified due to cyclic references.
An object that references itself cannot be serialized by stringify
. When the cycle is detected, a JsonCyclicError
is thrown.
The first object that was detected as part of a cycle.
Returns a string representation of this object.
This class parses JSON strings and builds the corresponding objects.
Constructs a new JsonDecoder.
The reviver
may be null
.
Converts the given JSON-string input
to its corresponding object.
Parsed JSON values are of the types num
, String
, bool
, Null
, List
s of parsed JSON values or Map
s from String
to parsed JSON values.
If this
was initialized with a reviver, then the parsing operation invokes the reviver on every object or list property that has been parsed. The arguments are the property name (String
) or list index (int
), and the value is the parsed value. The return value of the reviver is used as the value of that property instead the parsed value.
Throws FormatException
if the input is not valid JSON text.
Starts a conversion from a chunked JSON string to its corresponding object.
The output sink
receives exactly one decoded element through add
.
This class converts JSON objects to strings.
Converts the given object o
to its JSON representation.
Directly serializable values are num
, String
, bool
, and Null
, as well as some List
and Map
values. For List
, the elements must all be serializable. For Map
, the keys must be String
and the values must be serializable.
If a value is any other type is attempted serialized, a "toJson()" method is invoked on the object and the result, which must be a directly serializable value, is serialized instead of the original value.
If the object does not support this method, throws, or returns a value that is not directly serializable, a JsonUnsupportedObjectError
exception is thrown. If the call throws (including the case where there is no nullary "toJson" method, the error is caught and stored in the JsonUnsupportedObjectError
's cause
field.
If a List
or Map
contains a reference to itself, directly or through other lists or maps, it cannot be serialized and a JsonCyclicError
is thrown.
Json Objects should not change during serialization. If an object is serialized more than once, stringify
is allowed to cache the JSON text for it. I.e., if an object changes after it is first serialized, the new values may or may not be reflected in the result.
Starts a chunked conversion.
The converter works more efficiently if the given sink
is a StringConversionSink
.
Returns a chunked-conversion sink that accepts at most one object. It is an error to invoke add
more than once on the returned sink.
Error thrown by JSON serialization if an object cannot be serialized.
The unsupportedObject field holds that object that failed to be serialized.
If an object isn't directly serializable, the serializer calls the 'toJson' method on the object. If that call fails, the error will be stored in the cause field. If the call returns an object that isn't directly serializable, the cause is be null.
The exception thrown by object's toJson
method, if any.
The object that could not be serialized.
Returns a string representation of this object.
A LatinCodec
encodes strings to ISO Latin-1 (aka ISO-8859-1) bytes and decodes Latin-1 bytes to strings.
Instantiates a new Latin1Codec
.
If allowInvalid
is true, the decode
method and the converter returned by decoder
will default to allowing invalid values. Invalid values are decoded into the Unicode Replacement character (U+FFFD). Calls to the decode
method can override this default.
Encoders will not accept invalid (non Latin-1) characters.
Decodes the Latin-1 bytes
(a list of unsigned 8-bit integers) to the corresponding string.
If bytes
contains values that are not in the range 0 .. 255, the decoder will eventually throw a FormatException
.
If allowInvalid
is not provided, it defaults to the value used to create this Latin1Codec
.
This class converts Latin-1 bytes (lists of unsigned 8-bit integers) to a string.
Instantiates a new Latin1Decoder
.
The optional allowInvalid
argument defines how convert
deals with invalid bytes.
If it is true
, convert
replaces invalid bytes with the Unicode Replacement character U+FFFD
(�). Otherwise it throws a FormatException
.
Starts a chunked conversion.
The converter works more efficiently if the given sink
is a StringConversionSink
.
This class converts strings of only ISO Latin-1 characters to bytes.
This class splits String
values into individual lines.
Converts input
and returns the result of the conversion.
Starts a chunked conversion.
This class provides an interface for converters to efficiently transmit String data.
Instead of limiting the interface to one non-chunked String it accepts partial strings or can be transformed into a byte sink that accepts UTF-8 code units.
Creates a new instance wrapping the given sink
.
Every string that is added to the returned instance is forwarded to the sink
. The instance is allowed to buffer and is not required to forward immediately.
Adds the next chunk
to this
.
Adds the substring defined by start
and end
-exclusive to this
.
If isLast
is true
closes this
.
Returns this
as a ClosableStringSink
.
If used, this method must be the first and only call to this
. It invalidates this
. All further operations must be performed on the result.
Returns this
as a sink that accepts UTF-8 input.
If used, this method must be the first and only call to this
. It invalidates this
. All further operations must be performed on the result.
This class provides a base-class for converters that need to accept String inputs.
This class provides a mixin for converters that need to accept String inputs.
Adds chunked data to this sink.
This method is also used when converters are used as StreamTransformer
s.
Adds the next chunk
to this
.
Adds the substring defined by start
and end
-exclusive to this
.
If isLast
is true
closes this
.
Returns this
as a ClosableStringSink
.
If used, this method must be the first and only call to this
. It invalidates this
. All further operations must be performed on the result.
Returns this
as a sink that accepts UTF-8 input.
If used, this method must be the first and only call to this
. It invalidates this
. All further operations must be performed on the result.
Closes the sink.
This signals the end of the chunked conversion. This method is called when converters are used as StreamTransformer
's.
A Utf8Codec
encodes strings to utf-8 code units (bytes) and decodes UTF-8 code units to strings.
Instantiates a new Utf8Codec
.
The optional allowMalformed
argument defines how decoder
(and decode
) deal with invalid or unterminated character sequences.
If it is true
(and not overriden at the method invocation) decode
and the decoder
replace invalid (or unterminated) octet sequences with the Unicode Replacement character U+FFFD
(�). Otherwise they throw a FormatException
.
Decodes the UTF-8 codeUnits
(a list of unsigned 8-bit integers) to the corresponding string.
If allowMalformed
is true
the decoder replaces invalid (or unterminated) character sequences with the Unicode Replacement character U+FFFD
(�). Otherwise it throws a FormatException
.
If allowMalformed
is not given, it defaults to the allowMalformed
that was used to instantiate this
.
This class converts UTF-8 code units (lists of unsigned 8-bit integers) to a string.
Instantiates a new Utf8Decoder
.
The optional allowMalformed
argument defines how convert
deals with invalid or unterminated character sequences.
If it is true
convert
replaces invalid (or unterminated) character sequences with the Unicode Replacement character U+FFFD
(�). Otherwise it throws a FormatException
.
Converts the UTF-8 codeUnits
(a list of unsigned 8-bit integers) to the corresponding string.
Starts a chunked conversion.
The converter works more efficiently if the given sink
is a StringConversionSink
.
This class converts strings to their UTF-8 code units (a list of unsigned 8-bit integers).
Converts string
to its UTF-8 code units (a list of unsigned 8-bit integers).
Starts a chunked conversion.
The converter works more efficiently if the given sink
is a ByteConversionSink
.