json.get: Difference between revisions
No edit summary |
No edit summary |
||
(20 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
{{MacroFunction | {{MacroFunction | ||
|name=json.get | |name=json.get | ||
Line 7: | Line 6: | ||
|usage= | |usage= | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
json.get(array, index) | json.get(array, index) | ||
</ | </syntaxhighlight> | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
json.get(array, start, end) | json.get(array, start, end) | ||
</ | </syntaxhighlight> | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
json.get(object, key, key, ...) | json.get(object, key, key, ...) | ||
</ | </syntaxhighlight> | ||
'''Parameters''' | '''Parameters''' | ||
{{param|array|The [[JSON Array]] to retrieve the element from.}} | {{param|array|The [[JSON Array]] to retrieve the element from.}} | ||
Line 24: | Line 23: | ||
{{param|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.}} | {{param|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.}} | ||
Negative numbers can be used as the offsets from the end of the array | When extracting slices:<br /> | ||
Negative numbers can be used as the offsets from the end of the array. {{code|-1}} is the last element in the array, {{code|-2}} is the second to last, and so on. If the element specified by the {{code|start}} index and the element specified by the {{code|end}} index are located in reverse order in {{code|array}} (so reading from left to right {{code|end}} comes before {{code|start}}), then the array slice is returned in reverse order compared to {{code|array}} (because fetching from {{code|start}} to {{code|end}} means reading backwards).<br /> | |||
Negative offsets do not work for single indexes (the {{code|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 {{code|json.get(array, json.length(array)-1)}}, or use the slice notation, such as {{code|json.get(json.get(array, -1, -1), 0)}}. Note that using the slice notation like {{code|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= | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
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> | |||
</syntaxhighlight> | |||
Returns | Returns | ||
44 | 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 | |||
<br /> | |||
|changes= | |changes= | ||
{{change|1.3b51|Added ability to return [[JSON Array]] slices.}} | {{change|1.3b51|Added ability to return [[JSON Array]] slices.}} |
Latest revision as of 17:46, 15 March 2023
json.get() Function
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.