Encoding: GetCharCount

GetCharCount

When implemented in a derived class, calculates the number of characters produced by decoding a sequence of bytes from the specified byte array.

 Public Function GetCharCount(
	  ByRef Bytes ( ) As Byte,
	  Optional ByRef Index As Variant,
	  Optional ByRef Count As Variant ) As Long

Parameters

Bytes: [ByRef] Byte. The byte array containing the sequence of bytes to decode.
Index: [ByRef] Optional. Variant. The index of the first byte to decode.
Count: [ByRef] Optional. Variant. The number of bytes to decode.

Return Values

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

Remarks

To calculate the exact array size required by GetChars to store the resulting characters, the application should use GetCharCount. To calculate the maximum array size, the application should use GetMaxCharCount. The GetCharCount method generally allows allocation of less memory, while the GetMaxCharCount method generally executes faster.

The GetCharCount method determines how many characters result in decoding a sequence of bytes, and the GetChars method performs the actual decoding. The GetChars method expects discrete conversions, in contrast to the Decoder.GetChars method, which handles multiple passes on a single input stream.

Exceptions

Exception Condition

ArgumentNullException Bytes is null.

ArgumentOutOfRangeException Index is less than the lower-bound of Bytes.
-or-
Count is less than zero.

DecoderFallbackException A fallback occurred
-and-
DecoderFallback is set to DecoderExceptionFallback.

Exception	Condition
ArgumentNullException	Bytes is null.
ArgumentOutOfRangeException	Index is less than the lower-bound of Bytes. -or- Count is less than zero.
DecoderFallbackException	A fallback occurred -and- DecoderFallback is set to DecoderExceptionFallback.

Examples

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

Public Sub Main()
    Const Sigma As Integer = &H3A3
    Dim Chars() As Integer
    Dim Bytes() As Byte
    Dim ASCII   As New ASCIIEncoding
    Dim U8      As New UTF8Encoding
    
    Set Console.OutputEncoding = Encoding.UTF8
    
    Chars = NewChars("A", "Z", Sigma)
    Bytes = U8.GetBytes(Chars)
    
    PrintCountsAndChars Bytes, ASCII
    PrintCountsAndChars Bytes, U8
    
    Console.ReadKey
End Sub

Private Sub PrintCountsAndChars(ByRef Bytes() As Byte, ByVal Enc As Encoding)
    Console.WriteValue "{0,-25} :", Enc
    Console.WriteValue " {0,-3}", Enc.GetCharCount(Bytes)
    Console.WriteValue " {0,-3} :", Enc.GetMaxByteCount(CorArray.Length(Bytes))
    Console.WriteLine Enc.GetString(Bytes)
End Sub

' The previous example code outputs the following.
'
'    CorLib.ASCIIEncoding      : 4   5   :AZ??
'    CorLib.UTF8Encoding       : 3   15  :AZΠ

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