What the Class Is Used For

Use Chilkat.JsonArray when the JSON value being processed is an array, or when a member inside a JsonObject contains an array. The class is index-oriented: values are read, inserted, set, deleted, swapped, or searched by position.

Work with JSON Arrays Load JSON that begins with [ and ends with ], inspect its elements, and emit it back to text.

Build Ordered Lists Insert strings, numbers, booleans, nulls, objects, and arrays at a specific index or append them using index -1.

Access Nested Data Retrieve nested JsonObject or JsonArray values from array elements.

Search Array Contents Find matching strings or find objects in the array where a named member matches a value or wildcard pattern.

JsonObject vs JsonArray

Class	Represents	Access Style	Typical Example
JsonObject	A JSON object: an unordered or order-preserved set of named members.	Access values by member name or JSON path, such as user.name or items[0].sku.	{"name":"Alice","active":true}
JsonArray	A JSON array: an ordered list of values.	Access values by zero-based index, such as 0, 1, or 2.	["red","green","blue"]

How They Complement Each Other	Practical Meaning
Objects often contain arrays.	A JsonObject may have a member such as "items" whose value is a JSON array. Use JsonObject.ArrayOf to get that array, then use JsonArray methods to work with the list.
Arrays often contain objects.	A JsonArray may contain JSON objects. Use ObjectAt or ObjectAt2 to get an element as a JsonObject.
Arrays often contain arrays.	A JsonArray can contain nested arrays. Use ArrayAt or ArrayAt2 to work with a nested list.
Object methods are path-oriented; array methods are index-oriented.	Use JsonObject to navigate by names and paths. Use JsonArray once you are working with an ordered list of elements.

Simple rule: Use JsonObject for JSON enclosed in { }. Use JsonArray for JSON enclosed in [ ]. In real JSON documents, they commonly reference each other at different levels of the tree.

Typical Workflow

Load an array from text with Load or from a StringBuilder with LoadSb.
Check Size to know how many elements are in the array.
Inspect element types with TypeAt before reading values when input JSON is externally supplied.
Read values with methods such as StringAt, IntAt, BoolAt, ObjectAt, or ArrayAt.
Insert new values using Add*At methods. Use index 0 to prepend or -1 to append.
Modify existing values with Set*At methods.
Search, delete, or reorder elements with FindString, FindObject, DeleteAt, and Swap.
Emit the array with Emit or EmitSb, using EmitCompact and EmitCrlf to control formatting.

Core Concepts

Concept	Meaning	Important Members
Array Element	One value in the ordered JSON array. It may be a string, number, object, array, boolean, or null.	Size, TypeAt, StringAt, ObjectAt
Zero-Based Indexing	The first element is at index 0, the second at index 1, and so on.	AddAt, SetAt, DeleteAt, Swap
Append by Index -1	Insertion methods use index -1 to append to the end of the array.	AddStringAt(-1, ...), AddObjectAt(-1), AddArrayAt(-1)
Nested Object	An array element can be a JSON object, accessed through JsonObject.	ObjectAt, ObjectAt2, AddObjectAt, AddObjectAt2
Nested Array	An array element can itself be another JSON array.	ArrayAt, ArrayAt2, AddArrayAt, AddArrayAt2
Standalone Array Document	Calling Load or LoadSb loads a complete JSON array document.	Load, LoadSb, Clear

Core Properties

Property	Purpose	Guidance
Size	Number of values in the array.	Use for loops and bounds checking before index-based access.
EmitCompact	Controls whether emitted JSON is compact or pretty-printed.	Default true emits a single compact line. Set to false for human-readable formatting.
EmitCrlf	Controls line endings when emitting non-compact JSON.	Default true uses CRLF. Set to false for LF.
FindStartIndex	Start index for FindString and FindObject.	Default is 0. Change it to continue searching after a previous match.
LastErrorText	Detailed diagnostic text for the last method or property access.	Check after failures or unexpected results.

Loading, Clearing, and Emitting

Task	Method	Behavior
Load from string	Load	Loads a JSON array from a string. The JSON must begin with [ and end with ].
Load from StringBuilder	LoadSb	Loads a JSON array from a StringBuilder.
Clear all elements	Clear	Deletes all array elements.
Emit to string	Emit	Returns the JSON array rooted at the current object as a string.
Emit to StringBuilder	EmitSb	Writes the JSON array to a StringBuilder.

Important Load behavior: Load and LoadSb cause the JsonArray to detach and become its own JSON document. They should be called on new JsonArray instances, not on an array object that is currently referencing part of another JSON document.

Reading Array Values

Value Type	Method	Return / Output
String	StringAt	Returns the string value at the zero-based index.
Integer	IntAt	Returns the integer value at the zero-based index.
Unsigned integer	UIntAt	Returns the unsigned integer value at the zero-based index.
Boolean	BoolAt	Returns the boolean value at the zero-based index.
Null check	IsNullAt	Returns true if the element at the index is JSON null.
Nested object	ObjectAt, ObjectAt2	Returns or assigns a JsonObject reference to the object at the index.
Nested array	ArrayAt, ArrayAt2	Returns or assigns a JsonArray reference to the nested array at the index.
Date/time	DateAt, DtAt	Parses recognized date/time strings or Unix timestamp integers into CkDateTime or DtObj.
Type inspection	TypeAt	Returns the JSON type code for the element.

Type values: TypeAt returns 1 string, 2 number, 3 object, 4 array, 5 boolean, 6 null, or -1 if no element exists at the index.

Adding and Inserting Values

The Add*At methods insert new values at a specific position. Use index 0 to prepend and -1 to append.

Value to Insert	Method	Notes
String	AddStringAt	Inserts a JSON string value.
Integer	AddIntAt	Inserts a signed integer.
Unsigned integer	AddUIntAt	Inserts an unsigned integer.
Number from string	AddNumberAt	Inserts a numeric value using the exact string representation provided by the application.
Boolean	AddBoolAt	Inserts true or false.
Null	AddNullAt	Inserts JSON null.
Empty object	AddObjectAt, AddObjectAt2	Inserts a new empty object. The *2 variant returns a JsonObject reference to the new object.
Copy of object	AddObjectCopyAt	Inserts a copy of an existing JsonObject.
Empty array	AddArrayAt, AddArrayAt2	Inserts a new empty nested array. The *2 variant returns a JsonArray reference.
Append all items from another array	AppendArrayItems	Appends the elements contained in another JsonArray.

Setting Existing Values

The Set*At methods replace the value at an existing zero-based index.

Value Type	Method	Purpose
String	SetStringAt	Sets the array element to a JSON string.
Integer	SetIntAt	Sets the array element to a signed integer.
Unsigned integer	SetUIntAt	Sets the array element to an unsigned integer.
Number from string	SetNumberAt	Sets the array element to a numeric value using the exact numeric string supplied by the application.
Boolean	SetBoolAt	Sets the array element to true or false.
Null	SetNullAt	Sets the array element to JSON null.

Set vs Add: Use Set*At to replace an existing element. Use Add*At to insert a new element and shift later elements to the right.

Nested Objects and Arrays

Need	Method	How It Complements JsonObject
Get an object element	ObjectAt, ObjectAt2	Once an array element is an object, use JsonObject methods to read or update its named members.
Insert a new object element	AddObjectAt, AddObjectAt2	Add an object to the array, then fill it using JsonObject member/path methods.
Insert a copy of an object	AddObjectCopyAt	Reuses an existing JsonObject structure by inserting a copied object into the array.
Get a nested array element	ArrayAt, ArrayAt2	Work with nested arrays using another JsonArray reference.
Insert a new nested array	AddArrayAt, AddArrayAt2	Build arrays of arrays, or create list members inside arrays.

Common pattern: Use JsonObject to reach an array member, then use JsonArray to iterate the list, and use JsonObject again for each object element in that list.

Searching Arrays

Search Type	Method	Behavior
Find a string element	FindString	Returns the index of the first string matching a value pattern. The pattern can use * for zero or more characters.
Find an object by member value	FindObject	Returns the index of the first object in the array where the named member matches the supplied value pattern.
Start search after a known index	FindStartIndex	Controls the starting index for FindString and FindObject. Default is 0.

Search result: FindString and FindObject return the matching index, or -1 when no match is found.

Date/Time and Numeric Handling

Need	Method	Notes
Read date/time into CkDateTime	DateAt	Auto-recognizes ISO-8061-style timestamps, RFC 822 date/time strings, and Unix timestamp integers.
Read date/time into DtObj	DtAt	Can fill the DtObj with local or UTC/GMT date and time values.
Read number as int	IntAt	Reads the element as a signed integer.
Read number as unsigned int	UIntAt	Reads the element as an unsigned integer.
Preserve exact numeric formatting	AddNumberAt, SetNumberAt	The numeric value is provided as a string, allowing the application to control the exact representation used in JSON.

Deleting and Reordering

Task	Method	Behavior
Delete one element	DeleteAt	Deletes the element at the specified zero-based index.
Delete all elements	Clear	Removes every value from the array.
Swap two elements	Swap	Swaps the items at two zero-based indexes.

Method Families at a Glance

Family	Representative Methods	Purpose
Load / clear / emit	Load, LoadSb, Clear, Emit, EmitSb	Load a standalone JSON array, clear it, and output it.
Read values	StringAt, IntAt, UIntAt, BoolAt, IsNullAt	Retrieve scalar values from array elements.
Read nested structures	ObjectAt, ObjectAt2, ArrayAt, ArrayAt2	Access object or array elements as JSON object/array references.
Insert values	AddStringAt, AddIntAt, AddNumberAt, AddBoolAt, AddNullAt	Insert scalar values at a specific index.
Insert nested structures	AddObjectAt, AddObjectAt2, AddObjectCopyAt, AddArrayAt, AddArrayAt2	Insert nested objects or arrays.
Set existing values	SetStringAt, SetIntAt, SetUIntAt, SetNumberAt, SetBoolAt, SetNullAt	Replace existing array elements.
Search and reorder	FindString, FindObject, FindStartIndex, DeleteAt, Swap	Locate values, remove elements, or reorder items.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
Load or parse failure	LastErrorText	Check detailed diagnostic information after Load or LoadSb fails.
Wrong input type	Load	Confirm the input is a JSON array beginning with [ and ending with ]. Use JsonObject for JSON beginning with {.
Index out of range	Size, TypeAt	Check Size before using index-based methods. TypeAt returns -1 if no element exists at the index.
Unexpected element type	TypeAt	Inspect whether the element is a string, number, object, array, boolean, or null before reading it.
Search does not find expected match	FindStartIndex, FindString, FindObject	Confirm the starting index, case-sensitivity setting, wildcard pattern, and object member name.
Nested object or array access fails	ObjectAt, ArrayAt, TypeAt	Verify the element type before retrieving it as a nested object or array.

Common Pitfalls

Pitfall	Better Approach
Loading object JSON into JsonArray.	Use JsonArray only when the root JSON begins with [. Use JsonObject for JSON beginning with {.
Calling Load on a nested array reference.	Call Load only on a new JsonArray instance because loading detaches it into its own JSON document.
Using Set*At when trying to append.	Use AddAt(-1, ...) to append a new element. SetAt replaces an existing element.
Forgetting zero-based indexing.	The first element is index 0. The last valid index is Size - 1.
Assuming a numeric value must be passed as a numeric type.	Use AddNumberAt or SetNumberAt when the application wants to control the exact numeric string representation.
Expecting pretty output while EmitCompact is true.	Set EmitCompact = false before Emit or EmitSb.

Best Practices

Recommendation	Reason
Use JsonObject for named data and JsonArray for ordered lists.	JSON objects and arrays have different access patterns. Use the class that matches the current JSON node.
Check Size before index-based access.	It prevents out-of-range reads, writes, deletes, and swaps.
Use TypeAt before reading externally supplied JSON.	Array elements can hold any JSON type, and external input may not match expectations.
Use Add*At(-1, ...) to append values.	The class uses -1 as the append position for insertion methods.
Use AddObjectAt2 and AddArrayAt2 when building nested structures.	These variants return references to the newly inserted object or array so it can be filled immediately.
Use FindStartIndex for repeated searches.	It allows the next search to continue after a previous match.
Use EmitCompact = false for diagnostics and examples.	Pretty-printed JSON is easier to inspect in logs, documentation, and tests.
Check LastErrorText after failures.	It provides the most useful diagnostic detail for load, access, mutation, search, and emit operations.

Summary

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.

In practice, applications often use both classes together: use JsonObject to navigate named members and JSON paths, then use JsonArray to iterate and modify ordered lists found within the object tree.

Chilkat.JsonArray Class Overview