This method converts a string or byte array containing UTF-8 encoded text
to a native string. The input must be well-formed UTF-8, and if
any invalid sequences are encountered, the method will fail and
raise an exception. This ensures that only structurally valid Unicode
text is returned to the caller.
When calling this method, the input can be provided either as a
byte array or a native string. If a string is used, it must contain
raw UTF-8 encoded bytes, with each character stored in the low-order
byte (i.e., ChrW(&HXX)). This typically occurs when reading a
file in binary mode into a string, such as Input$(LOF(1), #1).
However, it is important to note that this approach is fragile. If
the string contains any non-zero high-order bytes, it will be rejected
as invalid input. Because UTF-8 is inherently a sequence of bytes
and not UTF-16 Unicode characters, it is strongly recommended you
pass the input as a byte array instead. This ensures correct
interpretation of the data and avoids ambiguity or unintended
character conversion.
To verify that the conversion is accurate and no data loss has
occurred, you can convert the resulting string back to a UTF-8 byte
array using the StrToUtf8 method. This round-trip approach is
useful in test scenarios where data integrity is critical, especially
when working with files or network responses encoded in UTF-8.
The StrConv function in Visual Basic 6.0 and VBScript does
not support UTF-8 encoding or decoding. Attempting to use
StrConv(..., vbFromUnicode) or StrConv(..., vbUnicode)
to convert between strings and UTF-8 byte arrays will produce
incorrect results or replace characters with question marks. Always
use StrToUtf8 and Utf8ToStr when working with UTF-8
encoded text.
When converting UTF-8 encoded data to a string using this method,
be aware that standard Visual Basic controls such as TextBox
and Label do not support full Unicode rendering. If the
converted text includes characters outside the ANSI code page,
such as accented letters, emoji, or non-Latin scripts, these
controls may display incorrect or missing characters. This happens
because the controls automatically convert strings to the system
locale's ANSI encoding. To properly display the converted text,
consider using a Unicode-aware control such as the TextBox
control in the Microsoft Forms 2.0 Object Library (FM20.DLL), or use Windows
API functions which support wide character output.
The Utf8ToStr and StrToUtf8 methods are provided
specifically for use with the ActiveX control in environments such as
Visual Basic 6.0 or scripting languages like VBScript, which do not
include built-in support for UTF-8 text encoding. In the .NET version
of the FileEncoder class, these methods are not included
because the .NET Framework and .NET Core provide native support for
UTF-8 conversion through the System.Text.Encoding classes.
Developers using .NET can convert between strings and UTF-8 byte arrays
using Encoding.UTF8.GetBytes and Encoding.UTF8.GetString,
making these methods unnecessary in managed code environments.
The following example creates a UTF-8 encoded text message in Greek
which says "Γειά σου, κόσμε!"
("Hello, world!") both as an array of Bytes and as a
String composed using the ChrW function.
The Utf8ToStr method converts the message to a native string
type which is displayed using the MessageBoxW function in
the Win32 API. Because MessageBoxW accepts Unicode
strings for both the message and title, it can be used to display
fully localized prompts and notifications in other languages.
Note that you could not use the MsgBox function
with this example because it would attempt to convert the string from
Unicode to ANSI using the current active code page. Unless your current
locale uses the Greek character set, the message would not display
correctly.
Private Declare Function MessageBoxW Lib "User32" ( _
ByVal hWnd As Long, _
ByVal lpText As Long, _
ByVal lpCaption As Long, _
ByVal uType As Long _
) As Long
Dim bUtf8(28) As Byte
bUtf8(0) = &HCE: bUtf8(1) = &H93
bUtf8(2) = &HCE: bUtf8(3) = &HB5
bUtf8(4) = &HCE: bUtf8(5) = &HB9
bUtf8(6) = &HCE: bUtf8(7) = &HAC
bUtf8(8) = &H20
bUtf8(9) = &HCF: bUtf8(10) = &H83
bUtf8(11) = &HCE: bUtf8(12) = &HBF
bUtf8(13) = &HCF: bUtf8(14) = &H85
bUtf8(15) = &H2C
bUtf8(16) = &H20
bUtf8(17) = &HCE: bUtf8(18) = &HBA
bUtf8(19) = &HCF: bUtf8(20) = &H8C
bUtf8(21) = &HCF: bUtf8(22) = &H83
bUtf8(23) = &HCE: bUtf8(24) = &HBC
bUtf8(25) = &HCE: bUtf8(26) = &HB5
bUtf8(27) = &H21
Dim sText As String
sText = FileEncoder1.Utf8ToStr(bUtf8)
Dim sTitle As String
sTitle = "Testing Byte Array"
MessageBoxW 0, StrPtr(sText), StrPtr(sTitle), vbOKOnly
Dim sUtf8 As String
sUtf8 = ChrW(&HCE) & ChrW(&H93) & ChrW(&HCE) & ChrW(&HB5) & ChrW(&HCE) & ChrW(&HB9) & _
ChrW(&HCE) & ChrW(&HAC) & ChrW(&H20) & ChrW(&HCF) & ChrW(&H83) & ChrW(&HCE) & _
ChrW(&HBF) & ChrW(&HCF) & ChrW(&H85) & ChrW(&H2C) & ChrW(&H20) & ChrW(&HCE) & _
ChrW(&HBA) & ChrW(&HCF) & ChrW(&H8C) & ChrW(&HCF) & ChrW(&H83) & ChrW(&HCE) & _
ChrW(&HBC) & ChrW(&HCE) & ChrW(&HB5) & ChrW(&H21)
sText = FileEncoder1.Utf8ToStr(sUtf8)
sTitle = "Testing String"
MessageBoxW 0, StrPtr(sText), StrPtr(sTitle), vbOKOnly