Export (0) Print
Expand All

UTF32Encoding.GetPreamble Method

Note: This method is new in the .NET Framework version 2.0.

Returns a Unicode byte order mark encoded in UTF-32 format, if the constructor for this instance requested that a byte order mark be provided.

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

public override byte[] GetPreamble ()
public byte[] GetPreamble ()
public override function GetPreamble () : byte[]

Return Value

A byte array containing the Unicode byte order mark, if the constructor for this instance requested that a byte order mark be provided. Otherwise, a byte array of length zero.

If the preamble is prefixed to an encoded stream, it helps the decoder to identify the encoding format used.

The encoder can use the big-endian byte order (most significant byte first) or the little-endian byte order (least significant byte first). For example, the Latin Capital Letter A (code point U+0041) is serialized as follows (in hexadecimal):

  • Big-endian byte order: 00 00 00 41

  • Little-endian byte order: 41 00 00 00

Optionally, the UTF32Encoding provides a preamble, which is an array of bytes that you can prefix to the sequence of bytes resulting from the encoding process. If the preamble contains a byte order mark (code point U+FEFF), it helps the decoder determine the byte order and the transformation format or UTF. The Unicode byte order mark is serialized as follows (in hexadecimal):

  • Big-endian byte order: 00 00 FE FF

  • Little-endian byte order: FF FE 00 00

It is generally more efficient to store 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 machines.

For more information on byte order and the byte order mark, see The Unicode Standard at www.unicode.org.

Caution noteCaution

To ensure that the encoded bytes are decoded properly, prefix encoded bytes with a preamble.

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

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 code produces the following output.

&lt;none&gt;
&lt;none&gt;
FF FE 00 00
00 00 FE FF

*/


import System.*;
import System.Text.*;

public class SamplesUTF32Encoding
{
    public static void main(String[] args)
    {
        // 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());
    } //main
   
    public static void PrintHexBytes(ubyte bytes[])
    {
        if(bytes == null || bytes.length == 0) {
            Console.WriteLine("<none>");
        }
        else {
            for(int i = 0; i < bytes.length; i++) {
                Console.Write("{0:X2} ", 
                    ((System.Byte)bytes[i]).ToString("X2"));
            }
            Console.WriteLine();
        }
    } //PrintHexBytes
} //SamplesUTF32Encoding

/* 
This code produces the following output.

FF FE 00 00
<none>
FF FE 00 00
00 00 FE FF

*/


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

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

.NET Framework

Supported in: 2.0

Community Additions

ADD
Show:
© 2014 Microsoft