GetBytesEx

Encodes a set of characters into an array of bytes, returning the number of bytes produced.

 Public Function GetBytesEx(
	  ByRef Chars As Variant,
	  ByVal CharIndex As Long,
	  ByVal CharCount As Long,
	  ByRef Bytes ( ) As Byte,
	  ByVal ByteIndex As Long ) As Long

Parameters

Chars

[ByRef] Variant. The Integer array or String containing the set of characters to encode.

CharIndex

[ByVal] Long. The index of the first character to encode.

CharCount

[ByVal] Long. The number of characters to encode.

Bytes

[ByRef] Byte. The byte array to contain the resulting sequence of bytes.

ByteIndex

[ByVal] Long. The index as which to start writing the resulting sequence of bytes.

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

Exception	Condition
ArgumentNullException	Chars is a null array. -or- Bytes is a null array.
ArgumentOutOfRangeException	CharIndex is less than the lower-bound of Chars for an array or less than zero for a string. -or- CharCount is less than zero. -or- CharIndex and CharCount do not denote a valid range in Chars. -or- ByteIndex is not a valid index in Bytes.
ArgumentException	Bytes does not have enough capacity from ByteIndex to the end of the array to accommodate the resulting bytes.
EncoderFallbackException	A fallback occurred -and- EncoderFallback is set to EncoderExceptionFallback.

Example

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

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
    
    MyChars = NewChars("z", "a", &H306, &H1FD, &H3B2, &HD8FF, &HDCFF)
    
    Set U7 = Encoding.UTF7
    Set U8 = Encoding.UTF8
    Set U16LE = Encoding.Unicode
    Set U16BE = Encoding.BigEndianUnicode
    Set U32 = Encoding.UTF32
    
    Console.WriteLine "Encoding the characters from index 4 through 6:"
    PrintCountsAndBytes MyChars, 4, 3, U7
    PrintCountsAndBytes MyChars, 4, 3, U8
    PrintCountsAndBytes MyChars, 4, 3, U16LE
    PrintCountsAndBytes MyChars, 4, 3, U16BE
    PrintCountsAndBytes MyChars, 4, 3, U32
    
    Console.ReadKey
End Sub

Private Sub PrintCountsAndBytes(ByRef Chars() As Integer, 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(Chars, Index, Count)
    Console.WriteValue " {0,-3}", IBC
    
    IMBC = Enc.GetMaxByteCount(Count)
    Console.WriteValue " {0,-3} :", IMBC
    
    ReDim Bytes(0 To IBC - 1)
    Enc.GetBytesEx Chars, Index, Count, Bytes, 0
    
    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 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

GetBytes

GetEncoder

GetByteCount

GetMaxByteCount