Windows apps
Collapse the table of content
Expand the table of content
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

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 NotInheritable Class DecoderReplacementFallback
	Inherits 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.
Imports System
Imports System.Text

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

        Dim erf As New EncoderReplacementFallback("(unknown)")
        Dim drf As New DecoderReplacementFallback("(error)")
        Dim ae As Encoding = Encoding.GetEncoding("us-ascii", erf, drf)
        Dim inputString As String = "XYZ"
        Dim decodedString As String
        Dim twoNewLines As String = vbCrLf & vbCrLf
        Dim numberOfEncodedBytes As Integer = ae.GetByteCount(inputString)
        ' Counteract the compiler implicitly adding an extra element.
        Dim encodedBytes(numberOfEncodedBytes - 1) As Byte

        ' --------------------------------------------------------------------------
        Console.Clear()

        ' 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
        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. 
        ' Each element is converted to an integer with Convert.ToInt32.
        Console.WriteLine("Encoded bytes in hexadecimal ({0} bytes):" & vbCrLf, _
                                                         numberOfEncodedBytes)
        Dim b As Byte
        For Each b In  encodedBytes
            Console.Write("0x{0:X2} ", Convert.ToInt32(b))
        Next 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) = &HFF
        encodedBytes(2) = &HFF

        Console.WriteLine("Display the corrupted byte sequence...")
        Console.WriteLine("Encoded bytes in hexadecimal ({0} bytes):" & vbCrLf, _
                           numberOfEncodedBytes)
        For Each b In  encodedBytes
            Console.Write("0x{0:X2} ", Convert.ToInt32(b))
        Next 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)

    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): "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:
© 2017 Microsoft