You are here: Start » Filter Reference » System » Json » Json_GetValue_FromArray_Int64_OrNil (Json_GetValue_FromArray Int64OrNil)

Json_GetValue_FromArray_Int64_OrNil (Json_GetValue_FromArray Int64OrNil)

Basic

Module:	FoundationLite

Gets a value of type Int64 from a JSON array or nil.

Name	Type	Range	Description
inJson	JsonData		Input JSON data.
inIndex	Integer	0 -	Index of the value to get from the array.
inValidate	Bool		Whether to validate that the key exists and is of the correct type.
outInt64	Long ?		Value obtained from the array or nil.

Remarks

Working with JSON data

Introduction

This filter is intended to interact with data saved in JSON format.

A JSON document is composed of objects and arrays nested within each other. Each document has the main object where all other data is stored. Data in objects is stored in a key-value fashion, while data in arrays is a sequence of values. Objects are marked with braces and arrays are marked with square brackets.

The JSON filters use a custom data type that represents a single element of a JSON document. An element may represent both JSON data structures - arrays and objects, but also values stored inside them - numerics, strings or booleans.

Loading a JSON document from a file

To load a JSON document from a file, the Json_LoadFile filter is used.

During loading of a JSON document it is possible to set various format parameters and parsing options. These can also be set at a later time for each JSON data structure individually using Json_SetFormatParameters and Json_SetParseOptions filters. When nesting JSON data structures, format parameters and parsing options of the higher data structure are used for the resulting structure.

Format parameters

The JsonFormatParameters allow for a more readable preview of JSON data in Aurora Vision Studio and specify the indentation of the JSON document when saving it to a file. It is recommended to disable the indentation if the preview is not used, as it introduces a small performance cost.

Accessing JSON data

After loading a JSON file all properties of arrays and objects can be accessed with Json_Access_Array and Json_Access_Object filters.

Filters from groups Json_GetValue_FromArray and Json_GetValue_FromObject can be used to access directly a value from an array or an object using its index or key. These filters are available for Bool, Int64, Uint64, Double, String, Array and Object types.

Many of these filters have OrNil variants that return Nil instead of throwing an error when a key doesn't exist or when the JSON value is null. The OrNil variants include an inValidate parameter: when set to false (default), the filter returns Nil for missing keys or type mismatches; when set to true, the filter throws an error for missing keys but still returns Nil for null JSON values.

Values of other types, such as Bool, Double, Int64, Uint64 and String can be extracted from JSON data structures of the corresponding types using the Json_GetValue_FromJsonData filters.

To check if a key exists in a JSON object or array, use the Json_KeyExistsIn filters. To get the data type of a value in JSON data, use the Json_GetElementType filters.

Warning: Numeric Json_GetValue filters perform automatic type conversion between int64, uint64, and double. Conversions may silently truncate decimal values (double -> integer) or lose precision (large integer -> double) without throwing exceptions, provided the source is a valid JSON number.

Creating a JSON document

The process of creating JSON documents is organized in a bottom-up approach. At the beginning, the lowest structures of the document must be created. Then, such structures can be added to a structure at a higher level in the document and that structure can be added to some yet higher structure and so on. The structure at the highest level in hierarchy must be an object.

To create an empty JSON structure Json_CreateEmpty_Array and Json_CreateEmpty_Object filters should be used.

Created JSON structures should be nested in other structures using the filters from groups Json_InsertValue_IntoArray and Json_SetValue_InObject . New structures will be added at the specified index or key. These filters are available for Bool, Int64, Uint64, Double, String, Array, Object and Null types.

The OrNil variants of these filters allow inserting null values into JSON by passing Nil as the value parameter. For example, Json_SetValue_InObject_Bool_OrNil can insert either a boolean value or a JSON null.

To remove a nested structure from an array or an object, the filters from group Json_RemoveValue can be used.

Saving a JSON document to a file

To save a JSON document to a file, the Json_SaveFile filter is used.

Other

JSON data structures can be converted to and built from strings using JsonDataToString and StringToJsonData filters.

Most of Aurora Vision Studio objects can be serialized to text and stored in a JSON file. SerializeToJson and DeserializeFromJson filters are used for that purpose.

Complexity Level

This filter is available on Basic Complexity Level.

Filter Group

This filter is member of Json_GetValue_FromArray filter group visible as Int64OrNil.