Encoding: GetBytes

GetBytes

Encodes a set of characters into an array of bytes.



 Public Function GetBytes(
	  ByRef Chars As Variant,
	  Optional ByRef Index As Variant,
	  Optional ByRef Count As Variant ) As Byte ( ) :

Parameters

Chars
[ByRef] Variant. The Integer array or String containing the set of characters to encode.
Index
[ByRef] Optional. Variant. The index of the first character to encode.
Count
[ByRef] Optional. Variant. The number of characters to encode.

Return Values

Byte() -  A byte array containing the results of encoding the specified set of characters.

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, of an implemented class.

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

Exceptions

ExceptionCondition
ArgumentNullExceptionChars 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.

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.

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

See Also

Project CorLib Overview

Class Encoding Overview

GetBytesEx

GetEncoder

GetByteCount

GetMaxByteCount