This method will convert the specified input file to use a
different encoding. The most common use is to convert a text file to a
standard UTF-8 encoding. You can specify any valid code page for the
output file; however, it is recommended you use code page 65001 (UTF-8)
in most cases. You can also convert the file to UTF-16LE using code page
1200 or UTF-16BE using code page 1201. If you use either UTF-16 encoding,
a byte order mark (BOM) will automatically be included at the beginning
of the file. This tells text editors what type of encoding was used.
A byte order mark (BOM) may help identify the encoding to some text
editors but may also cause compatibility issues with tools that are
not designed to be aware of Unicode.
- UTF-16LE and UTF-16BE output includes a BOM unless fileConvertNoBom is specified.
- UTF-8 output does not include a BOM unless fileConvertUtf8Bom is specified.
The method can normalize line endings in the input file to match
Windows conventions (CRLF) using the fileConvertNormalize
option. This is useful when converting files originally created on UNIX (LF)
or macOS Classic (CR). If the file already uses the Windows CRLF
convention for the end-of-line, this option will be ignored and has
no effect on the output.
When fileConvertUnicode is used, the method first
checks for a BOM to identify UTF-8 or UTF-16 encodings. If no BOM is
found, it analyzes the byte patterns near the beginning of the file to
detect if the content is valid UTF-8 or contains UTF-16 characteristics.
If detection fails, the code page specified by the InputCP
parameter will be used. The detection of UTF-8 encoded text without a
BOM performs checks to ensure it uses correct codepoints and does not
have characters outside the valid range, therefore it should be considered
reliable in determining if it is valid UTF-8 text.
For text files using UTF-16 without a BOM, there is no stringent
check that can be made to determine which is being used. Instead, the
method uses heuristics to guess which is most likely depending on the
order of null bytes and character sequences in the text. While it is
generally accurate with text files, it is possible the method could
mistakenly identify a binary file as being either UTF-16LE or UTF-16BE
encoded text.
If the output code page does not normally support all of the
characters used with the input text, they will be replaced with placeholder
symbols (typically a "?" character) and the conversion will
proceed. This is most often the case if the input and output code pages
are not compatible (for example, attempting to convert a text file
which was created using Greek code page (1253) to Western European (1252).
It can also occur if you attempt to convert a Unicode text file to
an ANSI code page. In most cases, the only completely safe conversion
is when you convert to a Unicode encoding or between two different
Unicode encodings.
To prevent potential data loss or corruption of the output
file, use the fileConvertStrict option. When this option is used,
the method fails when:
- An invalid or ambiguous encoding is detected.
- Any characters cannot be represented in the output encoding.
- The file ends with incomplete multi-byte sequences.
For a complete list of Windows code pages, you can refer to the
table of code page identifiers in the Windows SDK documentation. The
more common code pages are:
| Code Page |
Description |
Encoding Type |
| 65001 | UTF-8 | Unicode (variable) |
| 1200 | UTF-16 Little Endian (UTF-16LE) | Unicode (fixed) |
| 1201 | UTF-16 Big Endian (UTF-16BE) | Unicode (fixed) |
| 1252 | Western European (Windows Latin 1) | ANSI |
| 1251 | Cyrillic (Windows) | ANSI |
| 1250 | Central European (Windows) | ANSI |
| 1253 | Greek (Windows) | ANSI |
| 1254 | Turkish (Windows) | ANSI |
| 1255 | Hebrew (Windows) | ANSI |
| 1256 | Arabic (Windows) | ANSI |
| 1257 | Baltic (Windows) | ANSI |
| 1258 | Vietnamese (Windows) | ANSI |
| 874 | Thai (Windows) | ANSI |
| 932 | Japanese (Shift-JIS) | DBCS |
| 936 | Simplified Chinese (GB2312) | DBCS |
| 949 | Korean (Unified Hangul Code) | DBCS |
| 950 | Traditional Chinese (Big5) | DBCS |
In addition to the code pages listed above, you can also use 0 as a
code page. This is defined in the Windows SDK as CP_ACP which
refers to the system's current ANSI code page. It should only be used when
explicitly relying on the default behavior for the local system. The code
pages marked as DBCS (Double Byte Character Set) are commonly used for
East Asian languages and support a mixture of single- and multi-byte sequences.
If the conversion cannot be completed successfully, the output file
will not be changed.
Dim strInputFile As String
Dim strOutputFile As String
Dim nError As Long
strInputFile = "%USERPOFILE%\Documents\WideTextFile.txt"
strOutputFile = "%USERPOFILE%\Documents\TextFile.txt"
nError = FileEncoder1.ConvertFile(strInputFile, 1200, strOutputFile, 65001)
If nError = 0 Then
MsgBox "The text file was converted to UTF-8", vbInformation
Else
MsgBox "Unable to convert the text file to UTF-8", vbExclamation
End If