Export (0) Print
Expand All

EncoderReplacementFallback Class

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

System.Object
  System.Text.EncoderFallback
    System.Text.EncoderReplacementFallback

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

[SerializableAttribute]
public sealed class EncoderReplacementFallback : EncoderFallback

The EncoderReplacementFallback type exposes the following members.

  NameDescription
Public methodEncoderReplacementFallback()Initializes a new instance of the EncoderReplacementFallback class.
Public methodEncoderReplacementFallback(String)Initializes a new instance of the EncoderReplacementFallback class using a specified replacement string.
Top

  NameDescription
Public propertyDefaultStringGets the replacement string that is the value of the EncoderReplacementFallback object.
Public propertyMaxCharCountGets the number of characters in the replacement string for the EncoderReplacementFallback object. (Overrides EncoderFallback.MaxCharCount.)
Top

  NameDescription
Public methodCreateFallbackBufferCreates a EncoderFallbackBuffer object that is initialized with the replacement string of this EncoderReplacementFallback object. (Overrides EncoderFallback.CreateFallbackBuffer().)
Public methodEqualsIndicates whether the value of a specified object is equal to the EncoderReplacementFallback object. (Overrides Object.Equals(Object).)
Public methodGetHashCodeRetrieves the hash code for the value of the EncoderReplacementFallback object. (Overrides Object.GetHashCode().)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top

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 encode a character having a Unicode code point value that is outside the range U+0000 to U+007F. If the input character cannot be converted to an output byte sequence, a EncoderReplacementFallback object substitutes a specified replacement string for the original input character. The conversion process encodes the replacement string and then continues to process the remainder of the original input.

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

If you choose a fallback string to use with this class, make sure that the string is composed entirely of characters that can be encoded in the target encoding. Otherwise, a recursive fallback results, causing an ArgumentException.

This class is one of two .NET Framework classes that implement different fallback strategies for handling encoding conversion failures. The other class is the EncoderExceptionFallback class, which throws an EncoderFallbackException when an invalid character is encountered.

The following example demonstrates the EncoderReplacementFallback class.

// This example demonstrates the EncoderReplacementFallback 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 EncoderReplacementFallback parameter specifies that the 
// string, "(unknown)", replace characters that cannot be encoded. 
// A decoder replacement fallback is also specified, but in this  
// code example the decoding operation cannot fail.  

    Encoding ae = Encoding.GetEncoding(
                  "us-ascii",
                  new EncoderReplacementFallback("(unknown)"), 
                  new DecoderReplacementFallback("(error)"));

// The input string consists of the Unicode characters LEFT POINTING  
// DOUBLE ANGLE QUOTATION MARK (U+00AB), 'X' (U+0058), and RIGHT POINTING  
// DOUBLE ANGLE QUOTATION MARK (U+00BB).  
// The encoding can only encode characters in the US-ASCII range of U+0000  
// through U+007F. Consequently, the characters bracketing the 'X' character 
// are replaced with the fallback replacement string, "(unknown)".

    string inputString = "\u00abX\u00bb";
    string decodedString;
    string twoNewLines = "\n\n";
    byte[] encodedBytes = new byte[ae.GetByteCount(inputString)];
    int numberOfEncodedBytes = 0;
    int ix = 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);
    ix = 0;
    foreach (byte b in encodedBytes)
        {
        Console.Write("0x{0:X2} ", (int)b);
        ix++;
        if (0 == ix % 6) Console.WriteLine();
        }
    Console.Write(twoNewLines);

// -------------------------------------------------------------------------- 
// Decode the encoded bytes, yielding a reconstituted string.

    Console.WriteLine("Decode the encoded bytes...");
    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): "�X�"
Input string in hexadecimal: 0xAB 0x58 0xBB

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

0x28 0x75 0x6E 0x6B 0x6E 0x6F
0x77 0x6E 0x29 0x58 0x28 0x75
0x6E 0x6B 0x6E 0x6F 0x77 0x6E
0x29

Decode the encoded bytes...
Input string:  "�X�"
Decoded string:"(unknown)X(unknown)"

*/

.NET Framework

Supported in: 4.5.3, 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

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.
Show:
© 2014 Microsoft