JsonArray Chilkat2 Perl Reference Documentation
Chilkat2::JsonArray
Current Version: 11.7.0
Markdown version of this page for AI tools (v 11.7.0) · all AI docs
Chilkat.JsonArray
Work with JSON arrays as ordered lists containing strings, numbers,
booleans, nulls, objects, arrays, and mixed value types.
Retrieve, insert, replace, delete, or swap values by array index when
processing JSON list data.
Access child
Search arrays of strings or arrays of objects to locate matching values
without manually scanning every element.
Parse date/time values and preserve exact numeric strings when JSON data
contains values that must not be rounded or reformatted.
Produce compact or pretty JSON output after array data has been loaded,
edited, searched, or built programmatically.
For an extended overview, see
JsonArray Class Overview.
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
Index-based access
Nested objects and arrays
JsonObject and JsonArray values to
navigate and modify deeper JSON structures.
Search helpers
Date and numeric handling
Emit JSON output
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.
Object Creation
use Chilkat2;
my $jarr = Chilkat2::JsonArray->new;
# or set properties (and RaiseError) at creation:
# my $jarr = Chilkat2::JsonArray->new(VerboseLogging => 1, RaiseError => 1);Creates the object. The optional pairs set writable properties (and RaiseError) in order, as if set one by one; an unknown or read-only name croaks. use Chilkat2; loads every class; the Chilkat2/JsonArray.pm file holds only this class's documentation (perldoc Chilkat2::JsonArray).
Perl frees the object when its last reference goes (undef $jarr, or the variable going out of scope); there is nothing to close. Objects returned by methods are independent and freed the same way. The class may be subclassed (use parent -norequire, 'Chilkat2::JsonArray';): an object is a blessed hash reference whose hash is free for the subclass's own fields.
When false (the default), a method that fails returns false (or undef), and the reason is in LastErrorText. When true, it dies with a Chilkat2::Error instead, as DBI does with its RaiseError. Objects returned by a method inherit the value of the object that returned them.
Errors
A Chilkat2::Error stringifies to the failed call's full LastErrorText, and has the methods text, class ('Chilkat2::JsonArray'), method (the method name) and object. Methods that look something up and find nothing return undef without dying (each such method says so), methods that answer a question (HasMember, IsUnlocked, ...) return a plain boolean, and property reads and writes never fail for Chilkat reasons.
Misuse always croaks, with your file and line, whatever RaiseError is: a wrong number of arguments, a reference or undef where a string or number is expected, an object of the wrong class, an out-of-range integer, a string containing a NUL character, a wide character in a byte string, or a write to a read-only property.
Strings are Perl character strings in both directions (length, regexes and :encoding layers see characters); binary data (BinData) is a byte string. Unlocking: call Chilkat2::Global->new->UnlockBundle('...') once at startup.
Properties
DebugLogFilePath
my $strVal = $jarr->DebugLogFilePath;
$jarr->DebugLogFilePath($strVal);
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.
EmitCompact
my $boolVal = $jarr->EmitCompact;
$jarr->EmitCompact($boolVal);
Controls whether emitted JSON is compact or pretty-formatted. If 1, output contains no unnecessary whitespace and is emitted on a single line. If 0, indentation and line breaks are added for readability. The default is 1.
EmitCrlf
my $boolVal = $jarr->EmitCrlf;
$jarr->EmitCrlf($boolVal);
Controls line endings when pretty-formatted JSON is emitted. If 1, line breaks use CRLF (
); if 0, they use LF (
). The default is 1.
EmitCompact is 1, the JSON is emitted on one line and this setting has no effect.FindStartIndex
my $intVal = $jarr->FindStartIndex;
$jarr->FindStartIndex($intVal);
Specifies the zero-based array index at which FindString and FindObject begin searching. The default value is 0.
n, set this property to n + 1 before the next search to continue with later elements.LastErrorHtml
my $strVal = $jarr->LastErrorHtml;
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.
topLastErrorText
my $strVal = $jarr->LastErrorText;
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.
LastErrorXml
my $strVal = $jarr->LastErrorXml;
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.
topLastMethodSuccess
my $boolVal = $jarr->LastMethodSuccess;
$jarr->LastMethodSuccess($boolVal);
Indicates the success or failure of the most recent method call: 1 means success, 0 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.
Size
my $intVal = $jarr->Size;
Returns the number of values currently contained in the JSON array. Array indexes therefore range from 0 through Size - 1.
VerboseLogging
my $boolVal = $jarr->VerboseLogging;
$jarr->VerboseLogging($boolVal);
If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
Version
my $strVal = $jarr->Version;
Methods
AddArrayAt
# $success is true or false
my $success = $jarr->AddArrayAt($index);
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. |
Add*At methods insert a new array element. Use the corresponding Set*At method when replacing an existing element.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddArrayAt2
# $jarr is a Chilkat2::JsonArray
# $success is true or false
my $success = $jarr->AddArrayAt2($index, $jarr);
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. |
jarr references the inserted array, it can be populated directly without a separate ArrayAt lookup.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddBoolAt
# $value is a boolean
# $success is true or false
my $success = $jarr->AddBoolAt($index, $value);
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. |
Add*At methods insert a new array element. Use the corresponding Set*At method when replacing an existing element.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddIntAt
# $value is an integer
# $success is true or false
my $success = $jarr->AddIntAt($index, $value);
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. |
Add*At methods insert a new array element. Use the corresponding Set*At method when replacing an existing element.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddNullAt
# $success is true or false
my $success = $jarr->AddNullAt($index);
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. |
Add*At methods insert a new array element. Use the corresponding Set*At method when replacing an existing element.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddNumberAt
# $numericStr is a string
# $success is true or false
my $success = $jarr->AddNumberAt($index, $numericStr);
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. |
12345678901234567890, 1.2500, or scientific notation. The supplied text must be valid JSON number syntax; JSON does not permit NaN or infinity.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddObjectAt
# $success is true or false
my $success = $jarr->AddObjectAt($index);
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. |
Add*At methods insert a new array element. Use the corresponding Set*At method when replacing an existing element.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddObjectAt2
# $json is a Chilkat2::JsonObject
# $success is true or false
my $success = $jarr->AddObjectAt2($index, $json);
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. |
json references the inserted object, it can be populated directly without a separate ObjectAt lookup.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddObjectCopyAt
# $jsonObj is a Chilkat2::JsonObject
# $success is true or false
my $success = $jarr->AddObjectCopyAt($index, $jsonObj);
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. |
jsonObj do not serve as edits to the inserted array value.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddStringAt
# $value is a string
# $success is true or false
my $success = $jarr->AddStringAt($index, $value);
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. |
Add*At methods insert a new array element. Use the corresponding Set*At method when replacing an existing element.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddUIntAt
# $value is an integer
# $success is true or false
my $success = $jarr->AddUIntAt($index, $value);
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. |
Add*At methods insert a new array element. Use the corresponding Set*At method when replacing an existing element.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AppendArrayItems
# $success is true or false
my $success = $jarr->AppendArrayItems($jarr);
Appends copies of all values from jarr to the end of this array, preserving their order.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ArrayAt
# $jsonArray is a Chilkat2::JsonArray or undef
my $jsonArray = $jarr->ArrayAt($index);
Returns the nested JSON array stored at zero-based position index.
JsonArray refers to the existing nested array in the same JSON document. Changes made through the returned object modify that nested array.index must be an array. Use TypeAt when the value type is not already known.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way. The returned object is new and independent of this one, and inherits its RaiseError.
ArrayAt2
# $jarr is a Chilkat2::JsonArray
# $success is true or false
my $success = $jarr->ArrayAt2($index, $jarr);
Updates jarr so that it references the nested JSON array stored at zero-based position index.
jarr modify the existing nested array in the same JSON document.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
BoolAt
# $flag is true or false
my $flag = $jarr->BoolAt($index);
Returns the boolean value stored at zero-based position index.
TypeAt when the JSON type at index is not already known.Never dies: false is an answer, not a failure.
topClear
Removes all values from the array, leaving an empty JSON array ([]).
Returns the object, so calls can be chained.
topDateAt
# $dt is a Chilkat2::DateTime
# $success is true or false
my $success = $jarr->DateAt($index, $dt);
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.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
DeleteAt
# $success is true or false
my $success = $jarr->DeleteAt($index);
Deletes the value at zero-based position index. Elements following the deleted value shift down by one position.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
DtAt
# $bLocal is a boolean
# $dt is a Chilkat2::DtObj
# $success is true or false
my $success = $jarr->DtAt($index, $bLocal, $dt);
Parses the date/time value at zero-based position index and loads the result into dt. If bLocal is 1, the populated fields represent local time; if 0, they represent UTC/GMT. Recognized forms include ISO 8601 timestamps, RFC 822-style date/time strings, and Unix timestamp integers.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
Emit
my $str = $jarr->Emit();
Serializes this JSON array and returns the resulting JSON text.
EmitCompact to choose compact versus pretty output. When pretty output is enabled, EmitCrlf selects CRLF or LF line endings.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
EmitSb
Serializes this JSON array into the supplied StringBuilder.
EmitCompact to choose compact versus pretty output. When pretty output is enabled, EmitCrlf selects CRLF or LF line endings.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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FindObject
# $value is a string
# $caseSensitive is a boolean
# $n is an integer
my $n = $jarr->FindObject($name, $value, $caseSensitive);
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.
name identifies a direct member of each object being tested; it is not a JSON path.FindStartIndex, whose default is 0. To continue searching after a match, set FindStartIndex to the previous returned index plus 1.FindString
# $caseSensitive is a boolean
# $n is an integer
my $n = $jarr->FindString($value, $caseSensitive);
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.
FindStartIndex, whose default is 0. To continue searching after a match, set FindStartIndex to the previous returned index plus 1.IntAt
# $n is an integer
my $n = $jarr->IntAt($index);
Returns the integer value stored at zero-based position index.
TypeAt when the JSON type at index is not already known.IsNullAt
# $flag is true or false
my $flag = $jarr->IsNullAt($index);
Returns 1 if the value at zero-based position index is the JSON value null; otherwise returns 0.
null is a distinct JSON value. It is not the same as an empty string, zero, false, an empty object, or an empty array.Never dies: false is an answer, not a failure.
Load
# $success is true or false
my $success = $jarr->Load($jsonArray);
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 ].
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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
LoadSb
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 ].
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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ObjectAt
# $jsonObject is a Chilkat2::JsonObject or undef
my $jsonObject = $jarr->ObjectAt($index);
Returns the JSON object stored at zero-based position index.
JsonObject refers to the existing object in the same JSON document. Changes made through the returned object modify that nested object.index must be an object. Use TypeAt when the value type is not already known.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way. The returned object is new and independent of this one, and inherits its RaiseError.
ObjectAt2
# $jsonObj is a Chilkat2::JsonObject
# $success is true or false
my $success = $jarr->ObjectAt2($index, $jsonObj);
Updates jsonObj so that it references the JSON object stored at zero-based position index.
jsonObj modify the existing object in the same JSON document.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetBoolAt
# $value is a boolean
# $success is true or false
my $success = $jarr->SetBoolAt($index, $value);
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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetIntAt
# $value is an integer
# $success is true or false
my $success = $jarr->SetIntAt($index, $value);
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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetNullAt
# $success is true or false
my $success = $jarr->SetNullAt($index);
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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetNumberAt
# $value is a string
# $success is true or false
my $success = $jarr->SetNumberAt($index, $value);
Replaces the value at zero-based position index with a JSON number. The value argument supplies the exact JSON numeric text to store.
NaN or infinity.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetStringAt
# $value is a string
# $success is true or false
my $success = $jarr->SetStringAt($index, $value);
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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetUIntAt
# $value is an integer
# $success is true or false
my $success = $jarr->SetUIntAt($index, $value);
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 true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
StringAt
# $str is a string or undef
my $str = $jarr->StringAt($index);
Returns the string value stored at zero-based position index.
TypeAt when the JSON type at index is not already known.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
Swap
# $index2 is an integer
# $success is true or false
my $success = $jarr->Swap($index1, $index2);
Exchanges the values at zero-based positions index1 and index2. The array length does not change.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
TypeAt
# $n is an integer
my $n = $jarr->TypeAt($index);
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 |
ObjectAt, ArrayAt, or IntAt for the wrong kind of value.UIntAt
# $n is an integer
my $n = $jarr->UIntAt($index);
Returns the unsigned integer value stored at zero-based position index.
TypeAt when the JSON type at index is not already known.