UTF32Encoding.GetPreamble Metoda

Reference

Definice

Obor názvů:: System.Text

Sestavení:: mscorlib.dll, System.Text.Encoding.Extensions.dll

Sestavení:: System.Text.Encoding.Extensions.dll

Sestavení:: mscorlib.dll

Sestavení:: netstandard.dll

Důležité

Některé informace platí pro předběžně vydaný produkt, který se může zásadně změnit, než ho výrobce nebo autor vydá. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

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í znaménko pořadí bajtů Unicode, pokud UTF32Encoding je objekt nakonfigurovaný 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 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

Následující příklad vytvoří instanci dvouobjektůch dvou UTF32Encoding objektů, první z těchto objektů neposkytuje boM a druhou. Potom zavolá metodu GetPreamble pro zápis boM do souboru před zápisem řetězce kódování UTF-32. Jak ukazuje výstup z příkladu, soubor, který ukládá bajty z druhého kodéru, má čtyři další 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 režim zobrazení Hex. 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í. Předpřipravení sekvence zakódovaných bajtů se značkou pořadí bajtů (body kódu U+0000 U+FEFF) pomáhá dekodéru určit pořadí bajtů a formát transformace nebo UTF. Značka pořadí bajtů Unicode (BOM) se serializuje následujícím způsobem (v šestnáctkovém formátu):

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

Můžete vytvořit instanci objektu, jehož GetPreamble metoda vrátí platnou UTF32Encoding 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 .
Zadáním true hodnoty argumentu byteOrderMark UTF32Encoding pro konstruktory a UTF32Encoding konstruktory.

Doporučujeme použít boM, 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á mezinárodní obavy ani 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 boM poněkud redundantní. Dá se ale použít k tomu, aby server odeslal správnou hlavičku kódování. Alternativně se dá použít jako náhradní v případě, že se kódování jinak ztratí.

Použití kusovníku má určité nevýhody. Například znalost omezení databázových polí, která používají kusovníky, 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. Navzdory několika nevýhodám se však důrazně doporučuje použití kusovníku.

Další informace o pořadí bajtů a znaménku pořadí bajtů najdete v tématu Standard Unicode na domovské stránce Unicode.

Důležité

Abyste zajistili správné dekódování zakódovaných bajtů, měli byste předponu zakódovaných bajtů předponovat 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.

Platí pro

Sdílet prostřednictvím