Charset Lua Reference Documentation
chilkat.Charset
Current Version: 11.7.0
Markdown version of this page for AI tools (v 11.7.0) · all AI docs
Deprecated — scheduled for removal
Store raw bytes, load and save files, append byte-order marks, and move
encoded data between files, memory, and other Chilkat objects.
Hold Unicode text and perform charset encoding or decoding, URL
processing, HTML entity conversion, case conversion, and related text
operations.
For new text formats and interchange, use UTF-8 unless a protocol or
legacy system explicitly requires another encoding.
A charset defines how text characters map to bytes. Binary encodings such
as Base64 or hexadecimal solve a different problem and are not character
sets.
The class can inspect and rewrite HTML charset metadata, but these
helpers do not validate that declared metadata matches the actual bytes.
Continue using this class only while maintaining older code, and plan a
tested migration before adopting Chilkat v12.
Legacy character-set conversion utilities. Migrate before Chilkat v12.0.0.
Chilkat.Charset is a legacy class for converting text between
character encodings, reading and writing encoded text files, inspecting or
rewriting HTML charset declarations, encoding and decoding HTML entities,
validating byte sequences, and performing several older text utilities.
It remains documented only to support maintenance and migration of existing
applications.
Use BinData for bytes
Use StringBuilder for text
Prefer UTF-8
Keep bytes and characters distinct
Legacy HTML helpers
Maintenance only
BinData, decode them into a
StringBuilder using the known source charset, work with Unicode
text, then encode back into BinData using the required
destination charset. This makes the boundary between bytes and text explicit
and replaces the stateful FromCharset/ToCharset
workflow.
Object Creation
local chilkat = require("chilkat")
local charset = chilkat.Charset.new()Creates the object (chilkat.Charset() does the same). Lua's garbage collector frees it when it is no longer referenced; charset:dispose() frees it at once, and in Lua 5.4 and later local charset <close> = chilkat.Charset.new() frees it when the block ends. Calling a method of a disposed object raises an error.
Errors
A method that fails returns nil followed by the error text, as io.open does: local body, err = charset:method(...), where err is the object's last_error_text. Wrap the call in assert() to raise an error with that text instead. Methods that answer a question return true or false, numbers are returned as they are (check last_method_success where the description says a value means failure), and property reads and writes never fail for Chilkat reasons.
Misuse raises a Lua error: a wrong argument type or a missing argument (bad argument #1 to ...), an unknown property name, a write to a read-only property, an out-of-range integer, or an object of the wrong class.
Names are Chilkat's in snake_case: QuickGetStr is quick_get_str, LastErrorText is last_error_text. Properties are fields (charset.verbose_logging = true) and methods use the colon (charset:method(...)). Strings are UTF-8; binary data is a Lua string of bytes. Indexes are 0-based, as in every Chilkat API. Unlocking: call chilkat.unlock_bundle("...") once at startup.
Properties
AltToCharset
local strVal = charset.alt_to_charset
charset.alt_to_charset = strVal
Specifies the alternate destination character encoding used only when ErrorAction is 6.
If a decoded input character cannot be represented in ToCharset, Chilkat attempts to encode that character using this alternate charset. If the alternate conversion also fails, the character is omitted from the output.
DebugLogFilePath
local strVal = charset.debug_log_file_path
charset.debug_log_file_path = strVal
If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.
Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.
Possible causes of hangs include:
- A timeout property set to 0, indicating an infinite timeout.
- A hang occurring within an event callback in the application code.
- An internal bug in the Chilkat code causing the hang.
ErrorAction
local intVal = charset.error_action
charset.error_action = intVal
Controls what happens when an input character has been decoded successfully but cannot be represented in the destination charset.
| Value | Action |
|---|---|
0 | Drop the unrepresentable character. |
1 | Insert the replacement configured by SetErrorString. |
2 | Emit a hexadecimal numeric character reference such as €. |
3–5 | Reserved. Do not use. |
6 | Encode the character using AltToCharset; drop it if that also fails. |
7 | Pass the nonconvertible data through unchanged. |
0, 6, and 7 can silently lose data or produce output that is not valid in the declared destination charset. For new code, prefer an explicit failure or replacement policy in the replacement API.FromCharset
local strVal = charset.from_charset
charset.from_charset = strVal
Specifies the character encoding of the input bytes for conversion operations. Chilkat decodes the source bytes using this charset before encoding the resulting Unicode text using ToCharset.
| Family | Recognized names |
|---|---|
| Unicode and ASCII | us-ascii, utf-7, utf-8, unicode / utf-16 / utf-16le, unicodefffe / utf-16be, utf-32, utf-32be |
| ISO and Windows | iso-8859-1, -2, -3, -4, -5, -6, -7, -8, -9, -13, -15; windows-874, windows-1250 through windows-1258 |
| East Asian | shift_jis, gb2312, ks_c_5601-1987, big5, iso-2022-jp, iso-2022-kr, euc-jp, euc-kr |
| Macintosh | macintosh, x-mac-japanese, x-mac-chinesetrad, x-mac-korean, x-mac-arabic, x-mac-hebrew, x-mac-greek, x-mac-cyrillic, x-mac-chinesesimp, x-mac-romanian, x-mac-ukrainian, x-mac-thai, x-mac-ce, x-mac-icelandic, x-mac-turkish, x-mac-croatian |
| DOS, IBM, and legacy | ebcdic, asmo-708, dos-720, dos-862, ibm01140 through ibm01149, ibm037, ibm437, ibm500, ibm737, ibm775, ibm850, ibm852, ibm855, ibm857, ibm00858, ibm860, ibm861, ibm863, ibm864, ibm865, cp866, ibm869, ibm870, cp875, koi8-r, koi8-u |
unicode, utf-16, and utf-16le identify little-endian UTF-16. unicodefffe and utf-16be identify big-endian UTF-16. Except where a method explicitly documents HTML metadata detection, set the source charset explicitly rather than assuming automatic detection.LastErrorHtml
local strVal = charset.last_error_html
Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastErrorText
local strVal = charset.last_error_text
Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
LastErrorXml
local strVal = charset.last_error_xml
Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastInputAsHex
local strVal = charset.last_input_as_hex
Returns the input bytes captured for the most recent conversion performed while SaveLast was enabled, represented as hexadecimal text.
LastInputAsQP
local strVal = charset.last_input_as_qp
Returns the input bytes captured for the most recent conversion performed while SaveLast was enabled, represented as quoted-printable text.
LastMethodSuccess
local boolVal = charset.last_method_success
charset.last_method_success = boolVal
Indicates the success or failure of the most recent method call: true means success, false means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.
LastOutputAsHex
local strVal = charset.last_output_as_hex
Returns the output bytes captured for the most recent conversion performed while SaveLast was enabled, represented as hexadecimal text.
LastOutputAsQP
local strVal = charset.last_output_as_qp
Returns the output bytes captured for the most recent conversion performed while SaveLast was enabled, represented as quoted-printable text.
SaveLast
local boolVal = charset.save_last
charset.save_last = boolVal
When true, retains the input and output byte sequences from each conversion so they can be inspected through LastInputAsHex, LastInputAsQP, LastOutputAsHex, and LastOutputAsQP.
ToCharset
local strVal = charset.to_charset
charset.to_charset = strVal
Specifies the destination character encoding for conversion operations. After decoding the source bytes using FromCharset, Chilkat encodes the resulting Unicode text in this charset.
| Family | Recognized names |
|---|---|
| Unicode and ASCII | us-ascii, utf-7, utf-8, unicode / utf-16 / utf-16le, unicodefffe / utf-16be, utf-32, utf-32be |
| ISO and Windows | iso-8859-1, -2, -3, -4, -5, -6, -7, -8, -9, -13, -15; windows-874, windows-1250 through windows-1258 |
| East Asian | shift_jis, gb2312, ks_c_5601-1987, big5, iso-2022-jp, iso-2022-kr, euc-jp, euc-kr |
| Macintosh | macintosh, x-mac-japanese, x-mac-chinesetrad, x-mac-korean, x-mac-arabic, x-mac-hebrew, x-mac-greek, x-mac-cyrillic, x-mac-chinesesimp, x-mac-romanian, x-mac-ukrainian, x-mac-thai, x-mac-ce, x-mac-icelandic, x-mac-turkish, x-mac-croatian |
| DOS, IBM, and legacy | ebcdic, asmo-708, dos-720, dos-862, ibm01140 through ibm01149, ibm037, ibm437, ibm500, ibm737, ibm775, ibm850, ibm852, ibm855, ibm857, ibm00858, ibm860, ibm861, ibm863, ibm864, ibm865, cp866, ibm869, ibm870, cp875, koi8-r, koi8-u |
utf-8 is normally the preferred destination. Legacy single-byte encodings cannot represent every Unicode character; ErrorAction controls how such conversion failures are handled.VerboseLogging
local boolVal = charset.verbose_logging
charset.verbose_logging = boolVal
If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
Version
local strVal = charset.version
Methods
CharsetToCodePage
-- n is an integer
local n = charset:charset_to_code_page(charset_name)
Returns the numeric Windows code-page identifier corresponding to charset_name. For example, iso-8859-1 maps to 28591, and utf-8 maps to 65001.
utf-8 rather than numeric code pages.CodePageToCharset
-- str is a string, or nil and err on failure
local str, err = charset:code_page_to_charset(code_page)
Returns the charset name corresponding to the numeric code-page identifier in code_page. For example, 65001 maps to utf-8. The operation fails when the code page is not recognized.
Returns the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
ConvertFile
-- dest_path is a string
-- ok is true, or nil and err on failure
local ok, err = charset:convert_file(in_path, dest_path)
Reads the file at in_path, converts its text from FromCharset to ToCharset, and writes the converted bytes to the file at dest_path.
When the destination charset is utf-8 or utf-16, this method writes the corresponding byte-order mark (BOM) at the beginning of the output. Use ConvertFileNoPreamble when the output must not contain a BOM.
Returns true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
ConvertFileNoPreamble
-- dest_path is a string
-- ok is true, or nil and err on failure
local ok, err = charset:convert_file_no_preamble(in_path, dest_path)
Reads the file at in_path, converts its text from FromCharset to ToCharset, and writes the converted bytes to dest_path without adding a byte-order mark or other encoding preamble.
Returns true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
ConvertHtmlFile
-- dest_path is a string
-- ok is true, or nil and err on failure
local ok, err = charset:convert_html_file(in_path, dest_path)
Converts the HTML file at in_path to ToCharset and writes the result to dest_path. Chilkat also updates the HTML <meta> charset declaration to identify the destination encoding.
If FromCharset is empty, Chilkat attempts to obtain the source charset from an HTML <meta> declaration. Otherwise, the explicitly configured source charset is used.
Returns true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
EntityEncodeDec
-- str is a string, or nil and err on failure
local str, err = charset:entity_encode_dec(str)
Returns str with each non-US-ASCII character replaced by a decimal HTML/XML numeric character reference. For example, é becomes é.
Returns the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
EntityEncodeHex
-- str is a string, or nil and err on failure
local str, err = charset:entity_encode_hex(str)
Returns str with each non-US-ASCII character replaced by a hexadecimal HTML/XML numeric character reference. For example, é becomes é.
Returns the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
GetHtmlFileCharset
-- str is a string, or nil and err on failure
local str, err = charset:get_html_file_charset(html_file_path)
Examines the HTML file at html_file_path and returns the charset name declared by an HTML <meta> element, when present.
Returns the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
HtmlDecodeToStr
-- str is a string, or nil and err on failure
local str, err = charset:html_decode_to_str(in_str)
Decodes HTML named entities and numeric character references in in_str and returns the resulting Unicode string. Examples include <, &, é, and é.
<, >, and &.Returns the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
HtmlEntityDecodeFile
-- dest_path is a string
-- ok is true, or nil and err on failure
local ok, err = charset:html_entity_decode_file(in_path, dest_path)
Reads the file at in_path, decodes HTML named entities and numeric character references, and writes the transformed content to dest_path.
Returns true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
LowerCase
-- str is a string, or nil and err on failure
local str, err = charset:lower_case(in_str)
Returns the lowercase form of in_str using Chilkat’s Unicode case conversion.
Returns the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
ReadFileToString
-- charset is a string
-- str is a string, or nil and err on failure
local str, err = charset:read_file_to_string(path, charset)
Reads the text file at path, decodes its bytes using the charset named by charset, and returns the resulting Unicode string.
Returns the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
SetErrorString
-- charset is a string
charset:set_error_string(str, charset)
Configures the replacement used when ErrorAction is 1. str is the replacement text, and charset identifies the charset used to encode that replacement into the conversion output.
?, but explicit error handling is safer when data loss is unacceptable.UpperCase
-- str is a string, or nil and err on failure
local str, err = charset:upper_case(in_str)
Returns the uppercase form of in_str using Chilkat’s Unicode case conversion.
Returns the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
UrlDecodeStr
-- str is a string, or nil and err on failure
local str, err = charset:url_decode_str(in_str)
Percent-decodes in_str and interprets the resulting bytes using the platform’s legacy ANSI character encoding.
For example, in a Western Windows code page, %C9 may decode as É. UTF-8 input would encode the same character as %C3%89 and is therefore not handled correctly by this legacy assumption.
StringBuilder URL decoding with an explicit charset, normally utf-8.Returns the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
VerifyFile
-- path is a string
-- flag is true or false
local flag = charset:verify_file(charset, path)
Returns true when the contents of the file at path form a valid byte sequence for the charset named by charset; otherwise returns false.
Returns true or false: an answer, not a success flag.
WriteStringToFile
-- path is a string
-- charset is a string
-- ok is true, or nil and err on failure
local ok, err = charset:write_string_to_file(text_data, path, charset)
Encodes the Unicode text in text_data using the charset named by charset and writes the resulting bytes to the file at path.
utf-8 for modern interchange unless a receiving system requires a specific legacy encoding.Returns true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.