This documentation is archived and is not being maintained.

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.

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

<SerializableAttribute> _
Public NotInheritable Class EncoderReplacementFallback _
	Inherits EncoderFallback
Dim instance As EncoderReplacementFallback

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 value of a EncoderReplacementFallback object is the replacement string used to initialize that object.

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.

When 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.

The following code example demonstrates the EncoderReplacementFallback class.

' This example demonstrates the EncoderReplacementFallback class. 
Imports System
Imports System.Text

Class Sample
    Public Shared Sub 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.   

        Dim erf As New EncoderReplacementFallback("(unknown)")
        Dim drf As New DecoderReplacementFallback("(error)")
        Dim ae As Encoding = Encoding.GetEncoding("us-ascii", erf, drf)

        ' The input string consists of the Unicode characters LEFT POINTING  
        ' 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)". 

        Dim inputString As String = "«X»" 
        Dim decodedString As String 
        Dim twoNewLines As String = vbCrLf & vbCrLf
        Dim ix As Integer = 0
        Dim numberOfEncodedBytes As Integer = ae.GetByteCount(inputString)
        ' Counteract the compiler adding an extra byte to the array. 
        Dim encodedBytes(numberOfEncodedBytes - 1) As Byte

        ' --------------------------------------------------------------------------

        ' Display the name of the encoding.
        Console.WriteLine("The name of the encoding is ""{0}""." & vbCrLf, ae.WebName)

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

        ' Display the input string in hexadecimal.  
        ' Each element is converted to an integer with Convert.ToInt32.
        Console.Write("Input string in hexadecimal: ")
        Dim c As Char 
        For Each c In inputString.ToCharArray()
            Console.Write("0x{0:X2} ", Convert.ToInt32(c))
        Next c

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

        ' Display the encoded bytes.  
        ' Each element is converted to an integer with Convert.ToInt32.
        Console.WriteLine("Encoded bytes in hexadecimal ({0} bytes):" & vbCrLf, _
        ix = 0
        Dim b As Byte
        For Each b In encodedBytes
            Console.Write("0x{0:X2} ", Convert.ToInt32(b))
            ix += 1
            If 0 = ix Mod 6 Then
            End If 
        Next b

        ' -------------------------------------------------------------------------- 
        ' 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)

    End Sub 'Main
End Class 'Sample

'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 

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


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

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

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

.NET Framework

Supported in: 3.5, 3.0, 2.0