Encoding: GetByteCount

Returns the number of bytes that would be produced from the set of characters using this encoding.

Parameters

Return Values

Remarks

To calculate the exact array size required by GetBytesEx to store the resulting bytes, the application should use GetByteCount. To calculate the maximum array size, the application should use GetMaxByteCount. The GetByteCount method generally allows allocation of less memory, while the GetMaxByteCount method generally executes faster.

If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the Decoder or the Encoder provided by the GetDecoder method or the GetEncoder method, respectively, of an implemented class.

The GetByteCount method determines how many bytes result in encoding a set of Unicode characters, and the GetBytesEx method performs the actual encoding. The Encoding.GetBytesEx method expects discrete conversions, in contrast to the Encoder.GetBytes method, which handles multiple conversions on a single input stream.

Exceptions

Example

The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes.

Exception	Condition
ArgumentNullException	Chars is a null array.
ArgumentOutOfRangeException	Index is less than the lower-bound of Chars for an array or less than zero for a string. -or- Count is less than zero. -or- Index and Count do not denote a valid range in Chars.
EncoderFallbackException	A fallback occurred -and- EncoderFallback is set to EncoderExceptionFallback.

Public Sub Main()
    Dim MyChars()   As Integer
    Dim U7          As Encoding
    Dim U8          As Encoding
    Dim U16LE       As Encoding
    Dim U16BE       As Encoding
    Dim U32         As Encoding
    
    ' The characters to encode:
    '    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)
    '    a high-surrogate value (U+D8FF)
    '    a low-surrogate value (U+DCFF)
    MyChars = NewChars("z", "a", &H306, &H1FD, &H3B2, &HD8FF, &HDCFF)
    
    ' Get different encodings.
    Set U7 = Encoding.UTF7
    Set U8 = Encoding.UTF8
    Set U16LE = Encoding.Unicode
    Set U16BE = Encoding.BigEndianUnicode
    Set U32 = Encoding.UTF32
    
    ' Encode the entire array, and print out the counts and resulting bytes.
    PrintCountsAndBytes MyChars, U7
    PrintCountsAndBytes MyChars, U8
    PrintCountsAndBytes MyChars, U16LE
    PrintCountsAndBytes MyChars, U16BE
    PrintCountsAndBytes MyChars, U32
    
    Console.ReadKey
End Sub

Private Sub PrintCountsAndBytes(ByRef Chars() As Integer, ByVal Enc As Encoding)
    ' Display the name of the encoding used.
    Console.WriteValue "{0,-30} :", Enc.ToString
    
    ' Display the exact byte count.
    Console.WriteValue " {0,-3}", Enc.GetByteCount(Chars)
    
    ' Display the maximum byte count.
    Console.WriteValue " {0,-3} :", Enc.GetMaxByteCount(CorArray.Length(Chars))
    
    ' Encode the array of chars.
    Dim Bytes() As Byte
    Bytes = Enc.GetBytes(Chars)
    
    ' Display all the encoded bytes.
    PrintHexBytes Bytes
End Sub

Private Sub PrintHexBytes(ByRef Bytes() As Byte)
    If CorArray.IsNullOrEmpty(Bytes) Then
        Console.WriteLine "<none>"
    Else
        Dim i As Long
        
        For i = LBound(Bytes) To UBound(Bytes)
            Console.WriteValue "{0:X2} ", Bytes(i)
        Next
        
        Console.WriteLine
    End If
End Sub

'This code produces the following output.
'
'System.Text.UTF7Encoding       : 18  23  :7A 61 2B 41 77 59 42 2F 51 4F 79 32 50 2F 63 2F 77 2D
'System.Text.UTF8Encoding       : 12  24  :7A 61 CC 86 C7 BD CE B2 F1 8F B3 BF
'System.Text.UnicodeEncoding    : 14  16  :7A 00 61 00 06 03 FD 01 B2 03 FF D8 FF DC
'System.Text.UnicodeEncoding    : 14  16  :00 7A 00 61 03 06 01 FD 03 B2 D8 FF DC FF
'System.Text.UTF32Encoding      : 24  32  :7A 00 00 00 61 00 00 00 06 03 00 00 FD 01 00 00 B2 03 00 00 FF FC 04 00

The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes.

Public Sub Main()
    Dim MyStr   As String
    Dim U7      As Encoding
    Dim U8      As Encoding
    Dim U16LE   As Encoding
    Dim U16BE   As Encoding
    Dim U32     As Encoding
    
    ' The characters to encode:
    '    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)
    '    a high-surrogate value (U+D8FF)
    '    a low-surrogate value (U+DCFF)
    MyStr = t("za\u0306\u01FD\u03B2\uD8FF\uDCFF")
    
    ' Get different encodings.
    Set U7 = Encoding.UTF7
    Set U8 = Encoding.UTF8
    Set U16LE = Encoding.Unicode
    Set U16BE = Encoding.BigEndianUnicode
    Set U32 = Encoding.UTF32
    
    ' Encode the entire string, and print out the counts and the resulting bytes.
    Console.WriteLine "Encoding the entire string:"
    PrintCountsAndBytes MyStr, U7
    PrintCountsAndBytes MyStr, U8
    PrintCountsAndBytes MyStr, U16LE
    PrintCountsAndBytes MyStr, U16BE
    PrintCountsAndBytes MyStr, U32
    
    Console.WriteLine
    
    ' Encode three characters starting at index 4, and print out the counts and the resulting bytes.
    Console.WriteLine "Encoding the characters from index 4 through 6:"
    PrintCountsAndBytesEx MyStr, 4, 3, U7
    PrintCountsAndBytesEx MyStr, 4, 3, U8
    PrintCountsAndBytesEx MyStr, 4, 3, U16LE
    PrintCountsAndBytesEx MyStr, 4, 3, U16BE
    PrintCountsAndBytesEx MyStr, 4, 3, U32
    
    Console.ReadKey
End Sub

Private Sub PrintCountsAndBytes(ByRef s As String, ByVal Enc As Encoding)
    ' Display the name of the encoding used.
    Console.WriteValue "{0,-30} :", Enc.ToString
    
    ' Display the exact byte count.
    Console.WriteValue " {0,-3}", Enc.GetByteCount(s)
    
    ' Display the maximum byte count.
    Console.WriteValue " {0,-3} :", Enc.GetMaxByteCount(Len(s))
    
    ' Encode the entire string.
    Dim Bytes() As Byte
    Bytes = Enc.GetBytes(s)
    
    ' Display all the encoded bytes.
    PrintHexBytes Bytes
End Sub

Private Sub PrintCountsAndBytesEx(ByRef s As String, ByVal Index As Long, ByVal Count As Long, ByVal Enc As Encoding)
    ' Display the name of the encoding used.
    Console.WriteValue "{0,-30} :", Enc.ToString
    
    ' Display the exact byte count.
    Console.WriteValue " {0,-3}", Enc.GetByteCount(s, Index, Count)
    
    ' Display the maximum byte count.
    Console.WriteValue " {0,-3} :", Enc.GetMaxByteCount(Count)
    
    ' Encode the entire string.
    Dim Bytes() As Byte
    Bytes = Enc.GetBytes(s, Index, Count)
    
    ' Display all the encoded bytes.
    PrintHexBytes Bytes
End Sub

Private Sub PrintHexBytes(ByRef Bytes() As Byte)
    If CorArray.IsNullOrEmpty(Bytes) Then
        Console.WriteLine "<none>"
    Else
        Dim i As Long
        
        For i = LBound(Bytes) To UBound(Bytes)
            Console.WriteValue "{0:X2} ", Bytes(i)
        Next
        
        Console.WriteLine
    End If
End Sub

'This code produces the following output.
'
'Encoding the entire string:
'System.Text.UTF7Encoding       : 18  23  :7A 61 2B 41 77 59 42 2F 51 4F 79 32 50 2F 63 2F 77 2D
'System.Text.UTF8Encoding       : 12  24  :7A 61 CC 86 C7 BD CE B2 F1 8F B3 BF
'System.Text.UnicodeEncoding    : 14  16  :7A 00 61 00 06 03 FD 01 B2 03 FF D8 FF DC
'System.Text.UnicodeEncoding    : 14  16  :00 7A 00 61 03 06 01 FD 03 B2 D8 FF DC FF
'System.Text.UTF32Encoding      : 24  32  :7A 00 00 00 61 00 00 00 06 03 00 00 FD 01 00 00 B2 03 00 00 FF FC 04 00
'
'Encoding the characters from index 4 through 6:
'System.Text.UTF7Encoding       : 10  11  :2B 41 37 4C 59 2F 39 7A 2F 2D
'System.Text.UTF8Encoding       : 6   12  :CE B2 F1 8F B3 BF
'System.Text.UnicodeEncoding    : 6   8   :B2 03 FF D8 FF DC
'System.Text.UnicodeEncoding    : 6   8   :03 B2 D8 FF DC FF
'System.Text.UTF32Encoding      : 8   16  :B2 03 00 00 FF FC 04 00

GetByteCount

Parameters

Return Values

Remarks

Exceptions

Example

See Also