UTF8Encoding.GetBytes Metoda

  • Odwołanie

Definicja

Przestrzeń nazw:
System.Text
Zestaw:
mscorlib.dll
Zestaw:
System.Text.Encoding.Extensions.dll
Zestaw:
netstandard.dll

Koduje zestaw znaków w sekwencji bajtów.

Przeciążenia

GetBytes(String)

Koduje znaki w określonym String obiekcie do sekwencji bajtów.
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 znaków do sekwencji bajtów przechowywanych od określonego wskaźnika 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(String)

Koduje znaki w określonym String obiekcie do sekwencji bajtów.

public:
 override cli::array <System::Byte> ^ GetBytes(System::String ^ s);
public override byte[] GetBytes (string s);
override this.GetBytes : string -> byte[]
Public Overrides Function GetBytes (s As String) As Byte()

Parametry

s
String

Ciąg znaków do kodowania.

Zwraca

Byte[]

Tablica bajtów zawierająca zakodowane znaki w ciągu określonym przez parametr s.

Dotyczy

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

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 bytespliku .

Uwagi

Aby obliczyć dokładny rozmiar wymagany przez GetBytes magazyn wynikowych bajtów, należy wywołać metodę GetByteCount . Aby obliczyć maksymalny rozmiar, 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 zwróconej odpowiednio przez GetDecoder 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łą. Wstawianie preambuły na początku strumienia bajtowego (na przykład na początku serii bajtów do zapisu w pliku) jest obowiązkiem dewelopera. Metoda GetBytes nie poprzedza preambuły początku sekwencji zakodowanych bajtów.

Dotyczy

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

Ważne

Ten interfejs API nie jest zgodny ze specyfikacją CLS.

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

public:
 override int GetBytes(char* chars, int charCount, System::Byte* bytes, int byteCount);
[System.CLSCompliant(false)]
[System.Security.SecurityCritical]
public override int GetBytes (char* chars, int charCount, byte* bytes, int byteCount);
[System.CLSCompliant(false)]
public override int GetBytes (char* chars, int charCount, byte* bytes, int byteCount);
[System.CLSCompliant(false)]
[System.Runtime.InteropServices.ComVisible(false)]
public override int GetBytes (char* chars, int charCount, byte* bytes, int byteCount);
[System.CLSCompliant(false)]
[System.Security.SecurityCritical]
[System.Runtime.InteropServices.ComVisible(false)]
public override int GetBytes (char* chars, int charCount, byte* bytes, int byteCount);
[<System.CLSCompliant(false)>]
[<System.Security.SecurityCritical>]
override this.GetBytes : nativeptr<char> * int * nativeptr<byte> * int -> int
[<System.CLSCompliant(false)>]
override this.GetBytes : nativeptr<char> * int * nativeptr<byte> * int -> int
[<System.CLSCompliant(false)>]
[<System.Runtime.InteropServices.ComVisible(false)>]
override this.GetBytes : nativeptr<char> * int * nativeptr<byte> * int -> int
[<System.CLSCompliant(false)>]
[<System.Security.SecurityCritical>]
[<System.Runtime.InteropServices.ComVisible(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 kodowania.

bytes
Byte*

Wskaźnik do lokalizacji, w której chcesz 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 SecurityCriticalAttribute ComVisibleAttribute

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ł rezerwowy (aby uzyskać więcej informacji, zobacz Kodowanie znaków na platformie .NET) -and- EncoderFallback jest ustawiona na EncoderExceptionFallbackwartość .

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 zwróconej odpowiednio przez GetDecoder 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łą. Wstawianie preambuły na początku strumienia bajtowego (na przykład na początku serii bajtów do zapisu w pliku) jest obowiązkiem dewelopera. Metoda GetBytes nie poprzedza preambuły początku sekwencji zakodowanych bajtów.

Zobacz też

Dotyczy

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

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 charCount byteIndex 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 obowiązkiem dewelopera. Metoda GetBytes nie poprzedza prefiksu początku sekwencji zakodowanych bajtów.

Zobacz też

Dotyczy

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

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

Element String zawierający zestaw znaków do zakodowania.

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

s to null.

-lub- bytes to null.

ArgumentOutOfRangeException

charIndex lub charCount byteIndex 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ł 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 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 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 obowiązkiem dewelopera. Metoda GetBytes nie poprzedza prefiksu początku sekwencji zakodowanych bajtów.

Zobacz też

Dotyczy