Charset Chilkat2 Java Reference Documentation
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
import com.chilkatsoft.chilkat2.ChilkatException;
import com.chilkatsoft.chilkat2.Charset;
try (Charset charset = new Charset()) {
// ... use charset ...
} catch (ChilkatException e) {
System.out.println(e.getMessage()); // "Charset.someMethod failed: <reason>"
System.out.println(e.getLastErrorText()); // the full log of the failed call
}Creates the underlying native Chilkat object. The native library (chilkat2java) is loaded the first time any Chilkat2 object is created; see the README in the download for where it is looked for (-Dchilkat2.library.path, a classpath resource, or java.library.path).
Releases the native object (Charset is AutoCloseable, so try-with-resources calls it). Calling it again does nothing; any other method or property accessor called afterwards throws IllegalStateException. An object that is never closed is freed by a background cleaner once it becomes unreachable, but the garbage collector does not see native memory, so closing is the normal path. Objects returned by methods are owned by the caller too.
Returns true once close() has been called.
Errors
A method that fails throws ChilkatException, an unchecked exception carrying getClassName(), getMethodName(), getReason() (one line, also in the message) and getLastErrorText() (the full log, captured at the moment of the failure). The object remains usable. Methods that look something up and find nothing return null instead of throwing (each such method says so), and methods that answer a question (hasMember, isUnlocked, ...) return a plain boolean. Property accessors do not throw for Chilkat reasons.
A null string or object argument throws NullPointerException naming the parameter (except where a method documents that null is accepted), and a string containing U+0000 throws IllegalArgumentException.
Use an object from one thread at a time; it may be handed from one thread to another. The one cross-thread operation is setting setAbortCurrent(true) on an object that is busy in another thread (on the classes that have AbortCurrent). Unlocking: call new Global().unlockBundle("...") once at startup.
Properties
AltToCharset
String getAltToCharset()
void setAltToCharset(String value)
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
String getDebugLogFilePath()
void setDebugLogFilePath(String value)
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
int getErrorAction()
void setErrorAction(int value)
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
String getFromCharset()
void setFromCharset(String value)
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
String getLastErrorHtml()
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
String getLastErrorText()
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
String getLastErrorXml()
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
String getLastInputAsHex()
Returns the input bytes captured for the most recent conversion performed while SaveLast was enabled, represented as hexadecimal text.
LastInputAsQP
String getLastInputAsQP()
Returns the input bytes captured for the most recent conversion performed while SaveLast was enabled, represented as quoted-printable text.
LastMethodSuccess
boolean getLastMethodSuccess()
void setLastMethodSuccess(boolean value)
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
String getLastOutputAsHex()
Returns the output bytes captured for the most recent conversion performed while SaveLast was enabled, represented as hexadecimal text.
LastOutputAsQP
String getLastOutputAsQP()
Returns the output bytes captured for the most recent conversion performed while SaveLast was enabled, represented as quoted-printable text.
SaveLast
boolean getSaveLast()
void setSaveLast(boolean value)
When true, retains the input and output byte sequences from each conversion so they can be inspected through LastInputAsHex, LastInputAsQP, LastOutputAsHex, and LastOutputAsQP.
ToCharset
String getToCharset()
void setToCharset(String value)
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
boolean getVerboseLogging()
void setVerboseLogging(boolean value)
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
String getVersion()
Methods
CharsetToCodePage
Returns the numeric Windows code-page identifier corresponding to charsetName. For example, iso-8859-1 maps to 28591, and utf-8 maps to 65001.
utf-8 rather than numeric code pages.CodePageToCharset
Returns the charset name corresponding to the numeric code-page identifier in codePage. For example, 65001 maps to utf-8. The operation fails when the code page is not recognized.
Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.
ConvertFile
Reads the file at inPath, converts its text from FromCharset to ToCharset, and writes the converted bytes to the file at destPath.
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.
Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.
ConvertFileNoPreamble
Reads the file at inPath, converts its text from FromCharset to ToCharset, and writes the converted bytes to destPath without adding a byte-order mark or other encoding preamble.
Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.
ConvertHtmlFile
Converts the HTML file at inPath to ToCharset and writes the result to destPath. 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.
Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.
EntityEncodeDec
Returns str with each non-US-ASCII character replaced by a decimal HTML/XML numeric character reference. For example, é becomes é.
Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.
EntityEncodeHex
Returns str with each non-US-ASCII character replaced by a hexadecimal HTML/XML numeric character reference. For example, é becomes é.
Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.
GetHtmlFileCharset
Examines the HTML file at htmlFilePath and returns the charset name declared by an HTML <meta> element, when present.
Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.
HtmlDecodeToStr
Decodes HTML named entities and numeric character references in inStr and returns the resulting Unicode string. Examples include <, &, é, and é.
<, >, and &.Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.
HtmlEntityDecodeFile
Reads the file at inPath, decodes HTML named entities and numeric character references, and writes the transformed content to destPath.
Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.
LowerCase
Returns the lowercase form of inStr using Chilkat’s Unicode case conversion.
Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.
ReadFileToString
Reads the text file at path, decodes its bytes using the charset named by charset, and returns the resulting Unicode string.
Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.
SetErrorString
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
Returns the uppercase form of inStr using Chilkat’s Unicode case conversion.
Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.
UrlDecodeStr
Percent-decodes inStr 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.Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.
VerifyFile
Returns true when the contents of the file at path form a valid byte sequence for the charset named by charset; otherwise returns false.
Never throws: false is an answer, not a failure.
WriteStringToFile
Encodes the Unicode text in textData 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.Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.