UTF8Encoding: GetBytes

Encodes all the characters in the specified character array or string into a sequence of bytes.

Parameters

Return Values

Remarks

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.

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

Several versions of GetByteCount, GetBytesEx, and GetBytes are supported. The following are some programming considerations for use of these methods:

Exceptions

Examples

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.

Exception	Condition
ArgumentNullException	Chars is an uninitialized array.
ArgumentOutOfRangeException	Index is less than the lower-bound of Chars for an array or zero for a string. -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 MyStr   As String
    Dim U7      As Encoding
    Dim U8      As Encoding
    Dim U16LE   As Encoding
    Dim U16BE   As Encoding
    Dim U32     As Encoding
    
    MyStr = t("za\u0306\u01FD\u03B2\uD8FF\uDCFF")
    
    Set U7 = Encoding.UTF7
    Set U8 = Encoding.UTF8
    Set U16LE = Encoding.Unicode
    Set U16BE = Encoding.BigEndianUnicode
    Set U32 = Encoding.UTF32
    
    Console.WriteLine "Encoding the entire string:"
    PrintCountsAndBytes MyStr, U7
    PrintCountsAndBytes MyStr, U8
    PrintCountsAndBytes MyStr, U16LE
    PrintCountsAndBytes MyStr, U16BE
    PrintCountsAndBytes MyStr, U32
    
    Console.WriteLine
    
    Console.WriteLine "Encoding the characters from index 4 through 6:"
    PrintCountsAndBytes2 MyStr, 4, 3, U7
    PrintCountsAndBytes2 MyStr, 4, 3, U8
    PrintCountsAndBytes2 MyStr, 4, 3, U16LE
    PrintCountsAndBytes2 MyStr, 4, 3, U16BE
    PrintCountsAndBytes2 MyStr, 4, 3, U32
    
    Console.ReadKey
End Sub

Private Sub PrintCountsAndBytes(ByVal s As String, ByVal Enc As Encoding)
    Dim IBC     As Long
    Dim IMBC    As Long
    Dim Bytes() As Byte
    
    Console.WriteValue "{0,-30} :", Enc.ToString
    
    IBC = Enc.GetByteCount(s)
    Console.WriteValue " {0,-3}", IBC
    
    IMBC = Enc.GetMaxByteCount(Len(s))
    Console.WriteValue " {0,-3} :", IMBC
    
    Bytes = Enc.GetBytes(s)
    
    PrintHexBytes Bytes
End Sub

Private Sub PrintCountsAndBytes2(ByVal s As String, ByVal Index As Long, ByVal Count As Long, ByVal Enc As Encoding)
    Dim IBC     As Long
    Dim IMBC    As Long
    Dim Bytes() As Byte
    
    Console.WriteValue "{0,-30} :", Enc.ToString
    
    IBC = Enc.GetByteCount(s, Index, Count)
    Console.WriteValue " {0,-3}", IBC
    
    IMBC = Enc.GetMaxByteCount(Count)
    Console.WriteValue " {0,-3} :", IMBC
    
    Bytes = Enc.GetBytes(s, Index, Count)
    
    PrintHexBytes Bytes
End Sub

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

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

GetBytes

Parameters

Return Values

Remarks

Exceptions

Examples

See Also