mscorlib 2.0.0.0 4.0.0.0 System.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 class.

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

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

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

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

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

- Constructor
  2.0.0.0
  4.0.0.0
  To be added.

  Initializes a new instance of the class.

- Method
  2.0.0.0
  4.0.0.0
  System.Boolean `` ``

  The and methods call if they encounter an unknown input character that cannot be encoded. A return value of true indicates that the fallback buffer can process the input character, which causes the calling method to call the method to obtain each character of the fallback buffer. Because it does not process individual characters, the method in an exception fallback handler throws an exception.

  When overridden in a derived class, prepares the fallback buffer to handle the specified input character.

  true if the fallback buffer can process ; false if the fallback buffer ignores .

  An input character. The index position of the character in the input buffer.
- Method
  2.0.0.0
  4.0.0.0
  System.Boolean `` `` ``

  The and methods call if they encounter a surrogate pair in their input. A return value of true indicates that the fallback buffer can process the surrogate pair, which causes the calling method to call the method to obtain each character of the fallback buffer. Because it does not process individual characters, the method in an exception fallback handler throws an exception.

  When overridden in a derived class, prepares the fallback buffer to handle the specified surrogate pair.

  true if the fallback buffer can process and ; false if the fallback buffer ignores the surrogate pair.

  The high surrogate of the input pair. The low surrogate of the input pair. The index position of the surrogate pair in the input buffer.
- Method
  2.0.0.0
  4.0.0.0
  System.Char

  An encoding operation calls the method if the operation encounters an unknown character or surrogate pair in the input. For example, in the case of a replacement fallback, if the method returns true, a substitute string exists that can be encoded instead of the unknown input. The encoding operation calls the method repeatedly and obtains the substitute string one character at a time. When all characters in the fallback buffer have been returned to the encoder, the method should return U+0000.

  For an exception fallback handler, the method should return U+0000.

  When overridden in a derived class, retrieves the next character in the fallback buffer.

  The next character in the fallback buffer.

- Method
  2.0.0.0
  4.0.0.0
  System.Boolean

  An exception fallback handler should return false.

  When overridden in a derived class, causes the next call to the method to access the data buffer character position that is prior to the current character position.

  true if the operation was successful; otherwise, false.

- Property
  2.0.0.0
  4.0.0.0
  System.Int32 To be added.

  The method returns true if is a nonzero value.

  For an exception fallback handler, the method should return zero.

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

- Method
  2.0.0.0
  4.0.0.0
  System.Void To be added.

  Initializes all data and state information pertaining to this fallback buffer.