Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
GetCharCount Method (Byte[])

Encoding::GetCharCount Method (array<Byte>)

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
Assemblies:   System.Text.Encoding (in System.Text.Encoding.dll)
  mscorlib (in mscorlib.dll)

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.

ExceptionCondition
ArgumentNullException

bytes is nullptr.

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.

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??�

*/

.NET Framework

Supported in: 4.6, 4.5, 4, 3.5, 3.0, 2.0, 1.1

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

XNA Framework

Supported in: 3.0, 2.0, 1.0

.NET for Windows Phone apps

Supported in: Windows Phone 8.1, Windows Phone Silverlight 8.1, Windows Phone Silverlight 8

Portable Class Library

Supported in: Portable Class Library
Show:
© 2015 Microsoft