Export (0) Print
Expand All

Encoding.GetPreamble Method

When overridden in a derived class, returns a sequence of bytes that specifies the encoding used.

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

'Declaration
Public Overridable Function GetPreamble As Byte()
'Usage
Dim instance As Encoding
Dim returnValue As Byte()

returnValue = instance.GetPreamble
public byte[] GetPreamble ()
public function GetPreamble () : byte[]

Return Value

A byte array containing a sequence of bytes that specifies the encoding used. -or- A byte array of length zero, if a preamble is not required.

The UTF-16 and the UTF-32 encoders 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 (U+0041) is serialized as follows (in hexadecimal):

  • UTF-16 big-endian byte order: 00 41

  • UTF-16 little-endian byte order: 41 00

  • UTF-32 big-endian byte order: 00 00 00 41

  • UTF-32 little-endian byte order: 41 00 00 00

Optionally, the Encoding provides a preamble which is an array of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. If the preamble contains a byte order mark (In Unicode, 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):

  • UTF-8: EF BB BF

  • UTF-16 big-endian byte order: FE FF

  • UTF-16 little-endian byte order: FF FE

  • UTF-32 big-endian byte order: 00 00 FE FF

  • UTF-32 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. However, most encodings do not provide a preamble. To ensure that the encoded bytes are decoded properly, use a Unicode encoding (that is, UTF8Encoding, UnicodeEncoding, or UTF32Encoding) with a preamble.

The following code example determines the byte order of the encoding based on the preamble.

Imports System
Imports System.Text

Namespace GetPreambleExample
   Class GetPreambleExampleClass
      Shared Sub Main()
         Dim [unicode] As Encoding = Encoding.Unicode

         ' Get the preamble for the Unicode encoder. 
         ' In this case the preamble contains the byte order mark (BOM).
         Dim preamble As Byte() = [unicode].GetPreamble()

         ' Make sure a preamble was returned 
         ' and is large enough to contain a BOM.
         If preamble.Length >= 2 Then
            If preamble(0) = &HFE And preamble(1) = &HFF Then
               Console.WriteLine("The Unicode encoder is encoding in big-endian order.")
            Else
               If preamble(0) = &HFF And preamble(1) = &HFE Then
                  Console.WriteLine("The Unicode encoder is encoding in little-endian order.")
               End If
            End If
         End If
      End Sub
   End Class
End Namespace

package GetPreambleExample; 

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

class GetPreambleExampleClass
{
    public static void main(String[] args)
    {
        Encoding unicode = Encoding.get_Unicode();

        // Get the preamble for the Unicode encoder. 
        // In this case the preamble contains the byte order mark (BOM).
        ubyte preamble[] = unicode.GetPreamble();

        // Make sure a preamble was returned 
        // and is large enough to containa BOM.
        if(preamble.length >= 2) {
            if(preamble[0] == 0xFE && preamble[1] == 0xFF) {
                Console.WriteLine("The Unicode encoder is "
                + "encoding in big-endian order.");
            }
            else {
                if(preamble[0] == 0xFF && preamble[1] == 0xFE) {
                    Console.WriteLine("The Unicode encoder is" 
                    + " encoding in little-endian order.");
                }
            }
        }
    } //main
} //GetPreambleExampleClass 

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

.NET Compact Framework

Supported in: 2.0, 1.0

Community Additions

ADD
Show:
© 2014 Microsoft