Information
Switch
Switch
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Encoding::GetCharCount Method (array<Byte>^)

.NET Framework (current version)
 

When overridden in a derived class, calculates the number of characters produced by decoding all the bytes in the specified byte array.

Namespace:   System.Text
Assembly:  mscorlib (in mscorlib.dll)

C#
C++
F#
VB
Copy 
public:
virtual int GetCharCount(
	array<unsigned char>^ bytes
)

Parameters

bytes
Type: array<System::Byte>^

The byte array containing the sequence of bytes to decode.

Return Value

Type: System::Int32

The number of characters produced by decoding the specified sequence of bytes.

Exception Condition
ArgumentNullException

bytes is null.

DecoderFallbackException

A fallback occurred (see Character Encoding in the .NET Framework for complete explanation)

-and-

DecoderFallback is set to DecoderExceptionFallback.

To calculate the exact array size required by GetChars(array<Byte>^) to store the resulting characters, you should use the GetCharCount(array<Byte>^) method. To calculate the maximum array size, you should use the GetMaxCharCount(Int32) method. The GetCharCount(array<Byte>^) method generally allows allocation of less memory, while the GetMaxCharCount method generally executes faster.

The GetCharCount(array<Byte>^) method determines how many characters result in decoding a sequence of bytes, and the GetChars(array<Byte>^) method performs the actual decoding. The Encoding::GetChars method expects discrete conversions, in contrast to the Decoder::GetChars method, which handles multiple passes on a single input stream.

Several versions of GetCharCount and GetChars are supported. The following are some programming considerations for use of these methods:

  • Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls.

  • If your app handles string outputs, you should use the GetString method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting String type is to be preferred.

  • The byte version of GetChars(Byte*, Int32, Char*, Int32) allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required.

  • If your app must convert a large amount of data, it should reuse the output buffer. In this case, the GetChars(array<Byte>^, Int32, Int32, array<Char>^, Int32) version that supports output character buffers is the best choice.

  • Consider using the Decoder::Convert method instead of GetCharCount. The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice.

The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters.

C#
C++
VB
Copy 
using namespace System;
using namespace System::Text;
void PrintCountsAndChars( array<Byte>^bytes, Encoding^ enc );
int main()
{

   // Create two instances of UTF32Encoding: one with little-endian byte order and one with big-endian byte order.
   Encoding^ u32LE = Encoding::GetEncoding( "utf-32" );
   Encoding^ u32BE = Encoding::GetEncoding( "utf-32BE" );

   // Use a string containing the following characters:
   //    Latin Small Letter Z (U+007A)
   //    Latin Small Letter A (U+0061)
   //    Combining Breve (U+0306)
   //    Latin Small Letter AE With Acute (U+01FD)
   //    Greek Small Letter Beta (U+03B2)
   String^ myStr = "za\u0306\u01FD\u03B2";

   // Encode the string using the big-endian byte order.
   array<Byte>^barrBE = gcnew array<Byte>(u32BE->GetByteCount( myStr ));
   u32BE->GetBytes( myStr, 0, myStr->Length, barrBE, 0 );

   // Encode the string using the little-endian byte order.
   array<Byte>^barrLE = gcnew array<Byte>(u32LE->GetByteCount( myStr ));
   u32LE->GetBytes( myStr, 0, myStr->Length, barrLE, 0 );

   // Get the char counts, and decode the byte arrays.
   Console::Write( "BE array with BE encoding : " );
   PrintCountsAndChars( barrBE, u32BE );
   Console::Write( "LE array with LE encoding : " );
   PrintCountsAndChars( barrLE, u32LE );
}

void PrintCountsAndChars( array<Byte>^bytes, Encoding^ enc )
{

   // Display the name of the encoding used.
   Console::Write( "{0,-25} :", enc );

   // Display the exact character count.
   int iCC = enc->GetCharCount( bytes );
   Console::Write( " {0,-3}", iCC );

   // Display the maximum character count.
   int iMCC = enc->GetMaxCharCount( bytes->Length );
   Console::Write( " {0,-3} :", iMCC );

   // Decode the bytes and display the characters.
   array<Char>^chars = enc->GetChars( bytes );
   Console::WriteLine( chars );
}

/* 
This code produces the following output.  The question marks take the place of characters that cannot be displayed at the console.

BE array with BE encoding : System.Text.UTF32Encoding : 5   12  :za??�
LE array with LE encoding : System.Text.UTF32Encoding : 5   12  :za??�

*/

Universal Windows Platform
Available since 8
.NET Framework
Available since 1.1
Portable Class Library
Supported in: portable .NET platforms
Silverlight
Available since 2.0
Windows Phone Silverlight
Available since 7.0
Windows Phone
Available since 8.1
Return to top
Show: