UTF8Encoding.GetBytes Metoda

Definicja

Przestrzeń nazw:

System.Text

Zestaw:

System.Text.Encoding.Extensions.dll

Koduje zestaw znaków w sekwencji bajtów.

Przeciążenia

GetBytes(ReadOnlySpan<Char>, Span<Byte>)	Koduje określony zakres znaków do określonego zakresu bajtów.
GetBytes(Char*, Int32, Byte*, Int32)	Koduje zestaw znaków rozpoczynający się od określonego wskaźnika znaku do sekwencji bajtów przechowywanych w określonym wskaźniku bajtów.
GetBytes(Char[], Int32, Int32, Byte[], Int32)	Koduje zestaw znaków z określonej tablicy znaków do określonej tablicy bajtów.
GetBytes(String, Int32, Int32, Byte[], Int32)	Koduje zestaw znaków z określonej String tablicy bajtów.

GetBytes(ReadOnlySpan<Char>, Span<Byte>)

Źródło:

UTF8Encoding.cs

Koduje określony zakres znaków do określonego zakresu bajtów.

public:
 override int GetBytes(ReadOnlySpan<char> chars, Span<System::Byte> bytes);

public override int GetBytes (ReadOnlySpan<char> chars, Span<byte> bytes);

override this.GetBytes : ReadOnlySpan<char> * Span<byte> -> int

Public Overrides Function GetBytes (chars As ReadOnlySpan(Of Char), bytes As Span(Of Byte)) As Integer

Parametry

chars

ReadOnlySpan<Char>

Zakres znaków do kodowania.

bytes

Span<Byte>

Zakres zawierający wynikowy zestaw bajtów.

Zwraca

Int32

Rzeczywista liczba bajtów zapisanych w pliku bytes.

Uwagi

Aby obliczyć dokładny rozmiar wymagany przez GetBytes program do przechowywania bajtów wynikowych, należy wywołać metodę GetByteCount . Aby obliczyć maksymalny rozmiar, należy wywołać metodę GetMaxByteCount . Metoda GetByteCount zwykle przydziela mniej pamięci, podczas gdy GetMaxByteCount metoda zwykle wykonuje się szybciej.

W przypadku wykrywania błędów nieprawidłowa sekwencja powoduje, że ta metoda zgłasza ArgumentException wyjątek. Bez wykrywania błędów nieprawidłowe sekwencje są ignorowane i nie jest zgłaszany żaden wyjątek.

Dane do przekonwertowania, takie jak dane odczytywane ze strumienia, mogą być dostępne tylko w blokach sekwencyjnych. W tym przypadku lub jeśli ilość danych jest tak duża, że należy podzielić je na mniejsze bloki, użyć Decoder metody lub Encoder zwróconej odpowiednio przez GetDecoder metodę lub GetEncoder metodę.

Aby upewnić się, że zakodowane bajty są prawidłowo dekodowane, gdy są zapisywane jako plik lub jako strumień, można prefiks strumienia zakodowanych bajtów z prefiksem. Wstawianie prezbiory na początku strumienia bajtów (na przykład na początku serii bajtów do zapisania w pliku) jest odpowiedzialnością dewelopera. Metoda GetBytes nie poprzedza prefiksu początku sekwencji zakodowanych bajtów.

GetBytes(Char*, Int32, Byte*, Int32)

Źródło:

UTF8Encoding.cs

Ważne

Ten interfejs API nie jest zgodny ze specyfikacją CLS.

Koduje zestaw znaków rozpoczynający się od określonego wskaźnika znaku do sekwencji bajtów przechowywanych w określonym wskaźniku bajtów.

public:
 override int GetBytes(char* chars, int charCount, System::Byte* bytes, int byteCount);

[System.CLSCompliant(false)]
public override int GetBytes (char* chars, int charCount, byte* bytes, int byteCount);

[<System.CLSCompliant(false)>]
override this.GetBytes : nativeptr<char> * int * nativeptr<byte> * int -> int

Parametry

chars

Char*

Wskaźnik do pierwszego znaku w celu zakodowania.

charCount

Int32

Liczba znaków do zakodowania.

bytes

Byte*

Wskaźnik do lokalizacji, w której należy rozpocząć pisanie wynikowej sekwencji bajtów.

byteCount

Int32

Maksymalna liczba bajtów do zapisu.

Zwraca

Int32

Rzeczywista liczba bajtów zapisanych w lokalizacji wskazanej przez bytes.

Atrybuty

CLSCompliantAttribute

Wyjątki

ArgumentNullException

chars to null.

-lub-

bytes to null.

ArgumentOutOfRangeException

charCount wartość lub byteCount jest mniejsza niż zero.

ArgumentException

Wykrywanie błędów jest włączone i chars zawiera nieprawidłową sekwencję znaków.

-lub-

byteCount jest mniejsza niż wynikowa liczba bajtów.

EncoderFallbackException

Wystąpił powrót (aby uzyskać więcej informacji, zobacz Kodowanie znaków na platformie .NET)

-I-

EncoderFallback parametr jest ustawiony na EncoderExceptionFallbackwartość .

Uwagi

Aby obliczyć dokładny rozmiar tablicy wymagany przez GetBytes program do przechowywania bajtów wynikowych, należy wywołać metodę GetByteCount . Aby obliczyć maksymalny rozmiar tablicy, należy wywołać metodę GetMaxByteCount . Metoda GetByteCount zwykle przydziela mniej pamięci, podczas gdy GetMaxByteCount metoda zwykle wykonuje się szybciej.

W przypadku wykrywania błędów nieprawidłowa sekwencja powoduje, że ta metoda zgłasza ArgumentException wyjątek. Bez wykrywania błędów nieprawidłowe sekwencje są ignorowane i nie jest zgłaszany żaden wyjątek.

Dane do przekonwertowania, takie jak dane odczytywane ze strumienia, mogą być dostępne tylko w blokach sekwencyjnych. W tym przypadku lub jeśli ilość danych jest tak duża, że należy podzielić je na mniejsze bloki, użyć Decoder metody lub Encoder zwróconej odpowiednio przez GetDecoder metodę lub GetEncoder metodę.

Aby upewnić się, że zakodowane bajty są prawidłowo dekodowane, gdy są zapisywane jako plik lub jako strumień, można prefiks strumienia zakodowanych bajtów z prefiksem. Wstawianie prezbiory na początku strumienia bajtów (na przykład na początku serii bajtów do zapisania w pliku) jest odpowiedzialnością dewelopera. Metoda GetBytes nie poprzedza prefiksu początku sekwencji zakodowanych bajtów.

Zobacz też

• GetEncoder()
• GetByteCount(Char[], Int32, Int32)
• GetMaxByteCount(Int32)

GetBytes(Char[], Int32, Int32, Byte[], Int32)

Źródło:

UTF8Encoding.cs

Koduje zestaw znaków z określonej tablicy znaków do określonej tablicy bajtów.

public:
 override int GetBytes(cli::array <char> ^ chars, int charIndex, int charCount, cli::array <System::Byte> ^ bytes, int byteIndex);

public override int GetBytes (char[] chars, int charIndex, int charCount, byte[] bytes, int byteIndex);

override this.GetBytes : char[] * int * int * byte[] * int -> int

Public Overrides Function GetBytes (chars As Char(), charIndex As Integer, charCount As Integer, bytes As Byte(), byteIndex As Integer) As Integer

Parametry

chars

Char[]

Tablica znaków zawierająca zestaw znaków do kodowania.

charIndex

Int32

Indeks pierwszego znaku do zakodowania.

charCount

Int32

Liczba znaków do zakodowania.

bytes

Byte[]

Tablica bajtów zawierająca wynikową sekwencję bajtów.

byteIndex

Int32

Indeks, na którym należy rozpocząć pisanie wynikowej sekwencji bajtów.

Zwraca

Int32

Rzeczywista liczba bajtów zapisanych w pliku bytes.

Wyjątki

ArgumentNullException

chars to null.

-lub-

bytes to null.

ArgumentOutOfRangeException

charIndex lub charCountbyteIndex jest mniejsza niż zero.

-lub-

charIndex i charCount nie oznaczają prawidłowego zakresu w elemecie chars.

-lub-

byteIndex nie jest prawidłowym indeksem w pliku bytes.

ArgumentException

Wykrywanie błędów jest włączone i chars zawiera nieprawidłową sekwencję znaków.

-lub-

bytes nie ma wystarczającej pojemności od byteIndex do końca tablicy, aby pomieścić wynikowe bajty.

EncoderFallbackException

Wystąpił powrót (aby uzyskać więcej informacji, zobacz Kodowanie znaków na platformie .NET)

-I-

EncoderFallback parametr jest ustawiony na EncoderExceptionFallbackwartość .

Przykłady

W poniższym przykładzie użyto GetBytes metody w celu zakodowania zakresu znaków z ciągu i zapisania zakodowanych bajtów w zakresie elementów w tablicy bajtów.

using namespace System;
using namespace System::Text;
using namespace System::Collections;
int main()
{
   array<Byte>^bytes;
   String^ chars = "UTF8 Encoding Example";
   UTF8Encoding^ utf8 = gcnew UTF8Encoding;
   int byteCount = utf8->GetByteCount( chars->ToCharArray(), 0, 13 );
   bytes = gcnew array<Byte>(byteCount);
   int bytesEncodedCount = utf8->GetBytes( chars, 0, 13, bytes, 0 );
   Console::WriteLine( "{0} bytes used to encode string.", bytesEncodedCount );
   Console::Write( "Encoded bytes: " );
   IEnumerator^ myEnum = bytes->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }

   Console::WriteLine();
}

using System;
using System.Text;

class UTF8EncodingExample {
    public static void Main() {
        Byte[] bytes;
        String chars = "UTF8 Encoding Example";
        
        UTF8Encoding utf8 = new UTF8Encoding();
        
        int byteCount = utf8.GetByteCount(chars.ToCharArray(), 0, 13);
        bytes = new Byte[byteCount];
        int bytesEncodedCount = utf8.GetBytes(chars, 0, 13, bytes, 0);
        
        Console.WriteLine(
            "{0} bytes used to encode string.", bytesEncodedCount
        );

        Console.Write("Encoded bytes: ");
        foreach (Byte b in bytes) {
            Console.Write("[{0}]", b);
        }
        Console.WriteLine();
    }
}

Imports System.Text

Class UTF8EncodingExample
    
    Public Shared Sub Main()
        Dim bytes() As Byte
        Dim chars As String = "UTF8 Encoding Example"
        
        Dim utf8 As New UTF8Encoding()
        
        Dim byteCount As Integer = utf8.GetByteCount(chars.ToCharArray(), 0, 13)
        bytes = New Byte(byteCount - 1) {}
        Dim bytesEncodedCount As Integer = utf8.GetBytes(chars, 0, 13, bytes, 0)
        
        Console.WriteLine("{0} bytes used to encode string.", bytesEncodedCount)
        
        Console.Write("Encoded bytes: ")
        Dim b As Byte
        For Each b In  bytes
            Console.Write("[{0}]", b)
        Next b
        Console.WriteLine()
    End Sub
End Class

Uwagi

Aby obliczyć dokładny rozmiar tablicy wymagany przez GetBytes program do przechowywania bajtów wynikowych, należy wywołać metodę GetByteCount . Aby obliczyć maksymalny rozmiar tablicy, należy wywołać metodę GetMaxByteCount . Metoda GetByteCount zwykle przydziela mniej pamięci, podczas gdy GetMaxByteCount metoda zwykle wykonuje się szybciej.

W przypadku wykrywania błędów nieprawidłowa sekwencja powoduje, że ta metoda zgłasza ArgumentException wyjątek. Bez wykrywania błędów nieprawidłowe sekwencje są ignorowane i nie jest zgłaszany żaden wyjątek.

Dane do przekonwertowania, takie jak dane odczytywane ze strumienia, mogą być dostępne tylko w blokach sekwencyjnych. W tym przypadku lub jeśli ilość danych jest tak duża, że musi być podzielona na mniejsze bloki, użyj Decoder metody lub Encoder dostarczonej GetDecoder odpowiednio przez metodę lub GetEncoder metodę.

Aby upewnić się, że zakodowane bajty są prawidłowo dekodowane, gdy są zapisywane jako plik lub jako strumień, można prefiks strumienia zakodowanych bajtów z prefiksem. Wstawianie prezbiory na początku strumienia bajtów (na przykład na początku serii bajtów do zapisania w pliku) jest odpowiedzialnością dewelopera. Metoda GetBytes nie poprzedza prefiksu początku sekwencji zakodowanych bajtów.

Zobacz też

• GetEncoder()
• GetByteCount(Char[], Int32, Int32)
• GetMaxByteCount(Int32)

GetBytes(String, Int32, Int32, Byte[], Int32)

Źródło:

UTF8Encoding.cs

Koduje zestaw znaków z określonej String tablicy bajtów.

public:
 override int GetBytes(System::String ^ s, int charIndex, int charCount, cli::array <System::Byte> ^ bytes, int byteIndex);

public override int GetBytes (string s, int charIndex, int charCount, byte[] bytes, int byteIndex);

override this.GetBytes : string * int * int * byte[] * int -> int

Public Overrides Function GetBytes (s As String, charIndex As Integer, charCount As Integer, bytes As Byte(), byteIndex As Integer) As Integer

Parametry

s

String

Zawierający String zestaw znaków do zakodowania.

charIndex

Int32

Indeks pierwszego znaku do kodowania.

charCount

Int32

Liczba znaków do kodowania.

bytes

Byte[]

Tablica bajtów zawierająca wynikową sekwencję bajtów.

byteIndex

Int32

Indeks, na którym rozpocznie się pisanie wynikowej sekwencji bajtów.

Zwraca

Int32

Rzeczywista liczba bajtów zapisanych w bytespliku .

Wyjątki

ArgumentNullException

s to null.

-lub-

bytes to null.

ArgumentOutOfRangeException

charIndex lub charCountbyteIndex jest mniejsza niż zero.

-lub-

charIndex i charCount nie oznaczają prawidłowego zakresu w elemecie chars.

-lub-

byteIndex nie jest prawidłowym indeksem w pliku bytes.

ArgumentException

Wykrywanie błędów jest włączone i s zawiera nieprawidłową sekwencję znaków.

-lub-

bytes nie ma wystarczającej pojemności od byteIndex do końca tablicy, aby pomieścić wynikowe bajty.

EncoderFallbackException

Wystąpił rezerwowy (aby uzyskać więcej informacji, zobacz Kodowanie znaków na platformie .NET)

-I-

EncoderFallback jest ustawiona na EncoderExceptionFallbackwartość .

Przykłady

W poniższym przykładzie użyto GetBytes metody do zakodowania zakresu elementów z tablicy znaków Unicode i zapisania zakodowanych bajtów w zakresie elementów w tablicy bajtów.

using namespace System;
using namespace System::Text;
using namespace System::Collections;
int main()
{
   array<Byte>^bytes;
   
   // Unicode characters.
   
   // Pi
   // Sigma
   array<Char>^chars = {L'\u03a0',L'\u03a3',L'\u03a6',L'\u03a9'};
   UTF8Encoding^ utf8 = gcnew UTF8Encoding;
   int byteCount = utf8->GetByteCount( chars, 1, 2 );
   bytes = gcnew array<Byte>(byteCount);
   int bytesEncodedCount = utf8->GetBytes( chars, 1, 2, bytes, 0 );
   Console::WriteLine( "{0} bytes used to encode characters.", bytesEncodedCount );
   Console::Write( "Encoded bytes: " );
   IEnumerator^ myEnum = bytes->GetEnumerator();
   while ( myEnum->MoveNext() )
   {
      Byte b = safe_cast<Byte>(myEnum->Current);
      Console::Write( "[{0}]", b );
   }

   Console::WriteLine();
}

using System;
using System.Text;

class UTF8EncodingExample {
    public static void Main() {
        Byte[] bytes;
        // Unicode characters.
        Char[] chars = new Char[] {
            '\u0023', // #
            '\u0025', // %
            '\u03a0', // Pi
            '\u03a3'  // Sigma
        };
        
        UTF8Encoding utf8 = new UTF8Encoding();
        
        int byteCount = utf8.GetByteCount(chars, 1, 2);
        bytes = new Byte[byteCount];
        int bytesEncodedCount = utf8.GetBytes(chars, 1, 2, bytes, 0);
        
        Console.WriteLine(
            "{0} bytes used to encode characters.", bytesEncodedCount
        );

        Console.Write("Encoded bytes: ");
        foreach (Byte b in bytes) {
            Console.Write("[{0}]", b);
        }
        Console.WriteLine();
    }
}

Imports System.Text
Imports Microsoft.VisualBasic.Strings

Class UTF8EncodingExample
    
    Public Shared Sub Main()
        Dim bytes() As Byte
        ' Unicode characters.
        ' ChrW(35)  = #
        ' ChrW(37)  = %
        ' ChrW(928) = Pi
        ' ChrW(931) = Sigma
        Dim chars() As Char = {ChrW(35), ChrW(37), ChrW(928), ChrW(931)}
        
        Dim utf8 As New UTF8Encoding()
        
        Dim byteCount As Integer = utf8.GetByteCount(chars, 1, 2)
        bytes = New Byte(byteCount - 1) {}
        Dim bytesEncodedCount As Integer = utf8.GetBytes(chars, 1, 2, bytes, 0)
        
        Console.WriteLine("{0} bytes used to encode characters.", bytesEncodedCount)
        
        Console.Write("Encoded bytes: ")
        Dim b As Byte
        For Each b In  bytes
            Console.Write("[{0}]", b)
        Next b
        Console.WriteLine()
    End Sub
End Class

Uwagi

Aby obliczyć dokładny rozmiar tablicy wymagany przez GetBytes do przechowywania wynikowych bajtów, należy wywołać metodę GetByteCount . Aby obliczyć maksymalny rozmiar tablicy, należy wywołać metodę GetMaxByteCount . Metoda GetByteCount zazwyczaj przydziela mniej pamięci, podczas gdy GetMaxByteCount metoda zwykle wykonuje się szybciej.

W przypadku wykrywania błędów nieprawidłowa sekwencja powoduje, że ta metoda zgłasza ArgumentException wyjątek. Bez wykrywania błędów nieprawidłowe sekwencje są ignorowane i nie jest zgłaszany żaden wyjątek.

Dane, które mają być konwertowane, takie jak dane odczytywane ze strumienia, mogą być dostępne tylko w blokach sekwencyjnych. W takim przypadku lub jeśli ilość danych jest tak duża, że musi być podzielona na mniejsze bloki, użyj Decoder wartości lub Encoder dostarczonej GetDecoder odpowiednio przez metodę lub GetEncoder metodę.

Aby upewnić się, że zakodowane bajty są prawidłowo dekodowane po zapisaniu ich jako pliku lub strumieniu, można prefiksować strumień zakodowanych bajtów z preambułą. Wstawienie preambuły na początku strumienia bajtów (na przykład na początku serii bajtów do zapisu w pliku) jest odpowiedzialnością dewelopera. Metoda GetBytes nie poprzedza preambuły początku sekwencji zakodowanych bajtów.

Zobacz też

• GetEncoder()
• GetByteCount(Char[], Int32, Int32)
• GetMaxByteCount(Int32)