This documentation is archived and is not being maintained.

Encoder.GetBytes Method

When overridden in a derived class, encodes a specified range of characters in a character array and stores them in a specified range of a byte array.

[Visual Basic]
Public MustOverride Function GetBytes( _
   ByVal chars() As Char, _
   ByVal charIndex As Integer, _
   ByVal charCount As Integer, _
   ByVal bytes() As Byte, _
   ByVal byteIndex As Integer, _
   ByVal flush As Boolean _
) As Integer
[C#]
public abstract int GetBytes(
 char[] chars,
 int charIndex,
 int charCount,
 byte[] bytes,
 int byteIndex,
 bool flush
);
[C++]
public: virtual int GetBytes(
 __wchar_t chars __gc[],
 int charIndex,
 int charCount,
 unsigned char bytes __gc[],
 int byteIndex,
 bool flush
) = 0;
[JScript]
public abstract function GetBytes(
   chars : Char[],
 charIndex : int,
 charCount : int,
 bytes : Byte[],
 byteIndex : int,
 flush : Boolean
) : int;

Parameters

chars
The character array to encode.
charIndex
The index of the first character in chars to encode.
charCount
The number of characters to encode.
bytes
The byte array where the encoding is stored.
byteIndex
The index of the first element in bytes where the encoding is stored.
flush
true if this encoder can flush its state at the end of the conversion; otherwise, false. To ensure correct termination of a sequence of blocks of encoded bytes, the last call to GetBytes can specify a value of true for flush.

Return Value

The number of bytes encoded into bytes.

Exceptions

Exception Type Condition
ArgumentException bytes does not contain sufficient space to store the encoded characters.
ArgumentNullException chars or bytes is a null reference (Nothing in Visual Basic).
ArgumentOutOfRangeException charIndex, charCount, or byteIndex is less than zero.

-or-

charIndex plus charCount is greater than the length of chars.

-or-

byteIndex is greater than the length of bytes.

Remarks

Use GetByteCount to calculate the array size required by the GetBytes method to store encoded characters.

It is recommended that you always call GetByteCount before calling GetBytes because the GetBytes method might change the internal state information between blocks of bytes.

The flush parameter is useful for flushing a high-surrogate at the end of a stream that does not have a low-surrogate. For example, the Encoder created by UTF8Encoding.GetEncoder uses this parameter to determine whether to write out a dangling high-surrogate at the end of a character block.

Example

[Visual Basic, C#, C++] 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. The GetByteCount method is used to determine the size of the array required by GetBytes.

[Visual Basic] 
Imports System
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 'Main
End Class 'EncoderExample

[C#] 
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();
    }
}

[C++] 
#using <mscorlib.dll>
using namespace System;
using namespace System::Text;
using namespace System::Collections;

int main()
{
   Byte bytes[];
   // Unicode characters.
   Char chars[] = 
   {
      L'\u03a0', // Pi
      L'\u03a3', // Sigma
      L'\u03a6',
      L'\u03a9'
   };

   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(S"{0} bytes used to encode characters.", __box(bytesEncodedCount));

   Console::Write(S"Encoded bytes: ");
   IEnumerator* myEnum = bytes->GetEnumerator();
   while (myEnum->MoveNext())
   {
      Byte b = *__try_cast<Byte __gc*>(myEnum->Current);
      Console::Write(S"[{0}]", __box(b));
   }
   Console::WriteLine();
}

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework, Common Language Infrastructure (CLI) Standard

See Also

Encoder Class | Encoder Members | System.Text Namespace

Show: