次の方法で共有


UTF32Encoding.GetPreamble メソッド

定義

UTF32Encoding オブジェクトが UTF-32 形式でエンコードされた Unicode バイト順マークを提供するように構成されている場合、そのようなマークが返されます。

public:
 override cli::array <System::Byte> ^ GetPreamble();
public override byte[] GetPreamble ();
override this.GetPreamble : unit -> byte[]
Public Overrides Function GetPreamble () As Byte()

戻り値

Byte[]

Unicode のバイト順マークが格納されたバイト配列を提供するように UTF32Encoding オブジェクトが構成されている場合には、そうしたバイト配列。 それ以外の場合、このメソッドは長さがゼロのバイト配列を返します。

次のコード例では、さまざまな UTF32Encoding インスタンスのバイト オーダー マークを取得して表示します。

using namespace System;
using namespace System::Text;

void PrintHexBytes( array<Byte>^bytes );

int main()
{
   
   // Create instances of UTF32Encoding, with the byte order mark and without.
   UTF32Encoding ^ u32LeNone = gcnew UTF32Encoding;
   UTF32Encoding ^ u32BeNone = gcnew UTF32Encoding( true,false );
   UTF32Encoding ^ u32LeBom = gcnew UTF32Encoding( false,true );
   UTF32Encoding ^ u32BeBom = gcnew UTF32Encoding( true,true );
   
   // Display the preamble for each instance.
   PrintHexBytes( u32LeNone->GetPreamble() );
   PrintHexBytes( u32BeNone->GetPreamble() );
   PrintHexBytes( u32LeBom->GetPreamble() );
   PrintHexBytes( u32BeBom->GetPreamble() );
}

void PrintHexBytes( array<Byte>^bytes )
{
   if ( (bytes == nullptr) || (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
*/
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

次の例では、2 つの UTF32Encoding オブジェクトをインスタンス化します。そのうちの 1 つ目は BOM を提供せず、2 番目のオブジェクトは BOM を提供しません。 次に、メソッドを GetPreamble 呼び出して、UTF-32 でエンコードされた文字列を書き込む前に BOM をファイルに書き込みます。 この例の出力が示すように、2 番目のエンコーダーからのバイトを保存するファイルには、最初の 4 バイトが追加されています。

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 比較することも、16 進表示モードを含むテキスト エディターでファイルを検査することもできます。 UTF-32 をサポートするエディターでファイルを開くと、BOM は表示されないことに注意してください。

注釈

このオブジェクトは UTF32Encoding プリアンブルを提供できます。プリアンブルは、エンコード プロセスに起因するバイトシーケンスにプレフィックスを付けることができるバイトの配列です。 エンコードされたバイトのシーケンスをバイト順マーク (コード ポイント U+0000 U+FEFF) で前に付けると、デコーダーはバイト順と変換形式 (UTF) を決定するのに役立ちます。 Unicode バイト順マーク (BOM) は、次のようにシリアル化されます (16 進数)。

  • ビッグ エンディアン バイトオーダー: 00 00 FE FF

  • リトル エンディアン バイト順: FF FE 00 00

メソッドが有効な UTF32Encoding BOM を返すオブジェクト GetPreamble は、次の方法でインスタンス化できます。

BOM を使用することをお勧めします。これは、タグ付けされていない Web データや不適切にタグ付けされた Web データ、企業が国際的な懸念やその他のデータを持っていないときに保存されたランダムテキスト ファイルなど、オブジェクトへの UTF32Encoding 参照を失ったファイルのエンコードのほぼ一定の識別を提供するためです。 多くの場合、データが一貫して適切にタグ付けされている場合、ユーザーの問題は回避される可能性があります。

エンコードの種類を提供する標準の場合、BOM はやや冗長です。 ただし、このメソッドを使用して、サーバーが正しいエンコードヘッダーを送信できるようにすることができます。 または、エンコードが失われた場合にフォールバックとして使用することもできます。

BOM の使用にはいくつかの欠点があります。 たとえば、BOM を使用するデータベースフィールドを制限する方法を理解することは困難です。 ファイルの連結も問題になることがあります。たとえば、不要な文字がデータの途中で終了するような方法でファイルをマージする場合などです。 ただし、いくつかの欠点がありますが、BOM を使用することを強くお勧めします。

バイト順とバイト順マークの詳細については、unicodeホームページの unicode 標準を参照してください。

重要

エンコードされたバイトが正しくデコードされるようにするには、エンコードされたバイトをプリアンブルでプレフィックスとして付ける必要があります。 GetBytesこのメソッドでは、エンコードされたバイトのシーケンスに BOM を付加しません。適切なバイト ストリームの先頭に BOM を指定するのは開発者の責任です。

適用対象