Item (Json property)
Return or set JSON object/array item value (Json class)
[Introduced in Model 204 7.6]
This function retrieves or sets an item in a Json array or object, using either the item number for an array or the item (property) name for an object.
Syntax
%currentJson = json:Item( index) json:Item( index) = newJson Throws InvalidJsonType
Syntax terms
| %currentJson | Json object being retrieved from the object or array. |
|---|---|
| Json | Json object, which must be either an object or array. |
| index | The number of the item to set or retrieve if the Json object is an array or the name of the item (property) to set or retrieve if the Json object is an object. |
| newJson | Json object being added to the object or array. |
Usage notes
- As with the Arraylist Item property and the Stringlist Item function, the Item method can be invoked implicitly. That is
%json:item(%x)is identical to%json(%x). - JavaScript and JSON terminology refer to the properties of an object. However, the SOUL equivalent of JSON objects, NamedArraylists use the term items so, since the Json class is a SOUL feature, generally object properties will be referred to as named items.
- If the underlying Json object is an object, the input index is treated as a string, regardless of its datatype.
- The names used for objects are always stored internally as unicode so the names can be specified as unicode variables or constants.
- If the underlying Json object is an object, specifying a name that is not in the object returns a null on a retrieval and adds the name on a set.
- Unlike NamedArraylists, items are maintained in the object in the order in which they are added – this is generally the way JavaScript works and, while the JSON standard cautions against depending on property order, it does not forbid it. This does mean that setting and retrieving object items (properties) requires a linear scan of the item list so is not an ideal structure for very large item lists.
- If the underlying Json object is an array, the index must specify an item number that is between 1 and the number of items in the array (inclusive) for a retrieval, and between 1 and the number of items in the array plus one (inclusive) for a set. If the item number specified on a set is one more than the number of items in the array, the item is added to the end of the array.
- If the underlying Json object is an array, the input index is treated as a number, regardless of its datatype. This means that if it's a string that's not a valid number, it's converted to a 0 which is not a valid item number so results in request cancellation.
Examples
The following example sets some object items (properties) by name and then retrieves their values to use in an addition:
b %json is object json %json = object %json('Paris') = 2243833 %json('Marseille') = 850726 %json('Lyon') = 484344 %json('Toulouse') = 441802 printText {~=%json('Paris'):numberValue + %json('Marseille'):numberValue} printText {~=%json('Paris'):numberValue + %json('Lyon'):numberValue} printText {~=%json('Paris'):numberValue + %json('Toulouse'):numberValue} end
The above prints:
%json('Paris'):numberValue + %json('Marseille'):numberValue=3094559 %json('Paris'):numberValue + %json('Lyon'):numberValue=2728177 %json('Paris'):numberValue + %json('Toulouse'):numberValue=2685635
The following example replaces the values of some Json array items and then retrieves each item for printing:
b %json is object json %i is float %json = array(2, 3, 5, 7, 11, 13, 17, 19) %json(2) = "Berlin" %json(5) = "Hamburg" %json(6) = "Munich" for %i from 1 to %json:count printText {%i}: {%json(%i)} end for end
This prints:
1: 2 2: "Berlin" 3: 5 4: 7 5: "Hamburg" 6: "Munich" 7: 17 8: 19
Of course, if the intent was just to see the contents of the array, the array itself could just be printed, though the format of the output would be slightly different.