UTF32Encoding.GetPreamble Метод

Определение

Пространство имен:

System.Text

Сборки:

netstandard.dll, System.Text.Encoding.Extensions.dll

Исходный код:

UTF32Encoding.cs

Возвращает метку порядка байтов Юникода, закодированную в формате UTF-32, если UTF32Encoding объект настроен для предоставления одного.

public:
 override cli::array <System::Byte> ^ GetPreamble();

public override byte[] GetPreamble();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Возвращаемое значение

Byte[]

Массив байтов, содержащий знак порядка байтов Юникода, если UTF32Encoding объект настроен для предоставления одного. В противном случае этот метод возвращает массив байтов нулевой длины.

Примеры

В следующем примере кода извлекается и отображается метка порядка байтов для разных UTF32Encoding экземпляров.

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

В следующем примере создается экземпляр двух UTF32Encoding объектов, первый из которых не предоставляет BOM и второй из которых выполняется. Затем он вызывает GetPreamble метод для записи BOM в файл перед записью строки в кодировке UTF-32. Как показано в выходных данных из примера, файл, который сохраняет байты из второго кодировщика, имеет четыре больше байтов, что первый.

using System;
using System.IO;
using System.Text;

public class Example
{
   public static void Main()
   {
      String s = "This is a string to write to a file using UTF-32 encoding.";

      // Write a file using the default constructor without a BOM.
      var enc = new UTF32Encoding(! BitConverter.IsLittleEndian, false);
      Byte[] bytes = enc.GetBytes(s);
      WriteToFile(@".\NoPreamble.txt", enc, bytes);

      // Use BOM.
      enc = new UTF32Encoding(! BitConverter.IsLittleEndian, true);
      WriteToFile(@".\Preamble.txt", enc, bytes);
   }

   private static void WriteToFile(String fn, Encoding enc, Byte[] bytes)
   {
      var fs = new FileStream(fn, FileMode.Create);
      Byte[] preamble = enc.GetPreamble();
      fs.Write(preamble, 0, preamble.Length);
      Console.WriteLine("Preamble has {0} bytes", preamble.Length);
      fs.Write(bytes, 0, bytes.Length);
      Console.WriteLine("Wrote {0} bytes to {1}.", fs.Length, fn);
      fs.Close();
      Console.WriteLine();
   }
}
// The example displays the following output:
//       Preamble has 0 bytes
//       Wrote 232 bytes to .\NoPreamble.txt.
//
//       Preamble has 4 bytes
//       Wrote 236 bytes to .\Preamble.txt.

Imports System.IO
Imports System.Text

Module Example
   Public Sub Main()
      Dim s As String = "This is a string to write to a file using UTF-32 encoding."
      
      ' Write a file using the default constructor without a BOM.
      Dim enc As New UTF32Encoding(Not BitConverter.IsLittleEndian, False)
      Dim bytes() As Byte = enc.GetBytes(s)
      WriteToFile("NoPreamble.txt", enc, bytes)

      ' Use BOM.
      enc = New UTF32Encoding(Not BitConverter.IsLittleEndian, True)
      WriteToFile("Preamble.txt", enc, bytes)
   End Sub

   Private Sub WriteToFile(fn As String, enc As Encoding, bytes As Byte())
      Dim fs As New FileStream(fn, FileMode.Create)
      Dim preamble() As Byte = enc.GetPreamble()
      fs.Write(preamble, 0, preamble.Length)
      Console.WriteLine("Preamble has {0} bytes", preamble.Length)
      fs.Write(bytes, 0, bytes.Length)
      Console.WriteLine("Wrote {0} bytes to {1}.", fs.Length, fn)
      fs.Close()
      Console.WriteLine()
   End Sub
End Module
' The example displays the following output:
'       Preamble has 0 bytes
'       Wrote 232 bytes to NoPreamble.txt.
'
'       Preamble has 4 bytes
'       Wrote 236 bytes to Preamble.txt.

Вы также можете сравнить файлы с помощью fc команды в окне консоли или проверить файлы в текстовом редакторе, который включает режим шестнадцатеричного представления. Обратите внимание, что при открытии файла в редакторе, поддерживающем UTF-32, BOM не отображается.

Комментарии

Объект UTF32Encoding может предоставить преамблирование, которое представляет собой массив байтов, который можно префиксировать в последовательность байтов, полученных из процесса кодирования. Подготовка последовательности закодированных байтов с меткой порядка байтов (кодовые точки U+0000 U+FEFF) помогает декодеру определить порядок байтов и формат преобразования или UTF. Метка порядка байтов Юникода сериализуется следующим образом (в шестнадцатеричном формате):

• Порядок байтов больших байтов: 000 00 FE FF

• Маленький байтовый порядок: FF FE 00 00

Вы можете создать экземпляр объекта, метод которого GetPreamble возвращает допустимый UTF32Encoding BOM следующим образом:

• Извлекая объект, UTF32Encoding возвращаемый свойством Encoding.UTF32 .

• Вызывая конструктор без UTF32Encoding() параметров для создания экземпляра UTF32Encoding объекта.

• true Указав в качестве значения аргумента byteOrderMarkUTF32Encoding конструктора и UTF32Encoding конструктора.

Рекомендуется использовать BOM, так как он обеспечивает почти определенную идентификацию кодировки для файлов, которые в противном случае потеряли ссылку на UTF32Encoding объект, например, не помеченные или неправильно помеченные веб-данные, или случайные текстовые файлы, хранящиеся, когда у бизнеса нет международных проблем или других данных. Часто проблемы с пользователем могут быть избежать, если данные последовательно и правильно помечены.

Для стандартов, предоставляющих тип кодирования, BOM является несколько избыточным. Однако его можно использовать для отправки правильного заголовка кодировки на сервере. Кроме того, его можно использовать в качестве резервного варианта, если кодировка в противном случае потеряна.

Существует ряд недостатков использования BOM. Например, зная, как ограничить поля базы данных, использующие BOM, может быть сложной задачей. Объединение файлов может быть проблемой, например, когда файлы объединяются таким образом, что ненужный символ может оказаться в середине данных. Несмотря на некоторые недостатки, однако, использование BOM настоятельно рекомендуется.

Дополнительные сведения о порядке байтов и отметке порядка байтов см. в разделе "Стандартный юникод" на домашней странице юникода .

Это важно

Чтобы убедиться, что кодированные байты декодированы должным образом, необходимо закодировать префикс байтов с префиксом. Обратите внимание, что GetBytes метод не предопределен к последовательности закодированных байтов; предоставление BOM в начале соответствующего потока байтов является ответственностью разработчика.