Programming Reference Manual

toUTF8

 
Syntax
 
string = stringclassobject.toUTF8
 
Description
Encodes the contents of the StringClass instance, interpreting it as a Windows-1252 (ANSI) string, and returns the resulting text as a UTF-8 byte sequence.
 
toUTF8 is the inverse of .fromUTF8 and is intended for situations where text held in the native Tradium string representation must be passed to an external system that expects UTF-8 — for example the body of a REST API request, a JSON or XML payload, the URL of an outgoing HTTP call, or a file destined for a modern editor or another platform.
 
Conversion is performed via the Windows API functions MultiByteToWideChar (cp1252 ? UTF-16) followed by WideCharToMultiByte (UTF-16 ? UTF-8), which guarantees correct handling of all characters in the Windows-1252 codepage, including accented Latin characters such as é, è, ü, ñ, ç and the euro sign (€), which expands to a three-byte UTF-8 sequence. The contents of the StringClass instance itself are not modified; toUTF8 only returns the encoded result as a byte-per-character VB6 string in which every character represents exactly one UTF-8 output byte. When the input contains only plain ASCII characters (code points 0–127), toUTF8 returns the buffer unchanged, since ASCII is by definition a valid UTF-8 subset.
 
To verify whether a buffer is recognised as UTF-8, the isUTF8 method may be used. For the reverse operation — decoding a UTF-8 buffer back into the native Windows-1252 representation — use fromUTF8, or rely on the convenience method toString which performs automatic detection and conversion. Earlier versions of the StringClass implemented this conversion through a per-character bit-shift loop in script code; the current API-based implementation is significantly faster and fully deterministic.
 
See Also
FromUTF8, isUTF8,  toString, toURL.
Example
Sub Main
    Dim oS As StringClass
    Dim sNative$
    Dim sPayload$
 
    sNative$ = "Café Brûlé"
 
    Set oS = New StringClass
    oS.Value = sNative$
 
    sPayload$ = oS.toUTF8
    Debug.Print "Native byte count: "; Len(sNative$)
    Debug.Print "UTF-8 byte count:  "; Len(sPayload$)
    Debug.Print "UTF-8 payload:     "; sPayload$
 
    Set oS = Nothing
End Sub