GetPreamble

Returns a Unicode byte order mark encoded in UTF-8 format, if the constructor for this instance requests a byte order mark.

 Public Function GetPreamble ( ) As Byte ( )

Return Values

Remarks

Optionally, the UTF8Encoding object 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 (code point U+FEFF), it helps the decoder determine the byte order and the transformation format or UTF. The Unicode byte order mark (BOM) is serialized as EF BB BF (in hexadecimal).

Your applications are recommended to use the BOM, as it provides nearly certain identification of an encoding for files that otherwise have lost reference to the UTF8Encoding object, for example, untagged or improperly tagged web data or random text files stored when a business did not have international concerns or other data. Often user problems might be avoided if data is consistently and properly tagged.

For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost.

There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended.

For more information on byte order and the byte order mark, see The Unicode Standard at the Unicode home page.

Examples

The following example demonstrates how to use the GetPreamble method to return the Unicode byte order mark encoded in UTF-8 format. Notice that the default constructor for UTF8Encoding does not provide a preamble.

Public Sub Main()
    Dim UTF8NoPreamble      As UTF8Encoding
    Dim UTF8WithPreamble    As UTF8Encoding
    Dim preamble()          As Byte
    
    Set UTF8NoPreamble = New UTF8Encoding
    Set UTF8WithPreamble = NewUTF8Encoding(True)
    
    preamble = UTF8NoPreamble.GetPreamble
    Console.WriteLine "UTF8NoPreamble"
    Console.WriteLine " preamble length: {0}", CorArray.Length(preamble)
    Console.WriteValue " preamble: "
    ShowArray preamble
    
    preamble = UTF8WithPreamble.GetPreamble
    Console.WriteLine "UTF8WithPreamble"
    Console.WriteLine " preamble length: {0}", CorArray.Length(preamble)
    Console.WriteValue " preamble: "
    ShowArray preamble
    
    Console.ReadKey
End Sub

Private Sub ShowArray(ByRef Arr() As Byte)
    Dim Element As Variant
    
    For Each Element In Arr
        Console.WriteValue "[{0:X2}]", Element
    Next
    
    Console.WriteLine
End Sub

' This code produces the following output.
'
'    UTF8NoPreamble
'     preamble length: 0
'     preamble:
'    UTF8WithPreamble
'     preamble length: 3
'     preamble: [EF][BB][BF]

See Also

Project CorLib Overview

Class UTF8Encoding Overview