Export (0) Print
Expand All

Encoding.BigEndianUnicode Property

Updated: October 2010

Gets an encoding for the UTF-16 format using the big endian byte order.

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

'Declaration
Public Shared ReadOnly Property BigEndianUnicode As Encoding
'Usage
Dim value As Encoding 

value = Encoding.BigEndianUnicode

Property Value

Type: System.Text.Encoding
An encoding object for the UTF-16 format using the big endian byte order.

The UnicodeEncoding object that is returned by this property may not have the appropriate behavior for your application. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the UnicodeEncoding.UnicodeEncoding(Boolean, Boolean, Boolean) constructor to instantiate a big endian UnicodeEncoding object whose fallback is either an EncoderFallbackException or a DecoderFallbackException, as the following example illustrates.

Imports System.Text

Module Example
   Public Sub Main()
      Dim bytes() As Byte = { &h00, &h20, &hd8, &h01, &h00, &h68, &hA7, &h00}
      Dim enc As Encoding = New UnicodeEncoding(True, True, True)

      Try 
         Dim value As String = enc.GetString(bytes)
         Console.WriteLine()
         Console.WriteLine("'{0}'", value)
      Catch e As DecoderFallbackException      
         Console.WriteLine("Unable to decode {0} at index {1}", _ 
                           ShowBytes(e.BytesUnknown), e.Index)
      End Try 
   End Sub 

   Private Function ShowBytes(bytes As Byte()) As String 
      Dim returnString As String = Nothing 
      For Each byteValue In bytes
         returnString += String.Format("0x{0:X2} ", byteValue)
      Next 
      Return returnString.Trim()
   End Function 
End Module 
' The example displays the following output: 
'       Unable to decode 0xD8 0x01 at index 4

The returned UnicodeEncoding object has BodyName, HeaderName, and WebName properties that yield the name "unicodeFFFE". Although the UTF-16 big endian byte order mark is hexadecimal FEFF, the name "unicodeFFFE" was chosen because the byte order mark appears as hexadecimal FFFE on little endian Windows computers.

The following example reads a text file with a UTF-16 encoding using the big endian byte order.

Imports System
Imports System.IO

Namespace BigEndianExample
   Public Class Class1
      Public Overloads Shared Sub Main()
         ' Read a text file saved with Big Endian Unicode encoding. 
         Dim encoding As System.Text.Encoding = System.Text.Encoding.BigEndianUnicode
         Dim reader As New StreamReader("TextFile.txt", encoding)
         Dim line As String = reader.ReadLine()
         While Not (line Is Nothing)
            Console.WriteLine(line)
            line = reader.ReadLine()
         End While 
      End Sub 
   End Class 
End Namespace

The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes.

Imports System
Imports System.Text
Imports Microsoft.VisualBasic

Public Class SamplesEncoding   

   Public Shared Sub Main()

      ' The characters to encode: 
      '    Latin Small Letter Z (U+007A) 
      '    Latin Small Letter A (U+0061) 
      '    Combining Breve (U+0306) 
      '    Latin Small Letter AE With Acute (U+01FD) 
      '    Greek Small Letter Beta (U+03B2) 
      '    a high-surrogate value (U+D8FF) 
      '    a low-surrogate value (U+DCFF) 
      Dim myChars() As Char = {"z"c, "a"c, ChrW(&H0306), ChrW(&H01FD), ChrW(&H03B2), ChrW(&HD8FF), ChrW(&HDCFF)}


      ' Get different encodings. 
      Dim u7 As Encoding = Encoding.UTF7
      Dim u8 As Encoding = Encoding.UTF8
      Dim u16LE As Encoding = Encoding.Unicode
      Dim u16BE As Encoding = Encoding.BigEndianUnicode
      Dim u32 As Encoding = Encoding.UTF32

      ' Encode the entire array, and print out the counts and the resulting bytes.
      PrintCountsAndBytes(myChars, u7)
      PrintCountsAndBytes(myChars, u8)
      PrintCountsAndBytes(myChars, u16LE)
      PrintCountsAndBytes(myChars, u16BE)
      PrintCountsAndBytes(myChars, u32)

   End Sub 'Main


   Public Shared Sub PrintCountsAndBytes(chars() As Char, enc As Encoding)

      ' Display the name of the encoding used.
      Console.Write("{0,-30} :", enc.ToString())

      ' Display the exact byte count. 
      Dim iBC As Integer = enc.GetByteCount(chars)
      Console.Write(" {0,-3}", iBC)

      ' Display the maximum byte count. 
      Dim iMBC As Integer = enc.GetMaxByteCount(chars.Length)
      Console.Write(" {0,-3} :", iMBC)

      ' Encode the array of chars. 
      Dim bytes As Byte() = enc.GetBytes(chars)

      ' Display all the encoded bytes.
      PrintHexBytes(bytes)

   End Sub 'PrintCountsAndBytes


   Public Shared Sub PrintHexBytes(bytes() As Byte)

      If bytes Is Nothing OrElse bytes.Length = 0 Then
         Console.WriteLine("<none>")
      Else 
         Dim i As Integer 
         For i = 0 To bytes.Length - 1
            Console.Write("{0:X2} ", bytes(i))
         Next i
         Console.WriteLine()
      End If 

   End Sub 'PrintHexBytes 

End Class 'SamplesEncoding


'This code produces the following output. 

'System.Text.UTF7Encoding       : 18  23  :7A 61 2B 41 77 59 42 2F 51 4F 79 32 50 2F 63 2F 77 2D 
'System.Text.UTF8Encoding       : 12  24  :7A 61 CC 86 C7 BD CE B2 F1 8F B3 BF 
'System.Text.UnicodeEncoding    : 14  16  :7A 00 61 00 06 03 FD 01 B2 03 FF D8 FF DC 
'System.Text.UnicodeEncoding    : 14  16  :00 7A 00 61 03 06 01 FD 03 B2 D8 FF DC FF 
'System.Text.UTF32Encoding      : 24  32  :7A 00 00 00 61 00 00 00 06 03 00 00 FD 01 00 00 B2 03 00 00 FF FC 04 00

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, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

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, 1.1, 1.0

.NET Compact Framework

Supported in: 3.5, 2.0, 1.0

XNA Framework

Supported in: 3.0, 2.0, 1.0

Date

History

Reason

October 2010

Noted replacement fallback behavior.

Customer feedback.

Community Additions

ADD
Show:
© 2015 Microsoft