UnicodeEncoding Constructor (Boolean, Boolean, Boolean)

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Initializes a new instance of the UnicodeEncoding class. Parameters specify whether to use the big-endian byte order, whether to provide a Unicode byte order mark, and whether to throw an exception when an invalid encoding is detected.

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

Syntax

'Declaration
Public Sub New ( _
    bigEndian As Boolean, _
    byteOrderMark As Boolean, _
    throwOnInvalidBytes As Boolean _
)
public UnicodeEncoding(
    bool bigEndian,
    bool byteOrderMark,
    bool throwOnInvalidBytes
)

Parameters

  • bigEndian
    Type: System.Boolean
    true to use the big-endian byte order (most significant byte first); false to use the little-endian byte order (least significant byte first).
  • byteOrderMark
    Type: System.Boolean
    true to specify that a Unicode byte order mark is provided; otherwise, false.
  • throwOnInvalidBytes
    Type: System.Boolean
    true to specify that an exception should be thrown when an invalid encoding is detected; otherwise, false.

Remarks

It is generally more efficient to encode Unicode characters using the native byte order. For example, it is better to use the little-endian byte order on little-endian platforms, such as Intel computers, and the big-endian byte order on big-endian platforms.

If the throwOnInvalidBytes parameter is true, a method that detects an invalid byte sequence throws System.ArgumentException. Otherwise, the method does not throw an exception, and the invalid sequence is ignored.

NoteNote:

For security reasons, your applications are recommended to use this constructor to create an instance of the UnicodeEncoding class and turn on error detection by setting throwOnInvalidBytes to true.

Examples

The following code example demonstrates the behavior of UnicodeEncoding, both with error detection enabled and without.

Imports System.Text

Public Class Example

   Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)

      ' Create an instance of UnicodeEncoding using little-endian byte order.
      ' This will be used for encoding.
      Dim u16LE As New UnicodeEncoding(False, True)

      ' Create two instances of UnicodeEncoding using big-endian byte order: one with error detection and one without.
      ' These will be used for decoding.
      Dim u16withED As New UnicodeEncoding(True, True, True)
      Dim u16noED As New UnicodeEncoding(True, True, False)

      ' Create byte arrays from the same string containing the following characters:
      '    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)
      '    Latin Capital Letter U with  Diaeresis (U+00DC)
      Dim myStr As String = "za" & ChrW(&H306) & ChrW(&H1FD) & ChrW(&H3B2) & ChrW(&HDC)

      ' Encode the string using little-endian byte order.
      Dim myBytes(u16LE.GetByteCount(myStr)) As Byte
      u16LE.GetBytes(myStr, 0, myStr.Length, myBytes, 0)

      ' Decode the byte array with error detection.
      outputBlock.Text &= "Decoding with error detection:" & vbCrLf
      PrintDecodedString(outputBlock, myBytes, u16withED)

      ' Decode the byte array without error detection.
      outputBlock.Text &= "Decoding without error detection:" & vbCrLf
      PrintDecodedString(outputBlock, myBytes, u16noED)

   End Sub 'Main


   ' Decode the bytes and display the string.
   Public Shared Sub PrintDecodedString(ByVal outputBlock As System.Windows.Controls.TextBlock, ByVal bytes() As Byte, ByVal enc As Encoding)

      Try
         outputBlock.Text += String.Format("   Decoded string: {0}", enc.GetString(bytes, 0, bytes.Length)) & vbCrLf
      Catch e As System.ArgumentException
         outputBlock.Text &= e.ToString() & vbCrLf
      End Try

      outputBlock.Text &= vbCrLf

   End Sub 'PrintDecodedString 

End Class 'SamplesUnicodeEncoding

using System;
using System.Text;

public class Example
{

   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {

      // Create an instance of UnicodeEncoding using little-endian byte order.
      // This will be used for encoding.
      UnicodeEncoding u16LE = new UnicodeEncoding(false, true);

      // Create two instances of UnicodeEncoding using big-endian byte order: one with error detection and one without.
      // These will be used for decoding.
      UnicodeEncoding u16withED = new UnicodeEncoding(true, true, true);
      UnicodeEncoding u16noED = new UnicodeEncoding(true, true, false);

      // Create byte arrays from the same string containing the following characters:
      //    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)
      //    Latin Capital Letter U with  Diaeresis (U+00DC)
      String myStr = "za\u0306\u01FD\u03B2\u00DC";

      // Encode the string using little-endian byte order.
      byte[] myBytes = new byte[u16LE.GetByteCount(myStr)];
      u16LE.GetBytes(myStr, 0, myStr.Length, myBytes, 0);

      // Decode the byte array with error detection.
      outputBlock.Text += "Decoding with error detection:" + "\n";
      PrintDecodedString(outputBlock, myBytes, u16withED);

      // Decode the byte array without error detection.
      outputBlock.Text += "Decoding without error detection:" + "\n";
      PrintDecodedString(outputBlock, myBytes, u16noED);

   }


   // Decode the bytes and display the string.
   public static void PrintDecodedString(System.Windows.Controls.TextBlock outputBlock, byte[] bytes, Encoding enc)
   {

      try
      {
         outputBlock.Text += String.Format("   Decoded string: {0}", enc.GetString(bytes, 0, bytes.Length)) + "\n";
      }
      catch (System.ArgumentException e)
      {
         outputBlock.Text += e.ToString() + "\n";
      }

      outputBlock.Text += "\n";

   }

}

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.