@chilkat/react-native 11.6.1

package/src/specs/Charset.nitro.ts

@@ -0,0 +1,518 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+
+/**
+ * Legacy character-set conversion utilities. Migrate before Chilkat v12.0.0.
+ *
+ * **Do not use `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.
+ *
+ * `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.
+ *
+ * Each `Charset` instance owns a native Chilkat object. It is released when the JavaScript object
+ * is
+ * garbage collected, or immediately by `dispose()`; any use after `dispose()` throws.
+ * Create one with `new Charset()`.
+ */
+export interface Charset extends HybridObject<{ ios: 'c++', android: 'c++' }> {
+  // ---- Properties ----
+
+  /**
+   * 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.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorHtml: string
+
+  /**
+   * 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.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorText: string
+
+  /**
+   * 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.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorXml: string
+
+  /**
+   * Version of the component/library, such as "10.1.0"
+   *
+   * This property is read-only.
+   */
+  readonly version: string
+
+  /**
+   * 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.
+   */
+  debugLogFilePath: string
+
+  /**
+   * 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.
+   */
+  verboseLogging: boolean
+
+  /**
+   * 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.
+   */
+  lastMethodSuccess: boolean
+
+  /**
+   * Specifies the alternate destination character encoding used only when {@link
+   * Charset.errorAction} is `6`.
+   *
+   * If a decoded input character cannot be represented in {@link Charset.toCharset}, 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.
+   */
+  altToCharset: string
+
+  /**
+   * Controls what happens when an input character has been decoded successfully but cannot be
+   * represented in the destination charset.
+   *
+   * ValueAction
+   *
+   * | `0` |  | Drop the unrepresentable character. |
+   *
+   * | `1` |  | Insert the replacement configured by {@link Charset.setErrorString}. |
+   *
+   * | `2` |  | Emit a hexadecimal numeric character reference such as `&#x20AC;`. |
+   *
+   * | `3`–`5` |  | Reserved. Do not use. |
+   *
+   * | `6` | | Encode the character using {@link Charset.altToCharset}; 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.
+   */
+  errorAction: number
+
+  /**
+   * 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 {@link
+   * Charset.toCharset}.
+   *
+   * FamilyRecognized 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.
+   */
+  fromCharset: string
+
+  /**
+   * Returns the input bytes captured for the most recent conversion performed while {@link
+   * Charset.saveLast} 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.
+   *
+   * This property is read-only.
+   */
+  readonly lastInputAsHex: string
+
+  /**
+   * Returns the input bytes captured for the most recent conversion performed while {@link
+   * Charset.saveLast} 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.
+   *
+   * This property is read-only.
+   */
+  readonly lastInputAsQP: string
+
+  /**
+   * Returns the output bytes captured for the most recent conversion performed while {@link
+   * Charset.saveLast} 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.
+   *
+   * This property is read-only.
+   */
+  readonly lastOutputAsHex: string
+
+  /**
+   * Returns the output bytes captured for the most recent conversion performed while {@link
+   * Charset.saveLast} 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.
+   *
+   * This property is read-only.
+   */
+  readonly lastOutputAsQP: string
+
+  /**
+   * When `true`, retains the input and output byte sequences from each conversion so they can be
+   * inspected through {@link Charset.lastInputAsHex}, {@link Charset.lastInputAsQP}, {@link
+   * Charset.lastOutputAsHex}, and {@link Charset.lastOutputAsQP}.
+   *
+   * **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.
+   */
+  saveLast: boolean
+
+  /**
+   * Specifies the destination character encoding for conversion operations. After decoding the
+   * source bytes using {@link Charset.fromCharset}, Chilkat encodes the resulting Unicode text in
+   * this charset.
+   *
+   * FamilyRecognized 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; {@link
+   * Charset.errorAction} controls how such conversion failures are handled.
+   */
+  toCharset: string
+
+  // ---- Methods ----
+
+  /**
+   * 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.
+   */
+  charsetToCodePage(charsetName: string): number
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Charset.lastErrorText}.
+   */
+  codePageToCharset(codePage: number): string
+
+  /**
+   * Reads the file at `inPath`, converts its text from {@link Charset.fromCharset} to {@link
+   * Charset.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 {@link Charset.convertFileNoPreamble}
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Charset.lastErrorText}.
+   */
+  convertFile(inPath: string, destPath: string): void
+
+  /**
+   * Reads the file at `inPath`, converts its text from {@link Charset.fromCharset} to {@link
+   * Charset.toCharset}, 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Charset.lastErrorText}.
+   */
+  convertFileNoPreamble(inPath: string, destPath: string): void
+
+  /**
+   * Converts the HTML file at `inPath` to {@link Charset.toCharset} and writes the result to
+   * `destPath`. Chilkat also updates the HTML `<meta>` charset declaration to identify the
+   * destination encoding.
+   *
+   * If {@link Charset.fromCharset} 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Charset.lastErrorText}.
+   */
+  convertHtmlFile(inPath: string, destPath: string): void
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Charset.lastErrorText}.
+   */
+  entityEncodeDec(str: string): string
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Charset.lastErrorText}.
+   */
+  entityEncodeHex(str: string): string
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Charset.lastErrorText}.
+   */
+  getHtmlFileCharset(htmlFilePath: string): string
+
+  /**
+   * 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 `&`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Charset.lastErrorText}.
+   */
+  htmlDecodeToStr(inStr: string): string
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Charset.lastErrorText}.
+   */
+  htmlEntityDecodeFile(inPath: string, destPath: string): void
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Charset.lastErrorText}.
+   */
+  lowerCase(inStr: string): string
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Charset.lastErrorText}.
+   */
+  readFileToString(path: string, charset: string): string
+
+  /**
+   * Configures the replacement used when {@link Charset.errorAction} 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.
+   */
+  setErrorString(str: string, charset: string): void
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Charset.lastErrorText}.
+   */
+  upperCase(inStr: string): string
+
+  /**
+   * 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`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Charset.lastErrorText}.
+   */
+  urlDecodeStr(inStr: string): string
+
+  /**
+   * 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.
+   */
+  verifyFile(charset: string, path: string): boolean
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Charset.lastErrorText}.
+   */
+  writeStringToFile(textData: string, path: string, charset: string): void
+}