An encoding defines a mapping between a Unicode character and an encoded sequence of bytes. An encoding operation, which converts an input character to an output byte sequence, fails if no mapping is defined for a particular character.

The .NET Framework provides a failure handling mechanism, called a fallback, if a conversion cannot be performed. All encoder fallback handlers must implement the following:

• An encoder fallback, which is represented by a class derived from the System.Text.EncoderFallback class.

• An encoder fallback buffer, which is represented by a type derived from the System.Text.EncoderFallbackBuffer class that can return a string to the conversion operation.

Fallbacks can use three strategies to handle conversion failures:

• Best-fit mapping. The encoder fallback buffer can return a string that represents a close approximation to the input character. The .NET Framework does not provide a public best-fit System.Text.EncoderFallbackBuffer implementation.

• Replacement. The encoder fallback buffer can return a string, such as a question mark ("?"), that indicates that a character could not be encoded. In the .NET Framework, the System.Text.EncoderReplacementFallback and System.Text.EncoderReplacementFallbackBuffer classes provide a public replacement fallback buffer implementation. The constructor of the System.Text.EncoderReplacementFallback class enables you to define the replacement string.

• Exception. The System.Text.EncoderFallbackBuffer implementation throws an exception, which indicates that a character cannot be encoded, and terminates the encoding operation. In this case, the fallback handler must provide an System.Text.EncoderFallbackBuffer implementation, although it does not return a string to the encoder. In the .NET Framework, the System.Text.EncoderExceptionFallback and System.Text.EncoderExceptionFallbackBuffer classes provide a public exception fallback implementation that throws an System.Text.EncoderFallbackException when a character cannot be encoded.

The buffer in an System.Text.EncoderFallbackBuffer implementation represents the entire string to be returned to the encoder in response to an encoder fallback. Generally, implementations also include state information, such as the index of the next character to return to the encoder and the number of remaining characters to be returned. Because System.Text.EncoderFallbackBuffer is an abstract class, it requires derived classes to implement the following members at a minimum:

• The overloaded EncoderFallbackBuffer.Fallback(char, int) method, which is called by the encoder when it cannot encode a character. The encoder passes two pieces of information to the fallback buffer implementation: the character or surrogate pair that could not be encoded and the index of the character in the input. In an encoder fallback exception handler, the exception is thrown in this method. Otherwise, the method returns true if it provides a fallback, or false if it does not.

• The EncoderFallbackBuffer.GetNextChar method, which is called repeatedly by the encoder if the EncoderFallbackBuffer.Fallback(char, int) method returns true. In successive calls, the handler should return each character in its buffer. When it has returned all characters, it should return U+0000. An exception handler always returns U+0000.

• The EncoderFallbackBuffer.MovePrevious method, which tries to move the pointer to the previous position in the buffer and indicates whether the move was successful. An exception handler always returns false.

• The EncoderFallbackBuffer.Remaining property, which indicates the number of remaining characters to be returned to the encoder. An exception fallback handler always returns zero.

Namespace: System.Text
Assembly: mscorlib (in mscorlib.dll)
Assembly Versions: 2.0.0.0, 4.0.0.0
Since: .NET 2.0