UTF32Encoding.GetPreamble Metode

Definisi

Ruang nama:

System.Text

Rakitan:

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

Sumber:

UTF32Encoding.cs

Mengembalikan tanda urutan byte Unicode yang dikodekan dalam format UTF-32, jika objek dikonfigurasi UTF32Encoding untuk menyediakannya.

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

public override byte[] GetPreamble();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Mengembalikan

Byte[]

Array byte yang berisi tanda urutan byte Unicode, jika objek dikonfigurasi UTF32Encoding untuk menyediakannya. Jika tidak, metode ini mengembalikan array byte panjang nol.

Contoh

Contoh kode berikut mengambil dan menampilkan tanda urutan byte untuk instans yang berbeda 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

Contoh berikut membuat instans dua UTF32Encoding objek, yang pertama tidak menyediakan BOM dan yang kedua. Kemudian memanggil GetPreamble metode untuk menulis BOM ke file sebelum menulis string yang dikodekan UTF-32. Seperti yang ditunjukkan oleh output dari contoh, file yang menyimpan byte dari encoder kedua memiliki empat byte lagi yang pertama.

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.

Anda juga dapat membandingkan file dengan menggunakan fc perintah di jendela konsol, atau Anda dapat memeriksa file di editor teks yang menyertakan mode Tampilan Hex. Perhatikan bahwa ketika file dibuka di editor yang mendukung UTF-32, BOM tidak ditampilkan.

Keterangan

Objek UTF32Encoding dapat memberikan awalan, yang merupakan array byte yang dapat diawali dengan urutan byte yang dihasilkan dari proses pengodean. Prefacing urutan byte yang dikodekan dengan tanda urutan byte (titik kode U+0000 U+FEFF) membantu dekoder menentukan urutan byte dan format transformasi, atau UTF. Tanda urutan byte Unicode (BOM) diserialisasikan sebagai berikut (dalam heksadesimal):

• Urutan byte big endian: 00 00 FE FF

• Urutan byte little endian: FF FE 00 00

Anda dapat membuat UTF32Encoding instans objek yang metodenya GetPreamble mengembalikan BOM yang valid dengan cara berikut:

• Dengan mengambil objek yang UTF32Encoding dikembalikan oleh Encoding.UTF32 properti .

• Dengan memanggil konstruktor tanpa UTF32Encoding() parameter untuk membuat UTF32Encoding instans objek.

• Dengan menyediakan true sebagai nilai byteOrderMark argumen ke UTF32Encoding konstruktor dan UTF32Encoding .

Kami menyarankan agar Anda menggunakan BOM, karena menyediakan identifikasi yang hampir pasti dari pengodean untuk file yang telah kehilangan referensi ke UTF32Encoding objek, misalnya, data web yang tidak diberi tag atau tidak benar, atau file teks acak yang disimpan ketika bisnis tidak memiliki kekhawatiran internasional atau data lainnya. Seringkali, masalah pengguna mungkin dihindari jika data ditandai dengan konsisten dan benar.

Untuk standar yang menyediakan jenis pengodean, BOM agak berlebihan. Namun, ini dapat digunakan untuk membantu server mengirim header pengodean yang benar. Atau, ini dapat digunakan sebagai fallback jika pengodean hilang.

Ada beberapa kelemahan menggunakan BOM. Misalnya, mengetahui cara membatasi bidang database yang menggunakan BOM bisa sulit. Penggabungan file juga dapat menjadi masalah, misalnya, ketika file digabungkan sewaktu-waktu sehingga karakter yang tidak perlu dapat berakhir di tengah data. Terlepas dari beberapa kelemahan, namun, penggunaan BOM sangat disarankan.

Untuk informasi selengkapnya tentang urutan byte dan tanda urutan byte, lihat Standar Unicode di halaman beranda unicode .

Penting

Untuk memastikan bahwa byte yang dikodekan didekode dengan benar, Anda harus awali byte yang dikodekan dengan awalan. Perhatikan bahwa GetBytes metode ini tidak menambahkan BOM ke urutan byte yang dikodekan; memasok BOM di awal aliran byte yang sesuai adalah tanggung jawab pengembang.