@chilkat/react-native 11.6.1

package/src/specs/StringArray.nitro.ts

@@ -0,0 +1,396 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+
+/**
+ * Manage an ordered collection of strings, with StringTable recommended for new code.
+ *
+ * `StringArray` is an ordered string-collection class that
+ * can append, prepend, insert, replace, remove, pop, and retrieve strings by
+ * index. It can load one string per line from files or in-memory text, save the
+ * collection back to text or files, enforce uniqueness, trim incoming values,
+ * normalize line endings, search by exact value or wildcard pattern, sort
+ * entries, split text into entries, serialize and restore the collection, and
+ * perform set-style operations such as union and subtraction.
+ *
+ * **Recommendation:**
+ * For new development, prefer `Chilkat.StringTable` instead of
+ * `StringArray`. `StringTable` provides a simpler,
+ * faster, and more memory-efficient way to manage ordered lists of strings.
+ * Use `StringArray` primarily when maintaining existing code or when
+ * a specific API or older example already uses it.
+ *
+ * **Ordered string collection**
+ *
+ * Store strings in an internal ordered collection and retrieve them by
+ * zero-based index using `GetString`, `StrAt`, or
+ * `LastString`.
+ *
+ * **Add and modify entries**
+ *
+ * Append, prepend, insert, replace, remove, clear, or pop strings as the
+ * collection changes.
+ *
+ * **Load and save text**
+ *
+ * Load one string per line from files or text, and save the collection back
+ * to files or a single line-delimited string.
+ *
+ * **Charset-aware file I/O**
+ *
+ * Use charset-specific load and save methods when working with UTF-8,
+ * UTF-16, or other non-ANSI text encodings.
+ *
+ * **Search, match, and sort**
+ *
+ * Check for exact strings, find values from a starting index, match
+ * wildcard patterns, and sort ascending or descending.
+ *
+ * **Serialize and combine**
+ *
+ * Serialize the collection for later restoration, split text into entries,
+ * and combine or subtract collections with set-style operations.
+ *
+ * **Common pattern:**
+ * Create a `StringArray`, optionally set `Trim`,
+ * `Crlf`, or `Unique`, then append strings directly or
+ * load them from a file or text block. Search, sort, split, remove, union, or
+ * subtract entries as needed, then save the result with
+ * `SaveToText`, `SaveToFile`, or
+ * `SaveToFile2`. For new code that only needs an ordered list of
+ * strings, use `Chilkat.StringTable` instead.
+ *
+ * **Naming note:**
+ * Although the class name contains `Array`,
+ * `StringArray` is a Chilkat object that manages an ordered
+ * string collection. It should not be confused with a native array type in a
+ * programming language.
+ *
+ * Each `StringArray` 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 StringArray()`.
+ */
+export interface StringArray 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
+
+  /**
+   * The number of strings contained within the object's internal array (i.e. ordered collection).
+   *
+   * **Important:** This is an object that contains a collection of strings. Although the
+   * class/object name includes the word `Array`, it should not be confused with an array in the
+   * sense of the primitive array type used in a given programming language.
+   *
+   * This property is read-only.
+   */
+  readonly count: number
+
+  /**
+   * If `true`, strings are always automatically converted to use CRLF line endings. If `false`,
+   * strings are automatically converted to use bare LF line endings.
+   */
+  crlf: boolean
+
+  /**
+   * The number of strings contained within the internal collection. (Identical to the Count
+   * property.)
+   *
+   * This property is read-only.
+   */
+  readonly length: number
+
+  /**
+   * If `true`, whitespace, including carriage-returns and linefeeds, are automatically removed from
+   * the beginning and end of a string when added to the collection.
+   */
+  trim: boolean
+
+  /**
+   * If `true`, then duplicates are not allowed. When an attempt is made to insert a string that
+   * already exists, the duplicate insertion is silently suppressed and no error is returned. The
+   * default value is `false`.
+   */
+  unique: boolean
+
+  // ---- Methods ----
+
+  /**
+   * Appends a string to the end of the internal ordered collection.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link StringArray.lastErrorText}.
+   */
+  append(str: string): void
+
+  /**
+   * Appends multiple strings to the end of the internal ordered collection. The `encodedStr` is
+   * what is returned from the Serialize method (see below).
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link StringArray.lastErrorText}.
+   */
+  appendSerialized(encodedStr: string): void
+
+  /**
+   * Remove all strings from the internal collection.
+   */
+  clear(): void
+
+  /**
+   * Returns `true` if the string is present in the internal collection. The string comparisons are
+   * case sensitive.
+   */
+  contains(str: string): boolean
+
+  /**
+   * Finds the index of the first string equal to `findStr`. The search begins at `startIndex`. If
+   * the string is not found, -1 is returned. The first string in the array is at index 0.
+   */
+  find(findStr: string, startIndex: number): number
+
+  /**
+   * Finds the first string that matches the `matchPattern`. The search begins at `startIndex`. If
+   * the string is not found, -1 is returned. The first string in the array is at index 0.
+   *
+   * The `matchPattern` may contain zero or more asterisk chars, each of which matches 0 or more of
+   * any character.
+   */
+  findFirstMatch(matchPattern: string, startIndex: number): number
+
+  /**
+   * Returns the string at an indexed location within the internal collection. The first string is
+   * located at index 0.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link StringArray.lastErrorText}.
+   */
+  getString(index: number): string
+
+  /**
+   * Returns Nth string's length, in characters. The first string is located at index 0.
+   */
+  getStringLen(index: number): number
+
+  /**
+   * Inserts a string into the internal collection at a specified index. Using index 0 will insert
+   * at the beginning.
+   */
+  insertAt(index: number, str: string): void
+
+  /**
+   * Returns the last string in the internal collection.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link StringArray.lastErrorText}.
+   */
+  lastString(): string
+
+  /**
+   * Loads strings from a file (one per line) into the internal collection. It is assumed the file
+   * contains ANSI strings. To load from a file containing non-ANSI strings (such as utf-8), call
+   * LoadFromFile2 instead.
+   *
+   * **Note:** This method appends the strings in `path` to the existing collection of strings
+   * contained in this object.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link StringArray.lastErrorText}.
+   */
+  loadFromFile(path: string): void
+
+  /**
+   * Loads strings from a file (one per line) into the internal collection. The `charset` specifies
+   * the character encoding (such as utf-8) of the strings contained in the file.
+   *
+   * **Note:** This method appends the strings in `path` to the existing collection of strings
+   * contained in this object.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link StringArray.lastErrorText}.
+   */
+  loadFromFile2(path: string, charset: string): void
+
+  /**
+   * Loads strings from an in-memory string (one per line) into the internal collection.
+   *
+   * **Note:** This method appends the strings in `str` to the existing collection of strings
+   * contained in this object.
+   */
+  loadFromText(str: string): void
+
+  /**
+   * Returns the last string and removes it from the internal collection.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link StringArray.lastErrorText}.
+   */
+  pop(): string
+
+  /**
+   * Adds a string to the beginning of the internal collection.
+   */
+  prepend(str: string): void
+
+  /**
+   * Removes all strings equal to the string argument from the internal collection.
+   */
+  remove(str: string): void
+
+  /**
+   * Removes the string at a particular index.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link StringArray.lastErrorText}.
+   */
+  removeAt(index: number): void
+
+  /**
+   * Replaces the string at a specified index.
+   */
+  replaceAt(index: number, str: string): void
+
+  /**
+   * Saves the Nth string in the collection  to a file.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link StringArray.lastErrorText}.
+   */
+  saveNthToFile(index: number, saveToPath: string): void
+
+  /**
+   * Saves the collection of strings to a file, one string per line. Strings are saved using the
+   * ANSI charset. (Call SaveToFile2 to specify a charset, such as `utf-8`)
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link StringArray.lastErrorText}.
+   */
+  saveToFile(path: string): void
+
+  /**
+   * Saves the collection of strings to a file, one string per line. Strings are saved using the
+   * specified `charset`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link StringArray.lastErrorText}.
+   */
+  saveToFile2(saveToPath: string, charset: string): void
+
+  /**
+   * Writes the collection of strings to a single string, one per line (separated by CRLF line
+   * endings).
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link StringArray.lastErrorText}.
+   */
+  saveToText(): string
+
+  /**
+   * Returns an string which is an encoded representation of all the strings in the collection. The
+   * string collection can be re-created by calling the AppendSerialized method.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link StringArray.lastErrorText}.
+   */
+  serialize(): string
+
+  /**
+   * Sorts the strings in the collection in ascending or descending order. To sort in ascending
+   * order, set `ascending` to `true`, otherwise set `ascending` equal to `false`.
+   */
+  sort(ascending: boolean): void
+
+  /**
+   * Splits a string at a character or substring boundary and adds each resulting string to the
+   * internal collection.
+   */
+  splitAndAppend(str: string, boundary: string): void
+
+  /**
+   * Returns the string at a specific index.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link StringArray.lastErrorText}.
+   */
+  strAt(index: number): string
+
+  /**
+   * Subtracts the strings contained within `stringArrayObj` from the caller's internal collection.
+   */
+  subtract(stringArrayObj: StringArray): void
+
+  /**
+   * Performs the union set-operator. The result is that the caller will have a string collection
+   * that is the union of itself and `stringArrayObj`.
+   */
+  unionWith(stringArrayObj: StringArray): void
+}