A converter that can convert a byte sequence from a charset into a 16-bit Unicode character sequence.

The input byte sequence is wrapped by a Java.Nio.ByteBuffer and the output character sequence is a Java.Nio.CharBuffer. A decoder instance should be used in the following sequence, which is referred to as a decoding operation:

1. invoking the CharsetDecoder.Reset method to reset the decoder if the decoder has been used;
2. invoking the CharsetDecoder.Decode(Java.Nio.ByteBuffer, Java.Nio.CharBuffer, Java.Nio.CharBuffer) method until the additional input is not needed, the endOfInput parameter must be set to false, the input buffer must be filled and the output buffer must be flushed between invocations;
3. invoking the CharsetDecoder.Decode(Java.Nio.ByteBuffer, Java.Nio.CharBuffer, Java.Nio.CharBuffer) method for the last time, and then the endOfInput parameter must be set to true;
4. invoking the CharsetDecoder.Flush(Java.Nio.CharBuffer) method to flush the output.

The CharsetDecoder.Decode(Java.Nio.ByteBuffer, Java.Nio.CharBuffer, Java.Nio.CharBuffer) method will convert as many bytes as possible, and the process won't stop until the input bytes have run out, the output buffer has been filled or some error has happened. A Java.Nio.Charset.CoderResult instance will be returned to indicate the stop reason, and the invoker can identify the result and choose further action, which includes filling the input buffer, flushing the output buffer or recovering from an error and trying again.

There are two common decoding errors. One is named malformed and it is returned when the input byte sequence is illegal for the current specific charset, the other is named unmappable character and it is returned when a problem occurs mapping a legal input byte sequence to its Unicode character equivalent.

Both errors can be handled in three ways, the default one is to report the error to the invoker by a Java.Nio.Charset.CoderResult instance, and the alternatives are to ignore it or to replace the erroneous input with the replacement string. The replacement string is "�" by default and can be changed by invoking CharsetDecoder.ReplaceWith(string) method. The invoker of this decoder can choose one way by specifying a Java.Nio.Charset.CodingErrorAction instance for each error type via CharsetDecoder.OnMalformedInput(CodingErrorAction) method and CharsetDecoder.OnUnmappableCharacter(CodingErrorAction) method.

This is an abstract class and encapsulates many common operations of the decoding process for all charsets. Decoders for a specific charset should extend this class and need only to implement the CharsetDecoder.DecodeLoop(Java.Nio.ByteBuffer, Java.Nio.CharBuffer) method for the basic decoding. If a subclass maintains an internal state, it should override the CharsetDecoder.ImplFlush(Java.Nio.CharBuffer) method and the CharsetDecoder.ImplReset method in addition.

This class is not thread-safe.

See Also

• Java.Nio.Charset.Charset
• Java.Nio.Charset.CharsetEncoder

[Android Documentation]