This documentation is archived and is not being maintained.

EncoderFallbackBuffer Class

Provides a buffer that allows a fallback handler to return an alternate string to an encoder when it cannot encode an input character.

Namespace:  System.Text
Assembly:  mscorlib (in mscorlib.dll)

public abstract class EncoderFallbackBuffer

The EncoderFallbackBuffer type exposes the following members.

Protected methodEncoderFallbackBufferInitializes a new instance of the EncoderFallbackBuffer class.

Public propertyRemainingWhen overridden in a derived class, gets the number of characters in the current EncoderFallbackBuffer object that remain to be processed.

Public methodEquals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Public methodFallback(Char, Int32)When overridden in a derived class, prepares the fallback buffer to handle the specified input character.
Public methodFallback(Char, Char, Int32)When overridden in a derived class, prepares the fallback buffer to handle the specified surrogate pair.
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodGetNextCharWhen overridden in a derived class, retrieves the next character in the fallback buffer.
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodMovePreviousWhen overridden in a derived class, causes the next call to the GetNextChar method to access the data buffer character position that is prior to the current character position.
Public methodResetInitializes all data and state information pertaining to this fallback buffer.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)

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 EncoderFallback class.

  • An encoder fallback buffer, which is represented by a type derived from the 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 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 EncoderReplacementFallback and EncoderReplacementFallbackBuffer classes provide a public replacement fallback buffer implementation. The constructor of the EncoderReplacementFallback class enables you to define the replacement string.

  • Exception. The 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 EncoderFallbackBuffer implementation, although it does not return a string to the encoder. In the .NET Framework, the EncoderExceptionFallback and EncoderExceptionFallbackBuffer classes provide a public exception fallback implementation that throws an EncoderFallbackException when a character cannot be encoded.

The buffer in an 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 EncoderFallbackBuffer is an abstract class, it requires derived classes to implement the following members at a minimum:

  • The overloaded Fallback 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 GetNextChar method, which is called repeatedly by the encoder if the Fallback 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 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 Remaining property, which indicates the number of remaining characters to be returned to the encoder. An exception fallback handler always returns zero.

.NET Framework

Supported in: 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.