Encoder.GetBytes Метод

Определение

При переопределении в производном классе кодирует набор символов в последовательность байтов.When overridden in a derived class, encodes a set of characters into a sequence of bytes.

Перегрузки

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

При переопределении в производном классе кодирует набор символов во входном диапазоне символов и любые символы во внутреннем буфере в последовательность байтов, которые сохраняются во входном диапазоне байтов.When overridden in a derived class, encodes a set of characters in the input characters span and any characters in the internal buffer into a sequence of bytes that are stored in the input byte span. Параметр указывает, следует ли очистить внутреннее состояние кодировщика после выполнения преобразования.A parameter indicates whether to clear the internal state of the encoder after the conversion.

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

При переопределении в производном классе кодирует набор символов, начало которого задается указателем символов, и все байты, расположенные во внутреннем буфере, в последовательность байтов, которые сохраняются, начиная с заданного указателя байтов.When overridden in a derived class, encodes a set of characters starting at the specified character pointer and any characters in the internal buffer into a sequence of bytes that are stored starting at the specified byte pointer. Параметр указывает, следует ли очистить внутреннее состояние кодировщика после выполнения преобразования.A parameter indicates whether to clear the internal state of the encoder after the conversion.

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

При переопределении в производном классе кодирует набор символов из заданного массива символов и все символы, расположенные во внутреннем буфере, в указанный массив байтов.When overridden in a derived class, encodes a set of characters from the specified character array and any characters in the internal buffer into the specified byte array. Параметр указывает, следует ли очистить внутреннее состояние кодировщика после выполнения преобразования.A parameter indicates whether to clear the internal state of the encoder after the conversion.

Комментарии

Помните, что объект Encoder сохраняет состояние между вызовами GetBytes.Remember that the Encoder object saves state between calls to GetBytes. Когда приложение завершает работу с потоком данных, оно должно установить параметр flush для true в последнем вызове GetBytes, чтобы убедиться в том, что сведения о состоянии сброшены и закодированные байты правильно завершены.When the application is done with a stream of data, it should set the flush parameter to true in the last call to GetBytes to make sure that the state information is flushed and that the encoded bytes are properly terminated. При использовании этого параметра кодировщик игнорирует недопустимые байты в конце блока данных, например несовпадающие суррогаты или неполные комбинированные последовательности, и очищает внутренний буфер.With this setting, the encoder ignores invalid bytes at the end of the data block, such as unmatched surrogates or incomplete combining sequences, and clears the internal buffer.

Чтобы вычислить точный размер буфера, который GetBytes требуется для хранения полученных символов, приложение должно использовать GetByteCount.To calculate the exact buffer size that GetBytes requires to store the resulting characters, the application should use GetByteCount.

Если GetBytes вызывается с параметром flush, для которого задано значение false, кодировщик сохраняет конечные байты в конце блока данных во внутреннем буфере и использует их в следующей операции кодирования.If GetBytes is called with flush set to false, the encoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next encoding operation. Приложение должно вызывать GetByteCount для блока данных непосредственно перед вызовом GetBytes в одном блоке, чтобы все замыкающие символы из предыдущего блока включались в вычисление.The application should call GetByteCount on a block of data immediately before calling GetBytes on the same block, so that any trailing characters from the previous block are included in the calculation.

Если в приложении нужно преобразовать множество сегментов входного потока, рассмотрите возможность использования метода Convert.If your application is to convert many segments of an input stream, consider using the Convert method. GetBytes выдаст исключение, если выходной буфер недостаточно велик, но Convert заполнит максимально возможное пространство и возвратит считанные символы и записанные байты.GetBytes will throw an exception if the output buffer isn't large enough, but Convert will fill as much space as possible and return the chars read and bytes written. Дополнительные комментарии также см. в Encoding.GetBytes разделе.Also see the Encoding.GetBytes topic for more comments.

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

При переопределении в производном классе кодирует набор символов во входном диапазоне символов и любые символы во внутреннем буфере в последовательность байтов, которые сохраняются во входном диапазоне байтов.When overridden in a derived class, encodes a set of characters in the input characters span and any characters in the internal buffer into a sequence of bytes that are stored in the input byte span. Параметр указывает, следует ли очистить внутреннее состояние кодировщика после выполнения преобразования.A parameter indicates whether to clear the internal state of the encoder after the conversion.

public:
 virtual int GetBytes(ReadOnlySpan<char> chars, Span<System::Byte> bytes, bool flush);
public virtual int GetBytes (ReadOnlySpan<char> chars, Span<byte> bytes, bool flush);
abstract member GetBytes : ReadOnlySpan<char> * Span<byte> * bool -> int
override this.GetBytes : ReadOnlySpan<char> * Span<byte> * bool -> int
Public Overridable Function GetBytes (chars As ReadOnlySpan(Of Char), bytes As Span(Of Byte), flush As Boolean) As Integer

Параметры

chars
ReadOnlySpan<Char>

Кодируемый диапазон символов.A character span to encode.

bytes
Span<Byte>

Диапазон байтов для записи результирующей последовательности байтов.A byte span to write the resulting sequence of bytes to.

flush
Boolean

Значение true соответствует очистке внутреннего состояния кодировщика после преобразования; в противоположном случае — значение false.true to clear the internal state of the encoder after the conversion; otherwise, false.

Возвращаемое значение

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

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

Важно!

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

При переопределении в производном классе кодирует набор символов, начало которого задается указателем символов, и все байты, расположенные во внутреннем буфере, в последовательность байтов, которые сохраняются, начиная с заданного указателя байтов.When overridden in a derived class, encodes a set of characters starting at the specified character pointer and any characters in the internal buffer into a sequence of bytes that are stored starting at the specified byte pointer. Параметр указывает, следует ли очистить внутреннее состояние кодировщика после выполнения преобразования.A parameter indicates whether to clear the internal state of the encoder after the conversion.

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

flush
Boolean

Значение true соответствует очистке внутреннего состояния кодировщика после преобразования; в противоположном случае — значение false.true to clear the internal state of the encoder after the conversion; otherwise, false.

Возвращаемое значение

Фактическое число байтов, записанных в местоположение, которое задано параметром 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.

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

Произошел откат (см. сведения о кодировке символов в .NET)A fallback occurred (for more information, see Character Encoding in .NET)

- и --and-

Параметру Fallback задается значение EncoderExceptionFallback.Fallback is set to EncoderExceptionFallback.

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

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

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

При переопределении в производном классе кодирует набор символов из заданного массива символов и все символы, расположенные во внутреннем буфере, в указанный массив байтов.When overridden in a derived class, encodes a set of characters from the specified character array and any characters in the internal buffer into the specified byte array. Параметр указывает, следует ли очистить внутреннее состояние кодировщика после выполнения преобразования.A parameter indicates whether to clear the internal state of the encoder after the conversion.

public:
 abstract int GetBytes(cli::array <char> ^ chars, int charIndex, int charCount, cli::array <System::Byte> ^ bytes, int byteIndex, bool flush);
public abstract int GetBytes (char[] chars, int charIndex, int charCount, byte[] bytes, int byteIndex, bool flush);
abstract member GetBytes : char[] * int * int * byte[] * int * bool -> int
Public MustOverride Function GetBytes (chars As Char(), charIndex As Integer, charCount As Integer, bytes As Byte(), byteIndex As Integer, flush As Boolean) 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.

flush
Boolean

Значение true соответствует очистке внутреннего состояния кодировщика после преобразования; в противоположном случае — значение false.true to clear the internal state of the encoder after the conversion; otherwise, false.

Возвращаемое значение

Фактическое число байтов, записанных в 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.

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

Произошел откат (см. сведения о кодировке символов в .NET)A fallback occurred (for more information, see Character Encoding in .NET)

- и --and-

Параметру Fallback задается значение EncoderExceptionFallback.Fallback is set to EncoderExceptionFallback.

Примеры

В следующем примере показано, как кодировать диапазон элементов из массива символов и сохранить закодированные байты в диапазоне элементов в массиве байтов.The following example demonstrates how to encode a range of elements from a character array and store the encoded bytes in a range of elements in a byte array. Метод GetByteCount используется для определения размера массива, требуемого для GetBytes.The GetByteCount method is used to determine the size of the array required by GetBytes.

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'};
   Encoder^ uniEncoder = Encoding::Unicode->GetEncoder();
   int byteCount = uniEncoder->GetByteCount( chars, 0, chars->Length, true );
   bytes = gcnew array<Byte>(byteCount);
   int bytesEncodedCount = uniEncoder->GetBytes( chars, 0, chars->Length, bytes, 0, true );
   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();
}

/* This code example produces the following output.

8 bytes used to encode characters.
Encoded bytes: [160][3][163][3][166][3][169][3]

*/

using System;
using System.Text;

class EncoderExample {
    public static void Main() {
        Byte[] bytes;
        // Unicode characters.
        Char[] chars = new Char[] {
            '\u0023', // #
            '\u0025', // %
            '\u03a0', // Pi
            '\u03a3'  // Sigma
        };
        
        Encoder uniEncoder = Encoding.Unicode.GetEncoder();
        
        int byteCount = uniEncoder.GetByteCount(chars, 0, chars.Length, true);
        bytes = new Byte[byteCount];
        int bytesEncodedCount = uniEncoder.GetBytes(chars, 0, chars.Length, bytes, 0, true);
        
        Console.WriteLine(
            "{0} bytes used to encode characters.", bytesEncodedCount
        );

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

/* This code example produces the following output.

8 bytes used to encode characters.
Encoded bytes: [35][0][37][0][160][3][163][3]

*/
Imports System.Text
Imports Microsoft.VisualBasic.Strings

Class EncoderExample
    
    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 uniEncoder As Encoder = Encoding.Unicode.GetEncoder()
        
        Dim byteCount As Integer = _
            uniEncoder.GetByteCount(chars, 0, chars.Length, True)
        bytes = New Byte(byteCount - 1) {}
        Dim bytesEncodedCount As Integer = _
            uniEncoder.GetBytes(chars, 0, chars.Length, bytes, 0, True)
        
        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

'This code example produces the following output.
'8 bytes used to encode characters.
'Encoded bytes: [35][0][37][0][160][3][163][3]
'

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