UnicodeEncoding.GetBytes Метод

Определение

Кодирует набор символов в последовательность байтов.Encodes a set of characters into a sequence of bytes.

Перегрузки

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

Кодирует набор символов из заданного массива символов в указанный массив байтов.Encodes a set of characters from the specified character array into the specified byte array.

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

Кодирует набор символов из заданного объекта String в указанный массив байтов.Encodes a set of characters from the specified String into the specified byte array.

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

Кодирует набор символов, начало которого задается указателем символа, в последовательность байтов, которые сохраняются начиная с заданного указателя байта.Encodes a set of characters starting at the specified character pointer into a sequence of bytes that are stored starting at the specified byte pointer.

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

Кодирует набор символов из заданного массива символов в указанный массив байтов.Encodes a set of characters from the specified character array into the specified byte array.

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

Параметры

chars
Char[]

Массив символов, содержащий набор кодируемых символов.The character array containing the set of characters to encode.

charIndex
Int32

Индекс первого кодируемого символа.The index of the first character to encode.

charCount
Int32

Число кодируемых символов.The number of characters to encode.

bytes
Byte[]

Массив байтов, в который будет помещена результирующая последовательность байтов.The byte array to contain the resulting sequence of bytes.

byteIndex
Int32

Индекс, с которого начинается запись результирующей последовательности байтов.The index at which to start writing the resulting sequence of bytes.

Возвраты

Фактическое число байтов, записанных в bytes.The actual number of bytes written into bytes.

Исключения

chars имеет значение null (Nothing).chars is null (Nothing).

- или --or- bytes имеет значение null (Nothing).bytes is null (Nothing).

Значение параметра charIndex, charCount или byteIndex меньше нуля.charIndex or charCount or byteIndex is less than zero.

-или--or- ПараметрыcharIndex и charCount не указывают допустимый диапазон в chars.charIndex and charCount do not denote a valid range in chars.

- или --or- Значение параметра byteIndex не является допустимым индексом в bytes.byteIndex is not a valid index in bytes.

Обнаружение ошибок включено, и chars содержит недопустимую последовательность символов.Error detection is enabled, and chars contains an invalid sequence of characters.

- или --or- Недостаточно емкости bytes от byteIndex до конца массива для размещения полученных байтов.bytes does not have enough capacity from byteIndex to the end of the array to accommodate the resulting bytes.

Произошла отработка отказа (см. полное объяснение в статье Кодировка символов в .NET Framework)A fallback occurred (see Character Encoding in the .NET Framework for fuller explanation) - и --and- Параметру EncoderFallback задается значение EncoderExceptionFallback.EncoderFallback is set to EncoderExceptionFallback.

Примеры

В следующем примере показано, как использовать GetBytes метод для кодирования диапазона символов String из и хранения закодированных байтов в диапазоне элементов в массиве байтов.The following example demonstrates how to use the GetBytes method to encode a range of characters from a String and store the encoded bytes in a range of elements in a byte array.

using namespace System;
using namespace System::Text;
using namespace System::Collections;
int main()
{
   array<Byte>^bytes;
   String^ chars = "Unicode Encoding Example";
   UnicodeEncoding^ Unicode = gcnew UnicodeEncoding;
   int byteCount = Unicode->GetByteCount( chars->ToCharArray(), 8, 8 );
   bytes = gcnew array<Byte>(byteCount);
   int bytesEncodedCount = Unicode->GetBytes( chars, 8, 8, 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 UnicodeEncodingExample {
    public static void Main() {
        Byte[] bytes;
        String chars = "Unicode Encoding Example";
        
        UnicodeEncoding Unicode = new UnicodeEncoding();
        
        int byteCount = Unicode.GetByteCount(chars.ToCharArray(), 8, 8);
        bytes = new Byte[byteCount];
        int bytesEncodedCount = Unicode.GetBytes(chars, 8, 8, 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 UnicodeEncodingExample
    
    Public Shared Sub Main()
        Dim bytes() As Byte
        Dim chars As String = "Unicode Encoding Example"
        
        Dim uni As New UnicodeEncoding()
        
        Dim byteCount As Integer = uni.GetByteCount(chars.ToCharArray(), 8, 8)
        bytes = New Byte(byteCount - 1) {}
        Dim bytesEncodedCount As Integer = uni.GetBytes(chars, 8, 8, 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

Комментарии

Чтобы вычислить точный размер массива, GetBytes необходимый для хранения результирующих байтов, GetByteCount вызовите метод.To calculate the exact array size required by GetBytes to store the resulting bytes, you call the GetByteCount method. Чтобы вычислить максимальный размер массива, вызовите GetMaxByteCount метод.To calculate the maximum array size, you call the GetMaxByteCount method. Метод обычно выделяет меньше памяти, в GetMaxByteCount то время как метод обычно выполняется быстрее. GetByteCountThe GetByteCount method generally allocates less memory, while the GetMaxByteCount method generally executes faster.

При обнаружении ошибок недействительная последовательность приводит к тому, что ArgumentExceptionэтот метод выдает исключение.With error detection, an invalid sequence causes this method to throw a ArgumentException. Без обнаружения ошибок недопустимые последовательности пропускаются, и исключение не создается.Without error detection, invalid sequences are ignored, and no exception is thrown.

Данные для преобразования, например данные, считываемые из потока, могут быть доступны только в последовательных блоках.Data to be converted, such as data read from a stream, might be available only in sequential blocks. В этом случае, или если объем данных настолько велик, что необходимо разделить Decoder на меньшие блоки, приложение должно использовать Encoder или, предоставляемые GetDecoder методом или GetEncoder методом соответственно.In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the Decoder or the Encoder provided by the GetDecoder method or the GetEncoder method, respectively.

Важно!

Чтобы обеспечить правильную декодирование закодированных байтов при сохранении их в виде файла или потока, можно добавить префикс потока закодированных байтов в преамбулу.To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. При вставке преамбулы в начало потока байтов (например, в начале последовательности байтов для занесения в файл) лежит ответственность за разработчика.Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. GetBytes Метод не добавляет преамбулу к началу последовательности закодированных байтов.The GetBytes method does not prepend a preamble to the beginning of a sequence of encoded bytes.

Дополнительно

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

Кодирует набор символов из заданного объекта String в указанный массив байтов.Encodes a set of characters from the specified String into the specified byte array.

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

Параметры

s
String

Строка, содержащая набор символов для кодирования.The string containing the set of characters to encode.

charIndex
Int32

Индекс первого кодируемого символа.The index of the first character to encode.

charCount
Int32

Число кодируемых символов.The number of characters to encode.

bytes
Byte[]

Массив байтов, в который будет помещена результирующая последовательность байтов.The byte array to contain the resulting sequence of bytes.

byteIndex
Int32

Индекс, с которого начинается запись результирующей последовательности байтов.The index at which to start writing the resulting sequence of bytes.

Возвраты

Фактическое число байтов, записанных в bytes.The actual number of bytes written into bytes.

Исключения

Свойство s имеет значение null.s is null.

-или--or- bytes имеет значение null (Nothing).bytes is null (Nothing).

Значение параметра charIndex, charCount или byteIndex меньше нуля.charIndex or charCount or byteIndex is less than zero.

- или --or- ПараметрыcharIndex и charCount не указывают допустимый диапазон в chars.charIndex and charCount do not denote a valid range in chars.

-или--or- Значение параметра byteIndex не является допустимым индексом в bytes.byteIndex is not a valid index in bytes.

Обнаружение ошибок включено, и s содержит недопустимую последовательность символов.Error detection is enabled, and s contains an invalid sequence of characters.

- или --or- Недостаточно емкости bytes от byteIndex до конца массива для размещения полученных байтов.bytes does not have enough capacity from byteIndex to the end of the array to accommodate the resulting bytes.

Произошла отработка отказа (см. полное объяснение в статье Кодировка символов в .NET Framework)A fallback occurred (see Character Encoding in the .NET Framework for fuller explanation) - и --and- Параметру EncoderFallback задается значение EncoderExceptionFallback.EncoderFallback is set to EncoderExceptionFallback.

Примеры

В следующем примере показано, как кодировать диапазон элементов из массива символов Юникода и хранить закодированные байты в диапазоне элементов в массиве байтов.The following example demonstrates how to encode a range of elements from a Unicode character array and store the encoded bytes in a range of elements in a byte array.

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'};
   UnicodeEncoding^ Unicode = gcnew UnicodeEncoding;
   int byteCount = Unicode->GetByteCount( chars, 1, 2 );
   bytes = gcnew array<Byte>(byteCount);
   int bytesEncodedCount = Unicode->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 UnicodeEncodingExample {
    public static void Main() {
        Byte[] bytes;
        // Unicode characters.
        Char[] chars = new Char[] {
            '\u0023', // #
            '\u0025', // %
            '\u03a0', // Pi
            '\u03a3'  // Sigma
        };
        
        UnicodeEncoding Unicode = new UnicodeEncoding();
        
        int byteCount = Unicode.GetByteCount(chars, 1, 2);
        bytes = new Byte[byteCount];
        int bytesEncodedCount = Unicode.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 UnicodeEncodingExample
    
    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 uni As New UnicodeEncoding()
        
        Dim byteCount As Integer = uni.GetByteCount(chars, 1, 2)
        bytes = New Byte(byteCount - 1) {}
        Dim bytesEncodedCount As Integer = uni.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

Комментарии

Чтобы вычислить точный размер массива, GetBytes необходимый для хранения результирующих байтов, GetByteCount вызовите метод.To calculate the exact array size required by GetBytes to store the resulting bytes, you call the GetByteCount method. Чтобы вычислить максимальный размер массива, вызовите GetMaxByteCount метод.To calculate the maximum array size, you call the GetMaxByteCount method. Метод обычно выделяет меньше памяти, в GetMaxByteCount то время как метод обычно выполняется быстрее. GetByteCountThe GetByteCount method generally allocates less memory, while the GetMaxByteCount method generally executes faster.

При обнаружении ошибок недействительная последовательность приводит к тому, что ArgumentExceptionэтот метод выдает исключение.With error detection, an invalid sequence causes this method to throw a ArgumentException. Без обнаружения ошибок недопустимые последовательности пропускаются, и исключение не создается.Without error detection, invalid sequences are ignored, and no exception is thrown.

Данные для преобразования, например данные, считываемые из потока, могут быть доступны только в последовательных блоках.Data to be converted, such as data read from a stream, might be available only in sequential blocks. В этом случае, или если объем данных настолько велик, что необходимо разделить Decoder на меньшие блоки, приложение должно использовать Encoder или, предоставляемые GetDecoder методом или GetEncoder методом соответственно.In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the Decoder or the Encoder provided by the GetDecoder method or the GetEncoder method, respectively.

Важно!

Чтобы обеспечить правильную декодирование закодированных байтов при сохранении их в виде файла или потока, можно добавить префикс потока закодированных байтов в преамбулу.To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. При вставке преамбулы в начало потока байтов (например, в начале последовательности байтов для занесения в файл) лежит ответственность за разработчика.Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. GetBytes Метод не добавляет преамбулу к началу последовательности закодированных байтов.The GetBytes method does not prepend a preamble to the beginning of a sequence of encoded bytes.

Дополнительно

GetBytes(String)

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()

Параметры

s
String

Возвраты

Byte[]

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

Важно!

Этот API несовместим с CLS.

Кодирует набор символов, начало которого задается указателем символа, в последовательность байтов, которые сохраняются начиная с заданного указателя байта.Encodes a set of characters starting at the specified character pointer into a sequence of bytes that are stored starting at the specified byte pointer.

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

Параметры

chars
Char*

Указатель на первый кодируемый символ.A pointer to the first character to encode.

charCount
Int32

Число кодируемых символов.The number of characters to encode.

bytes
Byte*

Указатель на положение, с которого начинается запись результирующей последовательности байтов.A pointer to the location at which to start writing the resulting sequence of bytes.

byteCount
Int32

Максимальное число байтов для записи.The maximum number of bytes to write.

Возвраты

Фактическое число байтов, записанных в местоположение, которое задано параметром bytes.The actual number of bytes written at the location indicated by the bytes parameter.

Атрибуты

Исключения

chars имеет значение null (Nothing).chars is null (Nothing).

-или--or- bytes имеет значение null (Nothing).bytes is null (Nothing).

Значение параметра charCount или byteCount меньше нуля.charCount or byteCount is less than zero.

Обнаружение ошибок включено, и chars содержит недопустимую последовательность символов.Error detection is enabled, and chars contains an invalid sequence of characters.

- или --or- byteCount меньше результирующего числа байтов.byteCount is less than the resulting number of bytes.

Произошла отработка отказа (см. полное объяснение в статье Кодировка символов в .NET Framework)A fallback occurred (see Character Encoding in the .NET Framework for fuller explanation) - и --and- Параметру EncoderFallback задается значение EncoderExceptionFallback.EncoderFallback is set to EncoderExceptionFallback.

Комментарии

Чтобы вычислить точный размер массива GetBytes , для которого требуется сохранить полученные байты, GetByteCount вызовите метод.To calculate the exact array size that GetBytes requires to store the resulting bytes, you call the GetByteCount method. Чтобы вычислить максимальный размер массива, вызовите GetMaxByteCount метод.To calculate the maximum array size, you call the GetMaxByteCount method. Метод обычно выделяет меньше памяти, в GetMaxByteCount то время как метод обычно выполняется быстрее. GetByteCountThe GetByteCount method generally allocates less memory, while the GetMaxByteCount method generally executes faster.

При обнаружении ошибок недействительная последовательность приводит к тому, что ArgumentExceptionэтот метод выдает исключение.With error detection, an invalid sequence causes this method to throw a ArgumentException. Без обнаружения ошибок недопустимые последовательности пропускаются, и исключение не создается.Without error detection, invalid sequences are ignored, and no exception is thrown.

Данные для преобразования, например данные, считываемые из потока, могут быть доступны только в последовательных блоках.Data to be converted, such as data read from a stream, might be available only in sequential blocks. В этом случае, или если объем данных настолько велик, что необходимо разделить Decoder на меньшие блоки, приложение должно использовать Encoder объект или, GetEncoder предоставленный GetDecoder методом или, соответственно.In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the Decoder or the Encoder object provided by the GetDecoder or the GetEncoder method, respectively.

Важно!

Чтобы обеспечить правильную декодирование закодированных байтов при сохранении их в виде файла или потока, можно добавить префикс потока закодированных байтов в преамбулу.To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. При вставке преамбулы в начало потока байтов (например, в начале последовательности байтов для занесения в файл) лежит ответственность за разработчика.Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. GetBytes Метод не добавляет преамбулу к началу последовательности закодированных байтов.The GetBytes method does not prepend a preamble to the beginning of a sequence of encoded bytes.

Безопасность

SecurityCriticalAttribute
Требуется полное доверие для немедленного вызывающего объекта.Requires full trust for the immediate caller. Этот член не может использоваться частично доверенным или прозрачным кодом.This member cannot be used by partially trusted or transparent code.

Дополнительно

Применяется к