Package com.chilkatsoft.chilkat2

Class Charset

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Charset
All Implemented Interfaces:
AutoCloseable
public class Charset extends ChilkatObject
<section class="charset-summary">

Legacy character-set conversion utilities. Migrate before Chilkat v12.0.0.

Do not use Chilkat.Charset in new development. The entire class is deprecated and is scheduled to be removed in Chilkat v12.0.0. Existing applications should migrate now. Equivalent functionality is available in the free Chilkat.BinData and Chilkat.StringBuilder classes.

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

Store raw bytes, load and save files, append byte-order marks, and move encoded data between files, memory, and other Chilkat objects.

Use StringBuilder for text

Hold Unicode text and perform charset encoding or decoding, URL processing, HTML entity conversion, case conversion, and related text operations.

Prefer UTF-8

For new text formats and interchange, use UTF-8 unless a protocol or legacy system explicitly requires another encoding.

Keep bytes and characters distinct

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.

Legacy HTML helpers

The class can inspect and rewrite HTML charset metadata, but these helpers do not validate that declared metadata matches the actual bytes.

Maintenance only

Continue using this class only while maintaining older code, and plan a tested migration before adopting Chilkat v12.

Migration pattern: load encoded bytes into 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.

</section>

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • Charset

      public Charset()
      Creates a new Charset object.

  • Method Details

    • getAltToCharset

      public String getAltToCharset()
      Specifies the alternate destination character encoding used only when getErrorAction() is 6.

      If a decoded input character cannot be represented in getToCharset(), Chilkat attempts to encode that character using this alternate charset. If the alternate conversion also fails, the character is omitted from the output.

      Mixed-encoding output: The result can contain a mixture of byte encodings. Such output is usually unsuitable for interchange unless the receiving format explicitly supports this behavior.

      Returns:
      the value of the AltToCharset property

    • setAltToCharset

      public void setAltToCharset​(String value)
      Sets the AltToCharset property; see getAltToCharset().
      Parameters:
      value - the new value (not null)

    • getErrorAction

      public int getErrorAction()
      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(String, String).

      2 Emit a hexadecimal numeric character reference such as &#x20AC;.

      3–5 Reserved. Do not use.

      6 Encode the character using getAltToCharset(); drop it if that also fails.

      7 Pass the nonconvertible data through unchanged.

      Data-integrity warning: Values 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.

      Returns:
      the value of the ErrorAction property

    • setErrorAction

      public void setErrorAction​(int value)
      Sets the ErrorAction property; see getErrorAction().
      Parameters:
      value - the new value

    • getFromCharset

      public String getFromCharset()
      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 getToCharset().

      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

      Source encoding: 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.

      Returns:
      the value of the FromCharset property

    • setFromCharset

      public void setFromCharset​(String value)
      Sets the FromCharset property; see getFromCharset().
      Parameters:
      value - the new value (not null)

    • getLastInputAsHex

      public String getLastInputAsHex()
      Returns the input bytes captured for the most recent conversion performed while getSaveLast() was enabled, represented as hexadecimal text.

      Diagnostic snapshot: This is a diagnostic representation of the raw bytes. It does not perform another charset conversion, and the quoted-printable form is intended to make otherwise nonprintable bytes easier to inspect.

      Returns:
      the value of the LastInputAsHex property (read-only)

    • getLastInputAsQP

      public String getLastInputAsQP()
      Returns the input bytes captured for the most recent conversion performed while getSaveLast() was enabled, represented as quoted-printable text.

      Diagnostic snapshot: This is a diagnostic representation of the raw bytes. It does not perform another charset conversion, and the quoted-printable form is intended to make otherwise nonprintable bytes easier to inspect.

      Returns:
      the value of the LastInputAsQP property (read-only)

    • getLastOutputAsHex

      public String getLastOutputAsHex()
      Returns the output bytes captured for the most recent conversion performed while getSaveLast() was enabled, represented as hexadecimal text.

      Diagnostic snapshot: This is a diagnostic representation of the raw bytes. It does not perform another charset conversion, and the quoted-printable form is intended to make otherwise nonprintable bytes easier to inspect.

      Returns:
      the value of the LastOutputAsHex property (read-only)

    • getLastOutputAsQP

      public String getLastOutputAsQP()
      Returns the output bytes captured for the most recent conversion performed while getSaveLast() was enabled, represented as quoted-printable text.

      Diagnostic snapshot: This is a diagnostic representation of the raw bytes. It does not perform another charset conversion, and the quoted-printable form is intended to make otherwise nonprintable bytes easier to inspect.

      Returns:
      the value of the LastOutputAsQP property (read-only)

    • getSaveLast

      public boolean getSaveLast()
      When true, retains the input and output byte sequences from each conversion so they can be inspected through getLastInputAsHex(), getLastInputAsQP(), getLastOutputAsHex(), and getLastOutputAsQP().

      Debugging only: Enable this only while troubleshooting. Retaining both sides of a large conversion increases memory use and may keep sensitive plaintext in memory longer than necessary.

      Returns:
      the value of the SaveLast property

    • setSaveLast

      public void setSaveLast​(boolean value)
      Sets the SaveLast property; see getSaveLast().
      Parameters:
      value - the new value

    • getToCharset

      public String getToCharset()
      Specifies the destination character encoding for conversion operations. After decoding the source bytes using getFromCharset(), 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

      Choosing an output encoding: For new text interchange, utf-8 is normally the preferred destination. Legacy single-byte encodings cannot represent every Unicode character; getErrorAction() controls how such conversion failures are handled.

      Returns:
      the value of the ToCharset property

    • setToCharset

      public void setToCharset​(String value)
      Sets the ToCharset property; see getToCharset().
      Parameters:
      value - the new value (not null)

    • charsetToCodePage

      public int charsetToCodePage​(String charsetName)
      Returns the numeric Windows code-page identifier corresponding to charsetName. For example, iso-8859-1 maps to 28591, and utf-8 maps to 65001.

      Code pages: A code page number is a legacy Windows identifier for a character encoding. Internet protocols and modern APIs normally use charset names such as utf-8 rather than numeric code pages.

      Parameters:
      charsetName - the charsetName argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • codePageToCharset

      public String codePageToCharset​(int codePage)
      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.

      Name normalization: Different aliases can identify the same encoding. The returned value is Chilkat’s canonical name for the recognized code page, not necessarily the alias originally used by another application.

      Parameters:
      codePage - the codePage argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • convertFile

      public void convertFile​(String inPath, String destPath)
      Reads the file at inPath, converts its text from getFromCharset() to getToCharset(), 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(String, String) when the output must not contain a BOM.

      BOM behavior: A BOM is a leading byte sequence that can identify a Unicode encoding or byte order. UTF-8 does not require a BOM, and many modern formats prefer UTF-8 without one.

      Parameters:
      inPath - the inPath argument (not null)
      destPath - the destPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • convertFileNoPreamble

      public void convertFileNoPreamble​(String inPath, String destPath)
      Reads the file at inPath, converts its text from getFromCharset() to getToCharset(), and writes the converted bytes to destPath without adding a byte-order mark or other encoding preamble.

      UTF-8 output: This is generally the appropriate choice for UTF-8 files unless the consuming system specifically requires a UTF-8 BOM.

      Parameters:
      inPath - the inPath argument (not null)
      destPath - the destPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • convertHtmlFile

      public void convertHtmlFile​(String inPath, String destPath)
      Converts the HTML file at inPath to getToCharset() and writes the result to destPath. Chilkat also updates the HTML <meta> charset declaration to identify the destination encoding.

      If getFromCharset() is empty, Chilkat attempts to obtain the source charset from an HTML <meta> declaration. Otherwise, the explicitly configured source charset is used.

      Detection limitation: A declared charset is metadata, not proof of the file’s actual encoding. Incorrect or missing declarations can cause decoding errors; use an explicit source charset when it is known.

      Parameters:
      inPath - the inPath argument (not null)
      destPath - the destPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • entityEncodeDec

      public String entityEncodeDec​(String str)
      Returns str with each non-US-ASCII character replaced by a decimal HTML/XML numeric character reference. For example, é becomes &#233;.

      Entity encoding: Numeric character references describe Unicode characters; they are not a character-set conversion and do not make arbitrary binary data safe for HTML.

      Parameters:
      str - the str argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • entityEncodeHex

      public String entityEncodeHex​(String str)
      Returns str with each non-US-ASCII character replaced by a hexadecimal HTML/XML numeric character reference. For example, é becomes &#xE9;.

      Entity encoding: Decimal and hexadecimal numeric references represent the same Unicode character; only the textual notation differs.

      Parameters:
      str - the str argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getHtmlFileCharset

      public String getHtmlFileCharset​(String htmlFilePath)
      Examines the HTML file at htmlFilePath and returns the charset name declared by an HTML <meta> element, when present.

      Metadata only: The method reads document metadata only. A missing, stale, or incorrect declaration does not reveal the file’s true encoding.

      Parameters:
      htmlFilePath - the htmlFilePath argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • htmlDecodeToStr

      public String htmlDecodeToStr​(String inStr)
      Decodes HTML named entities and numeric character references in inStr and returns the resulting Unicode string. Examples include &lt;, &amp;, &#233;, and &#xE9;.

      Security context: Entity decoding is a text transformation, not HTML parsing or sanitization. Decoding untrusted text can reintroduce markup-significant characters such as <, >, and &.

      Parameters:
      inStr - the inStr argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • htmlEntityDecodeFile

      public void htmlEntityDecodeFile​(String inPath, String destPath)
      Reads the file at inPath, decodes HTML named entities and numeric character references, and writes the transformed content to destPath.

      Content transformation: The output may contain literal markup-significant characters that were previously escaped. This operation does not parse, validate, or sanitize HTML.

      Parameters:
      inPath - the inPath argument (not null)
      destPath - the destPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • lowerCase

      public String lowerCase​(String inStr)
      Returns the lowercase form of inStr using Chilkat’s Unicode case conversion.

      Unicode casing: Case conversion can change string length and is not the same operation as locale-aware collation or case-insensitive comparison.

      Parameters:
      inStr - the inStr argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • readFileToString

      public String readFileToString​(String path, String charset)
      Reads the text file at path, decodes its bytes using the charset named by charset, and returns the resulting Unicode string.

      Charset must match the file: The caller must supply the actual source encoding. Choosing the wrong charset can produce replacement characters or silently incorrect text even when the file can be decoded.

      Parameters:
      path - the path argument (not null)
      charset - the charset argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setErrorString

      public void setErrorString​(String str, String charset)
      Configures the replacement used when getErrorAction() is 1. str is the replacement text, and charset identifies the charset used to encode that replacement into the conversion output.

      Replacement behavior: Choose replacement text that is representable in the specified charset. A common replacement is ?, but explicit error handling is safer when data loss is unacceptable.

      Parameters:
      str - the str argument (not null)
      charset - the charset argument (not null)

    • upperCase

      public String upperCase​(String inStr)
      Returns the uppercase form of inStr using Chilkat’s Unicode case conversion.

      Unicode casing: Case conversion can change string length and is not the same operation as locale-aware collation or case-insensitive comparison.

      Parameters:
      inStr - the inStr argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • urlDecodeStr

      public String urlDecodeStr​(String inStr)
      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.

      Legacy ANSI behavior: Do not use this method for modern URLs or form data unless the data is known to use the applicable ANSI code page. Use StringBuilder URL decoding with an explicit charset, normally utf-8.

      Parameters:
      inStr - the inStr argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • verifyFile

      public boolean verifyFile​(String charset, String 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.

      Validation limitation: A successful result means only that the bytes are structurally valid for that encoding. It does not identify the encoding or confirm that the decoded text is semantically correct.

      Parameters:
      charset - the charset argument (not null)
      path - the path argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • writeStringToFile

      public void writeStringToFile​(String textData, String path, String charset)
      Encodes the Unicode text in textData using the charset named by charset and writes the resulting bytes to the file at path.

      Destination encoding: The charset argument is the third parameter. Select utf-8 for modern interchange unless a receiving system requires a specific legacy encoding.

      Parameters:
      textData - the textData argument (not null)
      path - the path argument (not null)
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why