UTF32Encoding.GetPreamble Metoda

Definice

Obor názvů:

System.Text

Sestavení:

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

Zdroj:

UTF32Encoding.cs

Vrátí znak pořadí bajtů Unicode kódovaný ve formátu UTF-32, pokud UTF32Encoding je objekt nakonfigurovaný tak, aby ho mohl zadat.

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

public override byte[] GetPreamble();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

Návraty

Byte[]

Bajtové pole obsahující značku pořadí bajtů Unicode, pokud UTF32Encoding je objekt nakonfigurován tak, aby ho mohl zadat. V opačném případě tato metoda vrátí pole bajtů nulové délky.

Příklady

Následující příklad kódu načte a zobrazí značku pořadí bajtů pro různé UTF32Encoding instance.

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

Následující příklad vytvoří instanci dvou UTF32Encoding objektů, z nichž první neposkytuje kusovník a druhý objekt. Potom volá metodu GetPreamble pro zápis kusovníku do souboru před zápisem řetězce s kódováním UTF-32. Jak ukazuje výstup z příkladu, soubor, který ukládá bajty z druhého kodéru, má čtyři bajty, které první.

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.

Soubory můžete také porovnat pomocí fc příkazu v okně konzoly nebo můžete zkontrolovat soubory v textovém editoru, který obsahuje šestnáctkový režim zobrazení. Všimněte si, že když je soubor otevřen v editoru, který podporuje UTF-32, bom se nezobrazí.

Poznámky

Objekt UTF32Encoding může poskytnout preambuli, což je pole bajtů, které lze předponu posloupnosti bajtů vyplývajících z procesu kódování. Prefacing sekvence kódovaných bajtů se značkou pořadí bajtů (kódové body U+0000 U+FEFF) pomáhá dekodéru určit pořadí bajtů a formát transformace nebo UTF. Znak pořadí bajtů Unicode (BOM) je serializován následujícím způsobem (v šestnáctkové soustavě):

• Velké endian bajt pořadí: 00 00 FE FF

• Malé endian bajtové pořadí: FF FE 00 00

Můžete vytvořit instanci objektu UTF32Encoding , jehož GetPreamble metoda vrátí platnou bom následujícími způsoby:

• Načtením objektu UTF32Encoding vráceného Encoding.UTF32 vlastností.

• Voláním konstruktoru bez UTF32Encoding() parametrů vytvořte instanci objektu UTF32Encoding .

• true Zadáním hodnoty argumentu byteOrderMark konstruktorůmUTF32Encoding.UTF32Encoding

Doporučujeme použít kusovník, protože poskytuje téměř určitou identifikaci kódování souborů, které jinak ztratily odkaz na UTF32Encoding objekt, například neoznačené nebo nesprávně označené webové data nebo náhodné textové soubory uložené v případě, že firma neměla mezinárodní obavy nebo jiná data. Problémy uživatelů se často můžou vyhnout, pokud jsou data konzistentně a správně označená.

Pro standardy, které poskytují typ kódování, je kusovník poněkud redundantní. Dá se ale použít k tomu, aby server posílal správnou hlavičku kódování. Alternativně se dá použít jako záložní v případě, že se kódování jinak ztratí.

Používání kusovníku má určité nevýhody. Například znalost omezení databázových polí, která používají kusovník, může být obtížné. Zřetězení souborů může být také problém, například když se soubory sloučí tak, aby nepotřebný znak mohl skončit uprostřed dat. I přes několik nevýhod se však důrazně doporučuje použití kusovníku.

Další informace o pořadí bajtů a značce pořadí bajtů naleznete v tématu Standard Unicode na domovské stránce Unicode.

Důležité

Chcete-li zajistit, aby kódované bajty byly dekódovány správně, měli byste předkódovat bajty s preambuli. Všimněte si, že GetBytes metoda nepředkládá kusovník na sekvenci kódovaných bajtů; poskytnutí kusovníku na začátku příslušného bajtového streamu je zodpovědností vývojáře.