This documentation is archived and is not being maintained.

Decoder.GetChars Method

When overridden in a derived class, decodes a specified range of elements from a byte array and stores them in a specified range of a Unicode character array.

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

Parameters

bytes
A byte array to decode.
byteIndex
The index of the first element in bytes to decode.
byteCount
The number of elements to decode.
chars
The character array where the decoded results are stored.
charIndex
The index of the first element in chars to store the decoded results.

Return Value

The number of characters decoded into chars.

Exceptions

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

-or-

byteIndex plus byteCount is greater than the length of bytes.

-or-

charIndex is greater than the length of chars.

Remarks

Use GetCharCount to calculate the array size required by the GetChars method to store decoded bytes.

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

Example

[Visual Basic, C#, C++] The following example demonstrates how to decode a range of elements from a byte array and store them in a Unicode character array. The GetCharCount method is used to calculate the number of characters needed to store the decoded elements in the array bytes. The GetChars method decodes the specified elements in bytes and stores them in the new character array chars.

[Visual Basic] 
Imports System
Imports System.Text

Class UnicodeEncodingExample
    
    Public Shared Sub Main()
        Dim chars() As Char
        Dim bytes() As Byte = { _
            85, 0, 110, 0, 105, 0, 99, 0, 111, 0, 100, 0, 101, 0 _
        }
        
        Dim uniDecoder As Decoder = Encoding.Unicode.GetDecoder()
        
        Dim charCount As Integer = uniDecoder.GetCharCount(bytes, 0, bytes.Length)
        chars = New Char(charCount - 1) {}
        Dim charsDecodedCount As Integer = _
            uniDecoder.GetChars(bytes, 0, bytes.Length, 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

[C#] 
using System;
using System.Text;

class UnicodeEncodingExample {
    public static void Main() {
        Char[] chars;
        Byte[] bytes = new Byte[] {
            85, 0, 110, 0, 105, 0, 99, 0, 111, 0, 100, 0, 101, 0
        };

        Decoder uniDecoder = Encoding.Unicode.GetDecoder();

        int charCount = uniDecoder.GetCharCount(bytes, 0, bytes.Length);
        chars = new Char[charCount];
        int charsDecodedCount = uniDecoder.GetChars(bytes, 0, bytes.Length, 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();
    }
}

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

int main()
{
   Char chars[];
   Byte bytes[] = 
   {
      85, 0, 110, 0, 105, 0, 99, 0, 111, 0, 100, 0, 101, 0
   };

   Decoder * uniDecoder = Encoding::Unicode -> GetDecoder();

   int charCount = uniDecoder -> GetCharCount(bytes, 0, bytes -> Length);
   chars = new Char[charCount];
   int charsDecodedCount = uniDecoder -> GetChars(bytes, 0, bytes -> Length, chars, 0);

   Console::WriteLine(S"{0} characters used to decode bytes.", __box(charsDecodedCount));

   Console::Write(S"Decoded chars: ");
   IEnumerator* myEnum = chars->GetEnumerator();
   while (myEnum->MoveNext())
   {
      Char* c = __try_cast<Char*>(myEnum->Current);
      Console::Write(S"[{0}]", c -> ToString());
   }
   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

Decoder Class | Decoder Members | System.Text Namespace | GetCharCount | GetChars

Show: