UTF8Encoding.GetChars Метод
Определение
Важно!
Некоторые сведения относятся к предварительной версии продукта, в которую до выпуска могут быть внесены существенные изменения. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.
Декодирует последовательность байтов в набор символов.
Перегрузки
GetChars(ReadOnlySpan<Byte>, Span<Char>) |
Декодирует заданный диапазон байтов в заданный диапазон символов. |
GetChars(Byte*, Int32, Char*, Int32) |
Декодирует последовательность байтов, начало которой задается указателем байта, в набор символов, которые сохраняются начиная с заданного указателя символа. |
GetChars(Byte[], Int32, Int32, Char[], Int32) |
Декодирует последовательность байтов из заданного массива байтов в указанный массив символов. |
GetChars(ReadOnlySpan<Byte>, Span<Char>)
Декодирует заданный диапазон байтов в заданный диапазон символов.
public:
override int GetChars(ReadOnlySpan<System::Byte> bytes, Span<char> chars);
public override int GetChars (ReadOnlySpan<byte> bytes, Span<char> chars);
override this.GetChars : ReadOnlySpan<byte> * Span<char> -> int
Public Overrides Function GetChars (bytes As ReadOnlySpan(Of Byte), chars As Span(Of Char)) As Integer
Параметры
- bytes
- ReadOnlySpan<Byte>
Диапазон, содержащий байты для декодирования.
Возвращаемое значение
Фактическое число символов, записанных в chars
.
Комментарии
Чтобы вычислить точный размер, необходимый GetChars для хранения результирующего символа, вызовите GetCharCount метод. Чтобы вычислить максимальный размер, вызовите GetMaxCharCount метод. Этот GetCharCount метод обычно выделяет меньше памяти, а GetMaxCharCount метод обычно выполняется быстрее.
При обнаружении ошибок недопустимая последовательность приводит к возникновению ArgumentException исключения. Без обнаружения ошибок недопустимые последовательности игнорируются и исключение не возникает.
Если набор байтов, который требуется декодировать, включает метку порядка байтов (BOM) и диапазон байтов был возвращен методом типа, не поддерживающего BOM, символ U+FFFE
включается в диапазон символов, возвращаемых этим методом. Его можно удалить, вызвав String.TrimStart метод.
Данные для преобразования, такие как чтение данных из потока, могут быть доступны только в последовательных блоках. В этом случае или если объем данных настолько велик, что его необходимо разделить на меньшие блоки, используйте Decoder или Encoder объект, предоставленный методом или GetEncoder методом GetDecoder соответственно.
Применяется к
GetChars(Byte*, Int32, Char*, Int32)
Важно!
Этот API несовместим с CLS.
Декодирует последовательность байтов, начало которой задается указателем байта, в набор символов, которые сохраняются начиная с заданного указателя символа.
public:
override int GetChars(System::Byte* bytes, int byteCount, char* chars, int charCount);
[System.CLSCompliant(false)]
[System.Security.SecurityCritical]
public override int GetChars (byte* bytes, int byteCount, char* chars, int charCount);
[System.CLSCompliant(false)]
public override int GetChars (byte* bytes, int byteCount, char* chars, int charCount);
[System.CLSCompliant(false)]
[System.Runtime.InteropServices.ComVisible(false)]
public override int GetChars (byte* bytes, int byteCount, char* chars, int charCount);
[System.CLSCompliant(false)]
[System.Security.SecurityCritical]
[System.Runtime.InteropServices.ComVisible(false)]
public override int GetChars (byte* bytes, int byteCount, char* chars, int charCount);
[<System.CLSCompliant(false)>]
[<System.Security.SecurityCritical>]
override this.GetChars : nativeptr<byte> * int * nativeptr<char> * int -> int
[<System.CLSCompliant(false)>]
override this.GetChars : nativeptr<byte> * int * nativeptr<char> * int -> int
[<System.CLSCompliant(false)>]
[<System.Runtime.InteropServices.ComVisible(false)>]
override this.GetChars : nativeptr<byte> * int * nativeptr<char> * int -> int
[<System.CLSCompliant(false)>]
[<System.Security.SecurityCritical>]
[<System.Runtime.InteropServices.ComVisible(false)>]
override this.GetChars : nativeptr<byte> * int * nativeptr<char> * int -> int
Параметры
- bytes
- Byte*
Указатель на первый декодируемый байт.
- byteCount
- Int32
Число байтов для декодирования.
- chars
- Char*
Указатель на положение, с которого начинается запись результирующего набора символов.
- charCount
- Int32
Наибольшее количество символов для записи.
Возвращаемое значение
Фактическое число символов, записанных в местоположение, указанное с помощью параметра chars
.
- Атрибуты
Исключения
Значение параметра byteCount
или charCount
меньше нуля.
Обнаружение ошибок включено, и параметр bytes
содержит недопустимую последовательность байтов.
-или-
charCount
меньше результирующего числа символов.
Произошел откат (см. сведения о кодировке символов в .NET)
- и - Параметру DecoderFallback задается значение DecoderExceptionFallback.
Комментарии
Чтобы вычислить точный размер массива, необходимый GetChars для хранения результирующего символа, вызовите GetCharCount метод. Чтобы вычислить максимальный размер массива, вызовите GetMaxCharCount метод. Этот GetCharCount метод обычно выделяет меньше памяти, а GetMaxCharCount метод обычно выполняется быстрее.
При обнаружении ошибок недопустимая последовательность приводит к возникновению ArgumentException исключения. Без обнаружения ошибок недопустимые последовательности игнорируются и исключение не возникает.
Если диапазон декодированных байтов включает метку порядка байтов (BOM) и массив байтов был возвращен методом типа, не поддерживающего BOM, символ U+FFFE включается в массив символов, возвращаемый этим методом. Его можно удалить, вызвав String.TrimStart метод.
Данные для преобразования, такие как чтение данных из потока, могут быть доступны только в последовательных блоках. В этом случае или если объем данных настолько велик, что его необходимо разделить на меньшие блоки, используйте Decoder или Encoder объект, предоставленный методом или GetEncoder методом GetDecoder соответственно.
См. также раздел
- GetCharCount(Byte[], Int32, Int32)
- GetMaxCharCount(Int32)
- GetDecoder()
- GetString(Byte[], Int32, Int32)
Применяется к
GetChars(Byte[], Int32, Int32, Char[], Int32)
Декодирует последовательность байтов из заданного массива байтов в указанный массив символов.
public:
override int GetChars(cli::array <System::Byte> ^ bytes, int byteIndex, int byteCount, cli::array <char> ^ chars, int charIndex);
public override int GetChars (byte[] bytes, int byteIndex, int byteCount, char[] chars, int charIndex);
override this.GetChars : byte[] * int * int * char[] * int -> int
Public Overrides Function GetChars (bytes As Byte(), byteIndex As Integer, byteCount As Integer, chars As Char(), charIndex As Integer) As Integer
Параметры
- bytes
- Byte[]
Массив байтов, содержащий последовательность байтов, которую требуется декодировать.
- byteIndex
- Int32
Индекс первого декодируемого байта.
- byteCount
- Int32
Число байтов для декодирования.
- chars
- Char[]
Массив символов, в который будет помещен результирующий набор символов.
- charIndex
- Int32
Индекс, с которого начинается запись результирующего набора символов.
Возвращаемое значение
Фактическое число символов, записанных в chars
.
Исключения
Значение параметра byteIndex
, byteCount
или charIndex
меньше нуля.
-или-
Параметрыbyteindex
и byteCount
не указывают допустимый диапазон в bytes
.
-или-
Значение параметра charIndex
не является допустимым индексом в chars
.
Обнаружение ошибок включено, и параметр bytes
содержит недопустимую последовательность байтов.
-или-
Недостаточно емкости chars
от charIndex
до конца массива для размещения полученных символов.
Произошел откат (см. сведения о кодировке символов в .NET)
- и - Параметру DecoderFallback задается значение DecoderExceptionFallback.
Примеры
В следующем примере метод используется GetChars для декодирования диапазона элементов в массиве байтов и хранения результата в массиве символов.
using namespace System;
using namespace System::Text;
using namespace System::Collections;
int main()
{
array<Char>^chars;
array<Byte>^bytes = {85,84,70,56,32,69,110,99,111,100,105,110,103,32,69,120,97,109,112,108,101};
UTF8Encoding^ utf8 = gcnew UTF8Encoding;
int charCount = utf8->GetCharCount( bytes, 2, 13 );
chars = gcnew array<Char>(charCount);
int charsDecodedCount = utf8->GetChars( bytes, 2, 13, chars, 0 );
Console::WriteLine( "{0} characters used to decode bytes.", charsDecodedCount );
Console::Write( "Decoded chars: " );
IEnumerator^ myEnum = chars->GetEnumerator();
while ( myEnum->MoveNext() )
{
Char c = safe_cast<Char>(myEnum->Current);
Console::Write( "[{0}]", c.ToString() );
}
Console::WriteLine();
}
using System;
using System.Text;
class UTF8EncodingExample {
public static void Main() {
Char[] chars;
Byte[] bytes = new Byte[] {
85, 84, 70, 56, 32, 69, 110,
99, 111, 100, 105, 110, 103, 32,
69, 120, 97, 109, 112, 108, 101
};
UTF8Encoding utf8 = new UTF8Encoding();
int charCount = utf8.GetCharCount(bytes, 2, 13);
chars = new Char[charCount];
int charsDecodedCount = utf8.GetChars(bytes, 2, 13, chars, 0);
Console.WriteLine(
"{0} characters used to decode bytes.", charsDecodedCount
);
Console.Write("Decoded chars: ");
foreach (Char c in chars) {
Console.Write("[{0}]", c);
}
Console.WriteLine();
}
}
Imports System.Text
Class UTF8EncodingExample
Public Shared Sub Main()
Dim chars() As Char
Dim bytes() As Byte = { _
85, 84, 70, 56, 32, 69, 110, _
99, 111, 100, 105, 110, 103, 32, _
69, 120, 97, 109, 112, 108, 101 _
}
Dim utf8 As New UTF8Encoding()
Dim charCount As Integer = utf8.GetCharCount(bytes, 2, 13)
chars = New Char(charCount - 1) {}
Dim charsDecodedCount As Integer = utf8.GetChars(bytes, 2, 13, chars, 0)
Console.WriteLine("{0} characters used to decode bytes.", charsDecodedCount)
Console.Write("Decoded chars: ")
Dim c As Char
For Each c In chars
Console.Write("[{0}]", c)
Next c
Console.WriteLine()
End Sub
End Class
Комментарии
Чтобы вычислить точный размер массива, необходимый GetChars для хранения результирующего символа, вызовите GetCharCount метод. Чтобы вычислить максимальный размер массива, вызовите GetMaxCharCount метод. Этот GetCharCount метод обычно выделяет меньше памяти, а GetMaxCharCount метод обычно выполняется быстрее.
При обнаружении ошибок недопустимая последовательность приводит к возникновению ArgumentException исключения. Без обнаружения ошибок недопустимые последовательности игнорируются и исключение не возникает.
Если диапазон декодированных байтов включает метку порядка байтов (BOM) и массив байтов был возвращен методом типа, не поддерживающего BOM, символ U+FFFE включается в массив символов, возвращаемый этим методом. Его можно удалить, вызвав String.TrimStart метод.
Данные для преобразования, такие как чтение данных из потока, могут быть доступны только в последовательных блоках. В этом случае или если объем данных настолько велик, что его необходимо разделить на меньшие блоки, используйте Decoder метод или Encoder GetEncoder предоставленный методом GetDecoder соответственно.
См. также раздел
- GetCharCount(Byte[], Int32, Int32)
- GetMaxCharCount(Int32)
- GetDecoder()
- GetString(Byte[], Int32, Int32)