json.get: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(5 intermediate revisions by 4 users not shown)
Line 6: Line 6:


|usage=
|usage=
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
json.get(array, index)
json.get(array, index)
</source>
</syntaxhighlight>
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
json.get(array, start, end)
json.get(array, start, end)
</source>
</syntaxhighlight>
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
json.get(object, key, key, ...)
json.get(object, key, key, ...)
</source>
</syntaxhighlight>
'''Parameters'''
'''Parameters'''
{{param|array|The [[JSON Array]] to retrieve the element from.}}
{{param|array|The [[JSON Array]] to retrieve the element from.}}
Line 23: 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.}}


When extracting slices: 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 {{code|end}} index is smaller than the {{code|start}} index then the array slice is returned in reverse. This does not work for single indices, so if you want to retrieve a single index, say the last one in an array, you do that like this: json.get(array, -1,-1). This way you take a ''slice'' of 1 index
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=
|examples=
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
  a) [h: jo = json.fromStrProp("a=1; b=44; cat=meow")] [r: json.get(jo, "b")] <br>
a) [h: obj = json.fromStrProp("a=1; b=44; cat=meow")] [r: json.get(obj, "b")] <br>
  b) [h: jo = json.fromStrProp("a=1; b=44; cat=meow")] [r: json.get(jo, "XX")] <br>
b) [h: obj = json.fromStrProp("a=1; b=44; cat=meow")] [r: json.get(obj, "XX")] <br>
  c) [h: jo = json.fromStrProp("a=1; b=44; cat=meow")] [r: json.get(jo, "cat", "a")] <br>
c) [h: obj = json.fromStrProp("a=1; b=44; cat=meow")] [r: json.get(obj, "cat", "a")] <br>
  d) [h: jo = json.fromStrProp("a=1; b=44; cat=meow")] [r: json.get(jo, "b", "XX")] <br>
d) [h: obj = json.fromStrProp("a=1; b=44; cat=meow")] [r: json.get(obj, "b", "XX")] <br>
  e) [h: ja = json.fromList("1,44,meow")] [r: json.get(ja, 1)] <br>
<br>
  f) [h: ja = json.fromList("1,44,meow")] [r: json.get(ja, 2)] <br>
e) [h: arr = json.fromList("1,44,meow")] [r: json.get(arr, 1)] <br>
  g) [h: ja = json.fromList("1,44,meow")] [r: json.get(ja, 1, 2)] <br>
f) [h: arr = json.fromList("1,44,meow")] [r: json.get(arr, 2)] <br>
  h) [h: ja = json.fromList("1,44,meow")] [r: json.get(ja, 0, -1)] <br>
g) [h: arr = json.fromList("1,44,meow")] [r: json.get(arr, 1, 2)] <br>
  i) [h: ja = json.fromList("1,44,meow")] [r: json.get(ja, 2, 0)] <br>  
h) [h: arr = json.fromList("1,44,meow")] [r: json.get(arr, 0, -1)] <br>
  j) [h: ja = json.fromList("1,44,meow")] [r: json.get(ja, -1, 0)] <br>
i) [h: arr = json.fromList("1,44,meow")] [r: json.get(arr, 0, -2)] <br>
  ERROR a) [h: ja = json.fromList("1,44,meow")] [r: json.get(ja, -1)] <br>
j) [h: arr = json.fromList("1,44,meow")] [r: json.get(arr, 2, 0)] <br>  
  ERROR b) [h: ja = json.fromList("1,44,meow")] [r: json.get(ja, 3)] <br>
k) [h: arr = json.fromList("1,44,meow")] [r: json.get(arr, -2, 0)] <br>
 
<br>
</source>
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
  a) 44 -- a value
a) 44 -- a value
  b)    -- empty string "", as XX does not exist
b)    -- empty string "", as the key XX was not defined
  c) {"cat":"meow","a":1} -- a JSON object
c) {"cat":"meow","a":1} -- a JSON object
  d) {"b":44,"XX":""} -- a JSON object
d) {"b":44,"XX":""} -- a JSON object
   e) 44 -- a value
    
  f) meow -- a value
e) 44 -- a value
  g) [1,44,"meow"] -- an array slice of 0..2   
f) meow -- a value
  h) ["meow",44] -- an array slice from 2..1  
g) [44,"meow"] -- an array slice of 1 to 2
  i) [1,44,"meow"] -- an array slice from 0..end
  h) [1,44,"meow"] -- an array slice from 0 to end (-1), meaning the entire original array
  j) ["meow",44] -- an array slice from end..1
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)
  ERROR a) -- java.lang.ArrayIndexOutOfBoundsException, can't use negatives with a single index param (works OK with slices).  
k) [44,1] -- an array slice from second to last (-2) to 0 (reverse order)
  ERROR a) -- java.lang.ArrayIndexOutOfBoundsException, the last valid index is 2
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

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