JsonArray Rust Reference Documentation

JsonArray

Current Version: 11.6.1

Chilkat.JsonArray

Read, modify, search, and emit ordered JSON arrays.

Chilkat.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.

Object Creation

// Cargo.toml:
//     [dependencies]
//     chilkat = "11.6"

use chilkat::JsonArray;

// Once per process, before any other Chilkat call:
chilkat::unlock_bundle("Anything for 30-day trial")?;  // shorthand for Global::new().unlock_bundle(..)

let json_array = JsonArray::new();
// ... the native object is freed when `json_array` goes out of scope.
pub fn new() -> JsonArray

Creates the underlying native Chilkat object (JsonArray also implements Default). Every method takes &self, so the object never needs to be declared mut. A JsonArray is Send but not Sync: it may be moved to another thread, but a reference to it cannot be shared between threads at the same time.

impl Drop for JsonArray

The native object is freed when the JsonArray is dropped — when it goes out of scope, or explicitly with drop(json_array). There is no Dispose method to call.

Errors

Methods that can fail return chilkat::Result<T>, which is Result<T, chilkat::Error>: a method whose only outcome is success or failure returns Result<()>, a method producing a string or an object returns Result<String> or Result<JsonArray>. The error carries the object's LastErrorText at the time of the failure (Error::last_error_text), the class and method names, and implements std::error::Error, so ? works in any function returning chilkat::Result or a Box<dyn Error>. Properties never fail, and methods that answer a question (has_..., is_..., ...) return a plain bool.

match json_array.some_method(...) {
    Ok(value) => println!("{value:?}"),
    Err(e) => eprintln!("{}", e.last_error_text()),
}

Properties

DebugLogFilePath
// read/write
pub fn debug_log_file_path(&self) -> String
pub fn set_debug_log_file_path(&self, value: &str)

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.

More Information and Examples
Example showing how to use DebugLogFilePath.
top
EmitCompact
// read/write
pub fn emit_compact(&self) -> bool
pub fn set_emit_compact(&self, value: bool)
Introduced in version 9.5.0.64

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.

top
EmitCrlf
// read/write
pub fn emit_crlf(&self) -> bool
pub fn set_emit_crlf(&self, value: bool)
Introduced in version 9.5.0.64

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.

top
FindStartIndex
// read/write
pub fn find_start_index(&self) -> i32
pub fn set_find_start_index(&self, value: i32)
Introduced in version 11.6.0

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.

top
LastErrorHtml
// read-only
pub fn last_error_html(&self) -> String

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.

top
LastErrorText
// read-only
pub fn last_error_text(&self) -> 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.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
// read-only
pub fn last_error_xml(&self) -> 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.

top
LastMethodSuccess
// read/write
pub fn last_method_success(&self) -> bool
pub fn set_last_method_success(&self, value: bool)

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.

top
Size
// read-only
pub fn size(&self) -> i32
Introduced in version 9.5.0.56

Returns the number of values currently contained in the JSON array. Array indexes therefore range from 0 through Size - 1.

top
VerboseLogging
// read/write
pub fn verbose_logging(&self) -> bool
pub fn set_verbose_logging(&self, value: bool)

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.

top
Version
// read-only
pub fn version(&self) -> String

Version of the component/library, such as "10.1.0"

More Information and Examples
How to get the Chilkat version at runtime.
top

Methods

AddArrayAt
pub fn add_array_at(&self, index: i32) -> Result<()>
Introduced in version 9.5.0.56

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.

0Insert as the first array element.
-1Append as the last array element.
nInsert 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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Modify Parts of JSON Document
top
AddArrayAt2
pub fn add_array_at2(&self, index: i32, jarr: &JsonArray) -> Result<()>
Introduced in version 11.1.0

Inserts a new, empty JSON array at zero-based position index and updates jarr to reference the newly inserted array.

0Insert as the first array element.
-1Append as the last array element.
nInsert at zero-based position n.
Immediate editing: Because jarr references the inserted array, it can be populated directly without a separate ArrayAt lookup.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
AddBoolAt
pub fn add_bool_at(&self, index: i32, value: bool) -> Result<()>
Introduced in version 9.5.0.56

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.

0Insert as the first array element.
-1Append as the last array element.
nInsert 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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Modify Parts of JSON Document
top
AddIntAt
pub fn add_int_at(&self, index: i32, value: i32) -> Result<()>
Introduced in version 9.5.0.56

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.

0Insert as the first array element.
-1Append as the last array element.
nInsert 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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Modify Parts of JSON Document
top
AddNullAt
pub fn add_null_at(&self, index: i32) -> Result<()>
Introduced in version 9.5.0.56

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.

0Insert as the first array element.
-1Append as the last array element.
nInsert 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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Modify Parts of JSON Document
top
AddNumberAt
pub fn add_number_at(&self, index: i32, numeric_str: &str) -> Result<()>
Introduced in version 9.5.0.56

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.

0Insert as the first array element.
-1Append as the last array element.
nInsert 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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Create more Complex JSON DocumentModify Parts of JSON Document
top
AddObjectAt
pub fn add_object_at(&self, index: i32) -> Result<()>
Introduced in version 9.5.0.56

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.

0Insert as the first array element.
-1Append as the last array element.
nInsert 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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Create more Complex JSON DocumentModify Parts of JSON Document
top
AddObjectAt2
pub fn add_object_at2(&self, index: i32, json: &JsonObject) -> Result<()>
Introduced in version 11.1.0

Inserts a new, empty JSON object at zero-based position index and updates json to reference the newly inserted object.

0Insert as the first array element.
-1Append as the last array element.
nInsert at zero-based position n.
Immediate editing: Because json references the inserted object, it can be populated directly without a separate ObjectAt lookup.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
AddObjectCopyAt
pub fn add_object_copy_at(&self, index: i32, json_obj: &JsonObject) -> Result<()>
Introduced in version 9.5.0.82

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.

0Insert as the first array element.
-1Append as the last array element.
nInsert 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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
JSON Array AddObjectCopyAt Example
top
AddStringAt
pub fn add_string_at(&self, index: i32, value: &str) -> Result<()>
Introduced in version 9.5.0.56

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.

0Insert as the first array element.
-1Append as the last array element.
nInsert 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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Create more Complex JSON DocumentModify Parts of JSON Document
top
AddUIntAt
pub fn add_u_int_at(&self, index: i32, value: u32) -> Result<()>
Introduced in version 9.5.0.96

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.

0Insert as the first array element.
-1Append as the last array element.
nInsert 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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
AppendArrayItems
pub fn append_array_items(&self, jarr: &JsonArray) -> Result<()>
Introduced in version 9.5.0.82

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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
AppendArrayItems Example
top
ArrayAt
pub fn array_at(&self, index: i32) -> Result<JsonArray>
Introduced in version 9.5.0.56

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.

Returns Err(chilkat::Error) on failure.

More Information and Examples
JSON: Nested Array
top
ArrayAt2
pub fn array_at2(&self, index: i32, jarr: &JsonArray) -> Result<()>
Introduced in version 11.0.0

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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
BoolAt
pub fn bool_at(&self, index: i32) -> bool
Introduced in version 9.5.0.56

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.
top
Clear
pub fn clear(&self)
Introduced in version 9.5.0.76

Removes all values from the array, leaving an empty JSON array ([]).

top
DateAt
pub fn date_at(&self, index: i32, dt: &DateTime) -> Result<()>
Introduced in version 9.5.0.73

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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
DeleteAt
pub fn delete_at(&self, index: i32) -> Result<()>
Introduced in version 9.5.0.56

Deletes the value at zero-based position index. Elements following the deleted value shift down by one position.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Modify Parts of JSON Document
top
DtAt
pub fn dt_at(&self, index: i32, b_local: bool, dt: &DtObj) -> Result<()>
Introduced in version 9.5.0.73

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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
Emit
pub fn emit(&self) -> Result<String>
Introduced in version 9.5.0.58

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.

Returns Err(chilkat::Error) on failure.

top
EmitSb
pub fn emit_sb(&self, sb: &StringBuilder) -> Result<()>
Introduced in version 9.5.0.65

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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Emit JSON Array to StringBuilder
top
FindObject
pub fn find_object(&self, name: &str, value: &str, case_sensitive: bool) -> i32
Introduced in version 9.5.0.73

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.
More Information and Examples
Find and Delete Object from JSON Array
top
FindString
pub fn find_string(&self, value: &str, case_sensitive: bool) -> i32
Introduced in version 9.5.0.73

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.
top
IntAt
pub fn int_at(&self, index: i32) -> i32
Introduced in version 9.5.0.56

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.
More Information and Examples
JSON: Access Array Values
top
IsNullAt
pub fn is_null_at(&self, index: i32) -> bool
Introduced in version 9.5.0.56

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.
More Information and Examples
Modify Parts of JSON Document
top
Load
pub fn load(&self, json_array: &str) -> Result<()>
Introduced in version 9.5.0.64

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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load a JsonArrayLoading and Parsing a JSON ArrayUnderstanding JSON Array vs JSON Object
top
LoadSb
pub fn load_sb(&self, sb: &StringBuilder) -> Result<()>
Introduced in version 9.5.0.64

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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load a JsonArray
top
ObjectAt
pub fn object_at(&self, index: i32) -> Result<JsonObject>
Introduced in version 9.5.0.56

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.

Returns Err(chilkat::Error) on failure.

More Information and Examples
JSON: Array of ObjectsCreate more Complex JSON DocumentModify Parts of JSON Document
top
ObjectAt2
pub fn object_at2(&self, index: i32, json_obj: &JsonObject) -> Result<()>
Introduced in version 11.0.0

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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
SetBoolAt
pub fn set_bool_at(&self, index: i32, value: bool) -> Result<()>
Introduced in version 9.5.0.56

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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Modify Parts of JSON Document
top
SetIntAt
pub fn set_int_at(&self, index: i32, value: i32) -> Result<()>
Introduced in version 9.5.0.56

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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Modify Parts of JSON Document
top
SetNullAt
pub fn set_null_at(&self, index: i32) -> Result<()>
Introduced in version 9.5.0.56

Replaces the value at zero-based position index with the JSON value null. The array length and the positions of other elements are unchanged.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
SetNumberAt
pub fn set_number_at(&self, index: i32, value: &str) -> Result<()>
Introduced in version 9.5.0.56

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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Modify Parts of JSON Document
top
SetStringAt
pub fn set_string_at(&self, index: i32, value: &str) -> Result<()>
Introduced in version 9.5.0.56

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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Modify Parts of JSON Document
top
SetUIntAt
pub fn set_u_int_at(&self, index: i32, value: u32) -> Result<()>
Introduced in version 9.5.0.96

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.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
StringAt
pub fn string_at(&self, index: i32) -> Result<String>
Introduced in version 9.5.0.56

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.

Returns Err(chilkat::Error) on failure.

More Information and Examples
JSON: Access Array Values
top
Swap
pub fn swap(&self, index1: i32, index2: i32) -> Result<()>
Introduced in version 9.5.0.76

Exchanges the values at zero-based positions index1 and index2. The array length does not change.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
TypeAt
pub fn type_at(&self, index: i32) -> i32
Introduced in version 9.5.0.58

Returns an integer identifying the JSON type of the value at zero-based position index. Returns -1 if no value exists at that index.

1string
2number
3object
4array
5boolean
6null
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.
top
UIntAt
pub fn u_int_at(&self, index: i32) -> u32
Introduced in version 9.5.0.96

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.
top