DecoderReplacementFallback Class

 

Provides a failure-handling mechanism, called a fallback, for an encoded input byte sequence that cannot be converted to an output character. The fallback emits a user-specified replacement string instead of a decoded input byte sequence. This class cannot be inherited.

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

System.Object
  System.Text.DecoderFallback
    System.Text.DecoderReplacementFallback

[SerializableAttribute]
public sealed class DecoderReplacementFallback : DecoderFallback

NameDescription
System_CAPS_pubmethodDecoderReplacementFallback()

Initializes a new instance of the DecoderReplacementFallback class.

System_CAPS_pubmethodDecoderReplacementFallback(String)

Initializes a new instance of the DecoderReplacementFallback class using a specified replacement string.

NameDescription
System_CAPS_pubpropertyDefaultString

Gets the replacement string that is the value of the DecoderReplacementFallback object.

System_CAPS_pubpropertyMaxCharCount

Gets the number of characters in the replacement string for the DecoderReplacementFallback object.(Overrides DecoderFallback.MaxCharCount.)

NameDescription
System_CAPS_pubmethodCreateFallbackBuffer()

Creates a DecoderFallbackBuffer object that is initialized with the replacement string of this DecoderReplacementFallback object.(Overrides DecoderFallback.CreateFallbackBuffer().)

System_CAPS_pubmethodEquals(Object)

Indicates whether the value of a specified object is equal to the DecoderReplacementFallback object.(Overrides Object.Equals(Object).)

System_CAPS_pubmethodGetHashCode()

Retrieves the hash code for the value of the DecoderReplacementFallback object.(Overrides Object.GetHashCode().)

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_pubmethodToString()

Returns a string that represents the current object.(Inherited from Object.)

A common reason for an encoding or decoding operation to fail is if the underlying encoding class does not provide a mapping between a character and an equivalent byte sequence. For example, an ASCIIEncoding object cannot decode a byte value greater than 0x7F. If an input byte sequence cannot be converted to an output character, a DecoderReplacementFallback object emits a replacement string into the output to represent the original input byte sequence. The conversion process then continues to decode the remainder of the original input.

The replacement string used by a DecoderReplacementFallback object is determined by the call to its class constructor. Two options are available:

This class is one of two .NET Framework classes that implement different fallback strategies for handling decoding conversion failures. The other class is the DecoderExceptionFallback class, which throws a DecoderFallbackException when an invalid byte sequence is encountered.

The following code example demonstrates the DecoderReplacementFallback class.

// This example demonstrates the DecoderReplacementFallback class.

using System;
using System.Text;

class Sample 
{
    public static void Main() 
    {

// Create an encoding, which is equivalent to calling the 
// ASCIIEncoding class constructor. 
// The DecoderReplacementFallback parameter specifies that the 
// string "(error)" is to replace characters that cannot be decoded. 
// An encoder replacement fallback is also specified, but in this code
// example the encoding operation cannot fail.  

    Encoding ae = Encoding.GetEncoding(
                  "us-ascii",
                  new EncoderReplacementFallback("(unknown)"), 
                  new DecoderReplacementFallback("(error)"));
    string inputString = "XYZ";
    string decodedString;
    string twoNewLines = "\n\n";
    byte[] encodedBytes = new byte[ae.GetByteCount(inputString)];
    int numberOfEncodedBytes = 0;

// --------------------------------------------------------------------------
    Console.Clear();

// Display the name of the encoding.
    Console.WriteLine("The name of the encoding is \"{0}\".\n", ae.WebName);

// Display the input string in text.
    Console.WriteLine("Input string ({0} characters): \"{1}\"", 
                       inputString.Length, inputString);

// Display the input string in hexadecimal.
    Console.Write("Input string in hexadecimal: ");
    foreach (char c in inputString.ToCharArray()) 
        {
        Console.Write("0x{0:X2} ", (int)c);
        }
    Console.Write(twoNewLines);

// --------------------------------------------------------------------------
// Encode the input string. 

    Console.WriteLine("Encode the input string...");
    numberOfEncodedBytes = ae.GetBytes(inputString, 0, inputString.Length, 
                                       encodedBytes, 0);

// Display the encoded bytes.
    Console.WriteLine("Encoded bytes in hexadecimal ({0} bytes):\n", 
                       numberOfEncodedBytes);
    foreach (byte b in encodedBytes)
        {
        Console.Write("0x{0:X2} ", (int)b);
        }
    Console.Write(twoNewLines);

// --------------------------------------------------------------------------

// Replace the encoded byte sequences for the characters 'X' and 'Z' with the 
// value 0xFF, which is outside the valid range of 0x00 to 0x7F for 
// ASCIIEncoding. The resulting byte sequence is actually the beginning of 
// this code example because it is the input to the decoder operation, and 
// is equivalent to a corrupted or improperly encoded byte sequence. 

    encodedBytes[0] = 0xFF;
    encodedBytes[2] = 0xFF;

    Console.WriteLine("Display the corrupted byte sequence...");
    Console.WriteLine("Encoded bytes in hexadecimal ({0} bytes):\n", 
                       numberOfEncodedBytes);
    foreach (byte b in encodedBytes)
        {
        Console.Write("0x{0:X2} ", (int)b);
        }
    Console.Write(twoNewLines);

// --------------------------------------------------------------------------
// Decode the encoded bytes.

    Console.WriteLine("Compare the decoded bytes to the input string...");
    decodedString = ae.GetString(encodedBytes);

// Display the input string and the decoded string for comparison.
    Console.WriteLine("Input string:  \"{0}\"", inputString);
    Console.WriteLine("Decoded string:\"{0}\"", decodedString);
    }
}
/*
This code example produces the following results:

The name of the encoding is "us-ascii".

Input string (3 characters): "XYZ"
Input string in hexadecimal: 0x58 0x59 0x5A

Encode the input string...
Encoded bytes in hexadecimal (3 bytes):

0x58 0x59 0x5A

Display the corrupted byte sequence...
Encoded bytes in hexadecimal (3 bytes):

0xFF 0x59 0xFF

Compare the decoded bytes to the input string...
Input string:  "XYZ"
Decoded string:"(error)Y(error)"

*/

Universal Windows Platform
Available since 10
.NET Framework
Available since 2.0

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

Return to top
Show: