@chilkat/react-native 11.6.1

package/src/specs/JsonArray.nitro.ts

@@ -0,0 +1,681 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { CkDateTime } from './CkDateTime.nitro'
+import type { DtObj } from './DtObj.nitro'
+import type { JsonObject } from './JsonObject.nitro'
+import type { StringBuilder } from './StringBuilder.nitro'
+
+/**
+ * Read, modify, search, and emit ordered JSON arrays.
+ *
+ * `JsonArray` is the JSON array companion to
+ * `Chilkat.JsonObject`. It represents an ordered list of JSON values
+ * and provides index-based methods for reading, inserting, replacing, deleting,
+ * swapping, searching, and emitting array data. It supports scalar values,
+ * nested objects, nested arrays, date/time parsing, exact numeric string
+ * handling, compact or pretty output, and search helpers for arrays of strings
+ * or arrays of objects.
+ *
+ * **Ordered JSON values**
+ *
+ * Work with JSON arrays as ordered lists containing strings, numbers,
+ * booleans, nulls, objects, arrays, and mixed value types.
+ *
+ * **Index-based access**
+ *
+ * Retrieve, insert, replace, delete, or swap values by array index when
+ * processing JSON list data.
+ *
+ * **Nested objects and arrays**
+ *
+ * Access child `JsonObject` and `JsonArray` values to
+ * navigate and modify deeper JSON structures.
+ *
+ * **Search helpers**
+ *
+ * Search arrays of strings or arrays of objects to locate matching values
+ * without manually scanning every element.
+ *
+ * **Date and numeric handling**
+ *
+ * Parse date/time values and preserve exact numeric strings when JSON data
+ * contains values that must not be rounded or reformatted.
+ *
+ * **Emit JSON output**
+ *
+ * Produce compact or pretty JSON output after array data has been loaded,
+ * edited, searched, or built programmatically.
+ *
+ * **Common pattern:**
+ * Use `JsonObject` to navigate named members and JSON paths, then
+ * use `JsonArray` to iterate or modify ordered lists found within
+ * the object tree. Retrieve nested objects or arrays as needed, update values
+ * by index, and emit the final JSON in compact or pretty form.
+ *
+ * For an extended overview, see
+ * [JsonArray Class Overview](https://www.chilkatsoft.com/jsonarray_class_overview.asp).
+ *
+ * Each `JsonArray` 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 JsonArray()`.
+ */
+export interface JsonArray 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
+
+  /**
+   * Returns the number of values currently contained in the JSON array. Array indexes therefore
+   * range from `0` through `Size - 1`.
+   *
+   * This property is read-only.
+   */
+  readonly size: number
+
+  /**
+   * Controls line endings when pretty-formatted JSON is emitted. If `true`, line breaks use CRLF
+   * (); if `false`, they use LF (). The default is `true`.
+   *
+   * **Applies only to pretty output:** When `EmitCompact` is `true`, the JSON is emitted on one
+   * line and this setting has no effect.
+   */
+  emitCrlf: boolean
+
+  /**
+   * Controls whether emitted JSON is compact or pretty-formatted. If `true`, output contains no
+   * unnecessary whitespace and is emitted on a single line. If `false`, indentation and line breaks
+   * are added for readability. The default is `true`.
+   */
+  emitCompact: boolean
+
+  /**
+   * Specifies the zero-based array index at which `FindString` and `FindObject` begin searching.
+   * The default value is `0`.
+   *
+   * **Iterating matches:** After finding a match at index `n`, set this property to `n + 1` before
+   * the next search to continue with later elements.
+   */
+  findStartIndex: number
+
+  // ---- Methods ----
+
+  /**
+   * Inserts a new, empty JSON array at zero-based position `index`. Existing elements at that
+   * position and after it are shifted one position toward the end of the array.
+   *
+   * | `0` |  | Insert as the first array element. |
+   *
+   * | `-1` |  | Append as the last array element. |
+   *
+   * | `n` |  | Insert at zero-based position n. |
+   *
+   * **Insert vs. replace:** The `Add*At` methods insert a new array element. Use the corresponding
+   * `Set*At` method when replacing an existing element.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  addArrayAt(index: number): void
+
+  /**
+   * Inserts a new JSON boolean value at zero-based position `index`. Existing elements at that
+   * position and after it are shifted one position toward the end of the array.
+   *
+   * | `0` |  | Insert as the first array element. |
+   *
+   * | `-1` |  | Append as the last array element. |
+   *
+   * | `n` |  | Insert at zero-based position n. |
+   *
+   * **Insert vs. replace:** The `Add*At` methods insert a new array element. Use the corresponding
+   * `Set*At` method when replacing an existing element.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  addBoolAt(index: number, value: boolean): void
+
+  /**
+   * Inserts a new JSON integer value at zero-based position `index`. Existing elements at that
+   * position and after it are shifted one position toward the end of the array.
+   *
+   * | `0` |  | Insert as the first array element. |
+   *
+   * | `-1` |  | Append as the last array element. |
+   *
+   * | `n` |  | Insert at zero-based position n. |
+   *
+   * **Insert vs. replace:** The `Add*At` methods insert a new array element. Use the corresponding
+   * `Set*At` method when replacing an existing element.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  addIntAt(index: number, value: number): void
+
+  /**
+   * Inserts a JSON `null` value at zero-based position `index`. Existing elements at that position
+   * and after it are shifted one position toward the end of the array.
+   *
+   * | `0` |  | Insert as the first array element. |
+   *
+   * | `-1` |  | Append as the last array element. |
+   *
+   * | `n` |  | Insert at zero-based position n. |
+   *
+   * **Insert vs. replace:** The `Add*At` methods insert a new array element. Use the corresponding
+   * `Set*At` method when replacing an existing element.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  addNullAt(index: number): void
+
+  /**
+   * Inserts a JSON number at zero-based position `index`. The `numericStr` argument supplies the
+   * exact JSON numeric text to store. Existing elements at that position and after it are shifted
+   * one position toward the end of the array.
+   *
+   * | `0` |  | Insert as the first array element. |
+   *
+   * | `-1` |  | Append as the last array element. |
+   *
+   * | `n` |  | Insert at zero-based position n. |
+   *
+   * **Exact numeric text:** Use this method when lexical form or precision matters, for example
+   * `12345678901234567890`, `1.2500`, or scientific notation. The supplied text must be valid JSON
+   * number syntax; JSON does not permit `NaN` or infinity.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  addNumberAt(index: number, numericStr: string): void
+
+  /**
+   * Inserts a new, empty JSON object at zero-based position `index`. Existing elements at that
+   * position and after it are shifted one position toward the end of the array.
+   *
+   * | `0` |  | Insert as the first array element. |
+   *
+   * | `-1` |  | Append as the last array element. |
+   *
+   * | `n` |  | Insert at zero-based position n. |
+   *
+   * **Insert vs. replace:** The `Add*At` methods insert a new array element. Use the corresponding
+   * `Set*At` method when replacing an existing element.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  addObjectAt(index: number): void
+
+  /**
+   * Inserts a new JSON string value at zero-based position `index`. Existing elements at that
+   * position and after it are shifted one position toward the end of the array.
+   *
+   * | `0` |  | Insert as the first array element. |
+   *
+   * | `-1` |  | Append as the last array element. |
+   *
+   * | `n` |  | Insert at zero-based position n. |
+   *
+   * **Insert vs. replace:** The `Add*At` methods insert a new array element. Use the corresponding
+   * `Set*At` method when replacing an existing element.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  addStringAt(index: number, value: string): void
+
+  /**
+   * Returns the nested JSON array stored at zero-based position `index`.
+   *
+   * **Reference, not copy:** The returned `JsonArray` refers to the existing nested array in the
+   * same JSON document. Changes made through the returned object modify that nested array.
+   *
+   * **Type requirement:** The value at `index` must be an array. Use `TypeAt` when the value type
+   * is not already known.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  arrayAt(index: number): JsonArray
+
+  /**
+   * Returns the boolean value stored at zero-based position `index`.
+   *
+   * **Type-aware access:** Use `TypeAt` when the JSON type at `index` is not already known.
+   */
+  boolAt(index: number): boolean
+
+  /**
+   * Deletes the value at zero-based position `index`. Elements following the deleted value shift
+   * down by one position.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  deleteAt(index: number): void
+
+  /**
+   * Returns the integer value stored at zero-based position `index`.
+   *
+   * **Type-aware access:** Use `TypeAt` when the JSON type at `index` is not already known.
+   */
+  intAt(index: number): number
+
+  /**
+   * Returns `true` if the value at zero-based position `index` is the JSON value `null`; otherwise
+   * returns `false`.
+   *
+   * **JSON null:** `null` is a distinct JSON value. It is not the same as an empty string, zero,
+   * `false`, an empty object, or an empty array.
+   */
+  isNullAt(index: number): boolean
+
+  /**
+   * Returns the JSON object stored at zero-based position `index`.
+   *
+   * **Reference, not copy:** The returned `JsonObject` refers to the existing object in the same
+   * JSON document. Changes made through the returned object modify that nested object.
+   *
+   * **Type requirement:** The value at `index` must be an object. Use `TypeAt` when the value type
+   * is not already known.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  objectAt(index: number): JsonObject
+
+  /**
+   * Replaces the value at zero-based position `index` with the specified JSON boolean value. The
+   * array length and the positions of other elements are unchanged.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  setBoolAt(index: number, value: boolean): void
+
+  /**
+   * Replaces the value at zero-based position `index` with the specified JSON integer value. The
+   * array length and the positions of other elements are unchanged.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  setIntAt(index: number, value: number): void
+
+  /**
+   * Replaces the value at zero-based position `index` with the JSON value `null`. The array length
+   * and the positions of other elements are unchanged.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  setNullAt(index: number): void
+
+  /**
+   * Replaces the value at zero-based position `index` with a JSON number. The `value` argument
+   * supplies the exact JSON numeric text to store.
+   *
+   * **Exact numeric text:** Use this method when lexical form or precision matters. The supplied
+   * text must be valid JSON number syntax; JSON does not permit `NaN` or infinity.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  setNumberAt(index: number, value: string): void
+
+  /**
+   * Replaces the value at zero-based position `index` with the specified JSON string value. The
+   * array length and the positions of other elements are unchanged.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  setStringAt(index: number, value: string): void
+
+  /**
+   * Returns the string value stored at zero-based position `index`.
+   *
+   * **Type-aware access:** Use `TypeAt` when the JSON type at `index` is not already known.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  stringAt(index: number): string
+
+  /**
+   * Serializes this JSON array and returns the resulting JSON text.
+   *
+   * **Formatting:** Set `EmitCompact` to choose compact versus pretty output. When pretty output is
+   * enabled, `EmitCrlf` selects CRLF or LF line endings.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  emit(): string
+
+  /**
+   * Returns an integer identifying the JSON type of the value at zero-based position `index`.
+   * Returns `-1` if no value exists at that index.
+   *
+   * | `1` |  | string |
+   *
+   * | `2` |  | number |
+   *
+   * | `3` |  | object |
+   *
+   * | `4` |  | array |
+   *
+   * | `5` |  | boolean |
+   *
+   * | `6` |  | null |
+   *
+   * **Why use TypeAt:** JSON arrays may contain mixed types. Checking the type first avoids
+   * choosing a type-specific accessor such as `ObjectAt`, `ArrayAt`, or `IntAt` for the wrong kind
+   * of value.
+   */
+  typeAt(index: number): number
+
+  /**
+   * Parses the JSON array contained in `sb` and loads it into this object. The input must represent
+   * a JSON array, beginning with `[` and ending with `]`.
+   *
+   * **Important — loading detaches the array:** Calling this method makes the `JsonArray` its own
+   * independent JSON document. If the object previously referenced an array nested inside another
+   * JSON document, that relationship is discarded. For this reason, call `Load`/`LoadSb` on a new
+   * `JsonArray` instance.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  loadSb(sb: StringBuilder): void
+
+  /**
+   * Parses the JSON array text in `jsonArray` and loads it into this object. The input must
+   * represent a JSON array, beginning with `[` and ending with `]`.
+   *
+   * **Important — loading detaches the array:** Calling this method makes the `JsonArray` its own
+   * independent JSON document. If the object previously referenced an array nested inside another
+   * JSON document, that relationship is discarded. For this reason, call `Load`/`LoadSb` on a new
+   * `JsonArray` instance.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  load(jsonArray: string): void
+
+  /**
+   * Serializes this JSON array into the supplied `StringBuilder`.
+   *
+   * **Formatting:** Set `EmitCompact` to choose compact versus pretty output. When pretty output is
+   * enabled, `EmitCrlf` selects CRLF or LF line endings.
+   *
+   * **Large JSON:** Using a `StringBuilder` can avoid returning a very large JSON document as a
+   * language-native string before passing it to another Chilkat method or writing it to a file.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  emitSb(sb: StringBuilder): void
+
+  /**
+   * Parses the date/time value at zero-based position `index` and loads the result into `dt`.
+   * Recognized forms include ISO 8601 timestamps (for example, `2009-11-04T19:55:41Z`), RFC
+   * 822-style date/time strings, and Unix timestamp integers.
+   *
+   * **JSON has no native date type:** Dates are application conventions represented as strings or
+   * numbers. These methods recognize common representations and convert them to Chilkat date/time
+   * objects.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  dateAt(index: number, dt: CkDateTime): void
+
+  /**
+   * Parses the date/time value at zero-based position `index` and loads the result into `dt`. If
+   * `bLocal` is `true`, the populated fields represent local time; if `false`, they represent
+   * UTC/GMT. Recognized forms include ISO 8601 timestamps, RFC 822-style date/time strings, and
+   * Unix timestamp integers.
+   *
+   * **JSON has no native date type:** Dates are application conventions represented as strings or
+   * numbers. These methods recognize common representations and convert them to Chilkat date/time
+   * objects.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  dtAt(index: number, bLocal: boolean, dt: DtObj): void
+
+  /**
+   * Searches for the first string array element matching `value` and returns its zero-based index,
+   * or `-1` if no match is found. The pattern may contain `*`, which matches zero or more
+   * characters. Set `caseSensitive` to control whether letter case must match.
+   *
+   * **Search start:** Searching begins at `FindStartIndex`, whose default is `0`. To continue
+   * searching after a match, set `FindStartIndex` to the previous returned index plus 1.
+   */
+  findString(value: string, caseSensitive: boolean): number
+
+  /**
+   * Searches array elements that are JSON objects and returns the zero-based index of the first
+   * object whose direct member `name` has a value matching `value`. Returns `-1` if no match is
+   * found. The value pattern may contain `*`, which matches zero or more characters. Set
+   * `caseSensitive` to control whether letter case must match.
+   *
+   * **Member name, not JSON path:** `name` identifies a direct member of each object being tested;
+   * it is not a JSON path.
+   *
+   * **Search start:** Searching begins at `FindStartIndex`, whose default is `0`. To continue
+   * searching after a match, set `FindStartIndex` to the previous returned index plus 1.
+   */
+  findObject(name: string, value: string, caseSensitive: boolean): number
+
+  /**
+   * Exchanges the values at zero-based positions `index1` and `index2`. The array length does not
+   * change.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  swap(index1: number, index2: number): void
+
+  /**
+   * Removes all values from the array, leaving an empty JSON array (`[]`).
+   */
+  clear(): void
+
+  /**
+   * Appends copies of all values from `jarr` to the end of this array, preserving their order.
+   *
+   * **Source is unchanged:** The source array is not emptied or moved. This method is useful for
+   * concatenating JSON arrays, including arrays belonging to different JSON documents.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  appendArrayItems(jarr: JsonArray): void
+
+  /**
+   * Inserts an independent copy of `jsonObj` at zero-based position `index`. Existing elements at
+   * that position and after it are shifted one position toward the end of the array.
+   *
+   * | `0` |  | Insert as the first array element. |
+   *
+   * | `-1` |  | Append as the last array element. |
+   *
+   * | `n` |  | Insert at zero-based position n. |
+   *
+   * **Copy semantics:** The inserted object is copied rather than referenced. Later changes to the
+   * source `jsonObj` do not serve as edits to the inserted array value.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  addObjectCopyAt(index: number, jsonObj: JsonObject): void
+
+  /**
+   * Returns the unsigned integer value stored at zero-based position `index`.
+   *
+   * **Type-aware access:** Use `TypeAt` when the JSON type at `index` is not already known.
+   */
+  uIntAt(index: number): number
+
+  /**
+   * Inserts a new JSON unsigned integer value at zero-based position `index`. Existing elements at
+   * that position and after it are shifted one position toward the end of the array.
+   *
+   * | `0` |  | Insert as the first array element. |
+   *
+   * | `-1` |  | Append as the last array element. |
+   *
+   * | `n` |  | Insert at zero-based position n. |
+   *
+   * **Insert vs. replace:** The `Add*At` methods insert a new array element. Use the corresponding
+   * `Set*At` method when replacing an existing element.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  addUIntAt(index: number, value: number): void
+
+  /**
+   * Replaces the value at zero-based position `index` with the specified JSON unsigned integer
+   * value. The array length and the positions of other elements are unchanged.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  setUIntAt(index: number, value: number): void
+
+  /**
+   * Updates `jarr` so that it references the nested JSON array stored at zero-based position
+   * `index`.
+   *
+   * **Reference, not copy:** Changes made through `jarr` modify the existing nested array in the
+   * same JSON document.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  arrayAt2(index: number, jarr: JsonArray): void
+
+  /**
+   * Updates `jsonObj` so that it references the JSON object stored at zero-based position `index`.
+   *
+   * **Reference, not copy:** Changes made through `jsonObj` modify the existing object in the same
+   * JSON document.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  objectAt2(index: number, jsonObj: JsonObject): void
+
+  /**
+   * Inserts a new, empty JSON array at zero-based position `index` and updates `jarr` to reference
+   * the newly inserted array.
+   *
+   * | `0` |  | Insert as the first array element. |
+   *
+   * | `-1` |  | Append as the last array element. |
+   *
+   * | `n` |  | Insert at zero-based position n. |
+   *
+   * **Immediate editing:** Because `jarr` references the inserted array, it can be populated
+   * directly without a separate `ArrayAt` lookup.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  addArrayAt2(index: number, jarr: JsonArray): void
+
+  /**
+   * Inserts a new, empty JSON object at zero-based position `index` and updates `json` to reference
+   * the newly inserted object.
+   *
+   * | `0` |  | Insert as the first array element. |
+   *
+   * | `-1` |  | Append as the last array element. |
+   *
+   * | `n` |  | Insert at zero-based position n. |
+   *
+   * **Immediate editing:** Because `json` references the inserted object, it can be populated
+   * directly without a separate `ObjectAt` lookup.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link JsonArray.lastErrorText}.
+   */
+  addObjectAt2(index: number, json: JsonObject): void
+}