UTF8Encoding: GetString

GetString

Decodes a range of bytes from a byte array into a string.

 Public Function GetString(
	  ByRef Bytes ( ) As Byte,
	  Optional ByRef Index As Variant,
	  Optional ByRef Count As Variant ) As String

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

String - A String containing the results of decoding the specified sequence of bytes.

Remarks

With error detection, an invalid sequence causes this method to throw a ArgumentException. Without error detection, invalid sequences are ignored, and no exception is thrown.

If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the CorString.TrimStart method.

Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the Decoder or the Encoder provided by the GetDecoder method or the GetEncoder method, respectively.

Exceptions

Exception Condition

ArgumentNullException Bytes is uninitialized.

ArgumentOutOfRangeException Index is less than the lower-bound of Bytes.
-or-
Count is less than zero.
-or-
Index and Count do not denote a valid range in Bytes.

ArgumentException Error detection is enabled, and Bytes contains an invalid sequence of bytes.

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

Exception	Condition
ArgumentNullException	Bytes is uninitialized.
ArgumentOutOfRangeException	Index is less than the lower-bound of Bytes. -or- Count is less than zero. -or- Index and Count do not denote a valid range in Bytes.
ArgumentException	Error detection is enabled, and Bytes contains an invalid sequence of bytes.
DecoderFallbackException	A fallback occurred -and- DecoderFallback is set to DecoderExceptionFallback.html.

Examples

The following example initializes an array by calling the GetByteCount method to determine exactly how many bytes are required for an encoded string and then adding the size of the byte order mark (BOM). The example then calls the GetPreamble method to store the BOM to the array before calling the GetBytesEx method to store the encoded bytes to the array. The example then calls the GetString method to decode the string.

Public Sub Main()
    Dim UTF8    As UTF8Encoding
    Dim Bytes() As Byte
    Dim s       As String
    Dim s2      As String
    
    Set UTF8 = NewUTF8Encoding(True, True)
    
    s = "It was the best of times, it was the worst of times..."
    
    ' We need to dimension the array, since we'll populate it with 2 method calls.
    ReDim Bytes(0 To UTF8.GetByteCount(s) + CorArray.Length(UTF8.GetPreamble) - 1)
    
    ' Encode the string
    CorArray.Copy UTF8.GetPreamble, Bytes, CorArray.Length(UTF8.GetPreamble)
    UTF8.GetBytesEx s, 0, Len(s), Bytes, CorArray.Length(UTF8.GetPreamble)
    
    ' Decode the byte array.
    s2 = UTF8.GetString(Bytes)
    Console.WriteLine s2
    
    Console.ReadKey
End Sub

' This code produces the following output.
'
'    ?It was the best of times, it was the worst of times...