json.get

json.get() Function

• Introduced in version 1.3b49

Returns the value in a JSON Array at the specified index, returns a slice of a JSON Array from the specified indexes, or returns the value from JSON Object for the specified key.

Usage

json.get(array, index)

json.get(array, start, end)

json.get(object, key, key, ...)

Parameters

• array - The JSON Array to retrieve the element from.
• index - The numerical index of the element you want returned.
• start - The starting index of the element you wish the slice to begin at.
• end - The ending index of the element you wish the slice to end at.
• object - The JSON Object to retrieve the element from.
• key - The name of a field that should be returned. This parameter can exist more than once, if it does then a JSON Object is returned with all the specified elements.

When extracting slices:
Negative numbers can be used as the offsets from the end of the array. -1 is the last element in the array, -2 is the second to last, and so on. If the element specified by the start index and the element specified by the end index are located in reverse order in array (so reading from left to right end comes before start), then the array slice is returned in reverse order compared to array (because fetching from start to end means reading backwards).
Negative offsets do not work for single indexes (the json.get(array, index) usage). If you want to retrieve a single element relative to the end of the array, say the last one, you have two options: Use the single index notation and calculate with the length of the array, such as json.get(array, json.length(array)-1), or use the slice notation, such as json.get(json.get(array, -1, -1), 0). Note that using the slice notation like json.get(array, -1, -1) will capture just one element, but still returns a slice which is in the JSON Array format. The last element then needs to be extracted from index 0 of that slice array.

Examples

a) [h: obj = json.fromStrProp("a=1; b=44; cat=meow")] [r: json.get(obj, "b")] <br>
b) [h: obj = json.fromStrProp("a=1; b=44; cat=meow")] [r: json.get(obj, "XX")] <br>
c) [h: obj = json.fromStrProp("a=1; b=44; cat=meow")] [r: json.get(obj, "cat", "a")] <br>
d) [h: obj = json.fromStrProp("a=1; b=44; cat=meow")] [r: json.get(obj, "b", "XX")] <br>
<br>
e) [h: arr = json.fromList("1,44,meow")] [r: json.get(arr, 1)] <br>
f) [h: arr = json.fromList("1,44,meow")] [r: json.get(arr, 2)] <br>
g) [h: arr = json.fromList("1,44,meow")] [r: json.get(arr, 1, 2)] <br>
h) [h: arr = json.fromList("1,44,meow")] [r: json.get(arr, 0, -1)] <br>
i) [h: arr = json.fromList("1,44,meow")] [r: json.get(arr, 0, -2)] <br>
j) [h: arr = json.fromList("1,44,meow")] [r: json.get(arr, 2, 0)] <br> 
k) [h: arr = json.fromList("1,44,meow")] [r: json.get(arr, -2, 0)] <br>
<br>
ERROR a) [h: arr = json.fromList("1,44,meow")] [r: json.get(arr, -1)] <br>
ERROR b) [h: arr = json.fromList("1,44,meow")] [r: json.get(arr, 3)] <br>

Returns

a) 44 -- a value
b)    -- empty string "", as the key XX was not defined
c) {"cat":"meow","a":1} -- a JSON object
d) {"b":44,"XX":""} -- a JSON object
 
e) 44 -- a value
f) meow -- a value
g) [44,"meow"] -- an array slice of 1 to 2
h) [1,44,"meow"] -- an array slice from 0 to end (-1), meaning the entire original array
i) [1,44] -- an array slice from 0 to second to last (-2)
j) ["meow",44,1] -- an array slice from 2 to 0 (reverse order)
k) [44,1] -- an array slice from second to last (-2) to 0 (reverse order)

ERROR a) -- java.lang.ArrayIndexOutOfBoundsException, can't use negatives with a single index param (works with slices, see usage note).
ERROR b) -- java.lang.ArrayIndexOutOfBoundsException, the last valid index is 2

Version Changes

• 1.3b51 - Added ability to return JSON Array slices.
• 1.3b51 - Added ability to return JSON Objects of select fields from other JSON Objects.