UTF32Encoding Constructors

Definition

Namespace:

System.Text

Assembly:

System.Text.Encoding.Extensions.dll

Initializes a new instance of the UTF32Encoding class.

Overloads

UTF32Encoding()	Initializes a new instance of the UTF32Encoding class.
UTF32Encoding(Boolean, Boolean)	Initializes a new instance of the UTF32Encoding class. Parameters specify whether to use the big endian byte order and whether the GetPreamble() method returns a Unicode byte order mark.
UTF32Encoding(Boolean, Boolean, Boolean)	Initializes a new instance of the UTF32Encoding 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.

UTF32Encoding()

Source:

UTF32Encoding.cs

Initializes a new instance of the UTF32Encoding class.

public:
 UTF32Encoding();

public UTF32Encoding ();

Public Sub New ()

Examples

The following example retrieves and displays the byte order mark for different UTF32Encoding instances.

using namespace System;
using namespace System::Text;

void PrintHexBytes( array<Byte>^bytes );

int main()
{
   
   // Create instances of UTF32Encoding, with the byte order mark and without.
   UTF32Encoding ^ u32LeNone = gcnew UTF32Encoding;
   UTF32Encoding ^ u32BeNone = gcnew UTF32Encoding( true,false );
   UTF32Encoding ^ u32LeBom = gcnew UTF32Encoding( false,true );
   UTF32Encoding ^ u32BeBom = gcnew UTF32Encoding( true,true );
   
   // Display the preamble for each instance.
   PrintHexBytes( u32LeNone->GetPreamble() );
   PrintHexBytes( u32BeNone->GetPreamble() );
   PrintHexBytes( u32LeBom->GetPreamble() );
   PrintHexBytes( u32BeBom->GetPreamble() );
}

void PrintHexBytes( array<Byte>^bytes )
{
   if ( (bytes == nullptr) || (bytes->Length == 0) )
      Console::WriteLine( "<none>" );
   else
   {
      for ( int i = 0; i < bytes->Length; i++ )
         Console::Write( "{0:X2} ", bytes[ i ] );
      Console::WriteLine();
   }
}

/* 
This example displays the following output:
      FF FE 00 00
      <none>
      FF FE 00 00
      00 00 FE FF
*/

using System;
using System.Text;

public class SamplesUTF32Encoding
{
   public static void Main()
   {
      // Create instances of UTF32Encoding, with the byte order mark and without.
      UTF32Encoding u32LeNone = new UTF32Encoding();
      UTF32Encoding u32BeNone = new UTF32Encoding( true, false );
      UTF32Encoding u32LeBom  = new UTF32Encoding( false, true );
      UTF32Encoding u32BeBom  = new UTF32Encoding( true, true );

      // Display the preamble for each instance.
      PrintHexBytes( u32LeNone.GetPreamble() );
      PrintHexBytes( u32BeNone.GetPreamble() );
      PrintHexBytes( u32LeBom.GetPreamble() );
      PrintHexBytes( u32BeBom.GetPreamble() );
   }

   public static void PrintHexBytes( byte[] bytes )
   {

      if (( bytes == null ) || ( bytes.Length == 0 ))
        {
            Console.WriteLine( "<none>" );
        }
        else  {
         for ( int i = 0; i < bytes.Length; i++ )
            Console.Write( "{0:X2} ", bytes[i] );
         Console.WriteLine();
      }
   }
}
/*
This example displays the following output.
      FF FE 00 00
      <none>
      FF FE 00 00
      00 00 FE FF
*/

Imports System.Text

Public Class SamplesUTF32Encoding   
   Public Shared Sub Main()
      ' Create instances of UTF32Encoding, with the byte order mark and without.
      Dim u32LeNone As New UTF32Encoding()
      Dim u32BeNone As New UTF32Encoding(True, False)
      Dim u32LeBom As New UTF32Encoding(False, True)
      Dim u32BeBom As New UTF32Encoding(True, True)

      ' Display the preamble for each instance.
      PrintHexBytes(u32LeNone.GetPreamble())
      PrintHexBytes(u32BeNone.GetPreamble())
      PrintHexBytes(u32LeBom.GetPreamble())
      PrintHexBytes(u32BeBom.GetPreamble())
   End Sub

   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
End Class
'This example displays the following output:
'       FF FE 00 00
'       FF FE 00 00
'       00 00 FE FF

Remarks

This constructor creates an instance that uses the little endian byte order, provides a Unicode byte order mark, and does not throw an exception when an invalid encoding is detected.

Caution

For security reasons, you should enable error detection by calling the UTF32Encoding(Boolean, Boolean, Boolean) constructor and setting its throwOnInvalidCharacters argument to true.

UTF32Encoding(Boolean, Boolean)

Source:

UTF32Encoding.cs

Initializes a new instance of the UTF32Encoding class. Parameters specify whether to use the big endian byte order and whether the GetPreamble() method returns a Unicode byte order mark.

public:
 UTF32Encoding(bool bigEndian, bool byteOrderMark);

public UTF32Encoding (bool bigEndian, bool byteOrderMark);

new System.Text.UTF32Encoding : bool * bool -> System.Text.UTF32Encoding

Public Sub New (bigEndian As Boolean, byteOrderMark As Boolean)

Parameters

bigEndian

Boolean

true to use the big endian byte order (most significant byte first), or false to use the little endian byte order (least significant byte first).

byteOrderMark

Boolean

true to specify that a Unicode byte order mark is provided; otherwise, false.

Examples

The following example retrieves and displays the byte order mark for different UTF32Encoding instances.

using namespace System;
using namespace System::Text;

void PrintHexBytes( array<Byte>^bytes );

int main()
{
   
   // Create instances of UTF32Encoding, with the byte order mark and without.
   UTF32Encoding ^ u32LeNone = gcnew UTF32Encoding;
   UTF32Encoding ^ u32BeNone = gcnew UTF32Encoding( true,false );
   UTF32Encoding ^ u32LeBom = gcnew UTF32Encoding( false,true );
   UTF32Encoding ^ u32BeBom = gcnew UTF32Encoding( true,true );
   
   // Display the preamble for each instance.
   PrintHexBytes( u32LeNone->GetPreamble() );
   PrintHexBytes( u32BeNone->GetPreamble() );
   PrintHexBytes( u32LeBom->GetPreamble() );
   PrintHexBytes( u32BeBom->GetPreamble() );
}

void PrintHexBytes( array<Byte>^bytes )
{
   if ( (bytes == nullptr) || (bytes->Length == 0) )
      Console::WriteLine( "<none>" );
   else
   {
      for ( int i = 0; i < bytes->Length; i++ )
         Console::Write( "{0:X2} ", bytes[ i ] );
      Console::WriteLine();
   }
}

/* 
This example displays the following output:
      FF FE 00 00
      <none>
      FF FE 00 00
      00 00 FE FF
*/

using System;
using System.Text;

public class SamplesUTF32Encoding
{
   public static void Main()
   {
      // Create instances of UTF32Encoding, with the byte order mark and without.
      UTF32Encoding u32LeNone = new UTF32Encoding();
      UTF32Encoding u32BeNone = new UTF32Encoding( true, false );
      UTF32Encoding u32LeBom  = new UTF32Encoding( false, true );
      UTF32Encoding u32BeBom  = new UTF32Encoding( true, true );

      // Display the preamble for each instance.
      PrintHexBytes( u32LeNone.GetPreamble() );
      PrintHexBytes( u32BeNone.GetPreamble() );
      PrintHexBytes( u32LeBom.GetPreamble() );
      PrintHexBytes( u32BeBom.GetPreamble() );
   }

   public static void PrintHexBytes( byte[] bytes )
   {

      if (( bytes == null ) || ( bytes.Length == 0 ))
        {
            Console.WriteLine( "<none>" );
        }
        else  {
         for ( int i = 0; i < bytes.Length; i++ )
            Console.Write( "{0:X2} ", bytes[i] );
         Console.WriteLine();
      }
   }
}
/*
This example displays the following output.
      FF FE 00 00
      <none>
      FF FE 00 00
      00 00 FE FF
*/

Imports System.Text

Public Class SamplesUTF32Encoding   
   Public Shared Sub Main()
      ' Create instances of UTF32Encoding, with the byte order mark and without.
      Dim u32LeNone As New UTF32Encoding()
      Dim u32BeNone As New UTF32Encoding(True, False)
      Dim u32LeBom As New UTF32Encoding(False, True)
      Dim u32BeBom As New UTF32Encoding(True, True)

      ' Display the preamble for each instance.
      PrintHexBytes(u32LeNone.GetPreamble())
      PrintHexBytes(u32BeNone.GetPreamble())
      PrintHexBytes(u32LeBom.GetPreamble())
      PrintHexBytes(u32BeBom.GetPreamble())
   End Sub

   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
End Class
'This example displays the following output:
'       FF FE 00 00
'       FF FE 00 00
'       00 00 FE FF

Remarks

This constructor creates an instance that does not throw an exception when an invalid encoding is detected.

Caution

For security reasons, you should enable error detection by calling the UTF32Encoding(Boolean, Boolean, Boolean) constructor and setting its throwOnInvalidCharacters argument to true.

See also

• GetPreamble()

UTF32Encoding(Boolean, Boolean, Boolean)

Source:

UTF32Encoding.cs

Initializes a new instance of the UTF32Encoding 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.

public:
 UTF32Encoding(bool bigEndian, bool byteOrderMark, bool throwOnInvalidCharacters);

public UTF32Encoding (bool bigEndian, bool byteOrderMark, bool throwOnInvalidCharacters);

new System.Text.UTF32Encoding : bool * bool * bool -> System.Text.UTF32Encoding

Public Sub New (bigEndian As Boolean, byteOrderMark As Boolean, throwOnInvalidCharacters As Boolean)

Parameters

bigEndian

Boolean

true to use the big endian byte order (most significant byte first), or false to use the little endian byte order (least significant byte first).

byteOrderMark

Boolean

true to specify that a Unicode byte order mark is provided; otherwise, false.

throwOnInvalidCharacters

Boolean

true to specify that an exception should be thrown when an invalid encoding is detected; otherwise, false.

Examples

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

using namespace System;
using namespace System::Text;
void PrintDecodedString( array<Byte>^bytes, Encoding^ enc );
int main()
{
   
   // Create an instance of UTF32Encoding using little-endian byte order.
   // This will be used for encoding.
   UTF32Encoding^ u32LE = gcnew UTF32Encoding( false,true );
   
   // Create two instances of UTF32Encoding using big-endian byte order: one with error detection and one without.
   // These will be used for decoding.
   UTF32Encoding^ u32withED = gcnew UTF32Encoding( true,true,true );
   UTF32Encoding^ u32noED = gcnew UTF32Encoding( 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)
   String^ myStr = L"za\u0306\u01FD\u03B2\xD8FF\xDCFF";
   
   // Encode the string using little-endian byte order.
   array<Byte>^myBytes = gcnew array<Byte>(u32LE->GetByteCount( myStr ));
   u32LE->GetBytes( myStr, 0, myStr->Length, myBytes, 0 );
   
   // Decode the byte array with error detection.
   Console::WriteLine( "Decoding with error detection:" );
   PrintDecodedString( myBytes, u32withED );
   
   // Decode the byte array without error detection.
   Console::WriteLine( "Decoding without error detection:" );
   PrintDecodedString( myBytes, u32noED );
}


// Decode the bytes and display the string.
void PrintDecodedString( array<Byte>^bytes, Encoding^ enc )
{
   try
   {
      Console::WriteLine( "   Decoded string: {0}", enc->GetString( bytes, 0, bytes->Length ) );
   }
   catch ( System::ArgumentException^ e ) 
   {
      Console::WriteLine( e );
   }

   Console::WriteLine();
}

using System;
using System.Text;

public class Example
{
   public static void Main()
   {
     // Create a UTF32Encoding object with error detection enabled.
      var encExc = new UTF32Encoding(! BitConverter.IsLittleEndian, true, true);
      // Create a UTF32Encoding object with error detection disabled.
      var encRepl = new UTF32Encoding(! BitConverter.IsLittleEndian, true, false);

      // Create a byte arrays from a string, and add an invalid surrogate pair, as follows.
      //    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)
      //    an invalid low surrogate (U+01FF)
      String s = "za\u0306\u01FD\u03B2";

      // Encode the string using little-endian byte order.
      int index = encExc.GetByteCount(s);
      Byte[] bytes = new Byte[index + 4];
      encExc.GetBytes(s, 0, s.Length, bytes, 0);
      bytes[index] = 0xFF;
      bytes[index + 1] = 0xD8;
      bytes[index + 2] = 0xFF;
      bytes[index + 3] = 0x01;

      // Decode the byte array with error detection.
      Console.WriteLine("Decoding with error detection:");
      PrintDecodedString(bytes, encExc);

      // Decode the byte array without error detection.
      Console.WriteLine("Decoding without error detection:");
      PrintDecodedString(bytes, encRepl);
   }

   // Decode the bytes and display the string.
   public static void PrintDecodedString(Byte[] bytes, Encoding enc)
   {
      try {
         Console.WriteLine("   Decoded string: {0}", enc.GetString(bytes, 0, bytes.Length));
      }
      catch (DecoderFallbackException e) {
         Console.WriteLine(e.ToString());
      }
      Console.WriteLine();
   }
}
// The example displays the following output:
//    Decoding with error detection:
//    System.Text.DecoderFallbackException: Unable to translate bytes [FF][D8][FF][01] at index
//    20 from specified code page to Unicode.
//       at System.Text.DecoderExceptionFallbackBuffer.Throw(Byte[] bytesUnknown, Int32 index)
//       at System.Text.DecoderExceptionFallbackBuffer.Fallback(Byte[] bytesUnknown, Int32 index
//    )
//       at System.Text.DecoderFallbackBuffer.InternalFallback(Byte[] bytes, Byte* pBytes)
//       at System.Text.UTF32Encoding.GetCharCount(Byte* bytes, Int32 count, DecoderNLS baseDeco
//    der)
//       at System.Text.UTF32Encoding.GetString(Byte[] bytes, Int32 index, Int32 count)
//       at Example.PrintDecodedString(Byte[] bytes, Encoding enc)
//
//    Decoding without error detection:
//       Decoded string: zăǽβ�

Imports System.Text

Public Module Example
   Public Sub Main()
      ' Create a UTF32Encoding object with error detection enabled.
      Dim encExc As New UTF32Encoding(Not BitConverter.IsLittleEndian, True, True)
      ' Create a UTF32Encoding object with error detection disabled.
      Dim encRepl As New UTF32Encoding(Not BitConverter.IsLittleEndian, True, False)

      ' Create a byte arrays from a string, and add an invalid surrogate pair, as follows.
      '    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)
      '    an invalid low surrogate (U+01FF)
      Dim s As String = "za" & ChrW(&H0306) & ChrW(&H01FD) & ChrW(&H03B2)

      ' Encode the string using little-endian byte order.
      Dim index As Integer = encExc.GetBytecount(s)
      Dim bytes(index + 3) As Byte
      encExc.GetBytes(s, 0, s.Length, bytes, 0)
      bytes(index) = &hFF
      bytes(index + 1) = &hD8
      bytes(index + 2) = &hFF
      bytes(index + 3) = &h01

      ' Decode the byte array with error detection.
      Console.WriteLine("Decoding with error detection:")
      PrintDecodedString(bytes, encExc)

      ' Decode the byte array without error detection.
      Console.WriteLine("Decoding without error detection:")
      PrintDecodedString(bytes, encRepl)
   End Sub

   ' Decode the bytes and display the string.
   Public Sub PrintDecodedString(bytes() As Byte, enc As Encoding)
      Try
         Console.WriteLine("   Decoded string: {0}", enc.GetString(bytes, 0, bytes.Length))
      Catch e As DecoderFallbackException
         Console.WriteLine(e.ToString())
      End Try
      Console.WriteLine()
   End Sub
End Module
' The example displays the following output:
'    Decoding with error detection:
'    System.Text.DecoderFallbackException: Unable to translate bytes [FF][D8][FF][01] at index
'    20 from specified code page to Unicode.
'       at System.Text.DecoderExceptionFallbackBuffer.Throw(Byte[] bytesUnknown, Int32 index)
'       at System.Text.DecoderExceptionFallbackBuffer.Fallback(Byte[] bytesUnknown, Int32 index
'    )
'       at System.Text.DecoderFallbackBuffer.InternalFallback(Byte[] bytes, Byte* pBytes)
'       at System.Text.UTF32Encoding.GetCharCount(Byte* bytes, Int32 count, DecoderNLS baseDeco
'    der)
'       at System.Text.UTF32Encoding.GetString(Byte[] bytes, Int32 index, Int32 count)
'       at Example.PrintDecodedString(Byte[] bytes, Encoding enc)
'
'    Decoding without error detection:
'       Decoded string: zăǽβ�

Remarks

If throwOnInvalidCharacters 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.

Caution

For security reasons, you should enable error detection by calling the UTF32Encoding(Boolean, Boolean, Boolean) constructor and setting its throwOnInvalidCharacters argument to true.

See also

• GetPreamble()