json.get: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
(Fixed the example to show correct output and added some more explanation.)
No edit summary
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. To get the last element you thus need to do: json.get(json.get(array, -1,-1),0) as you get a ''slice'' and you want an ''element''.
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>
<source 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>
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>
</source>
</source>


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) [44,"meow"] -- an array slice of 1 to 2
f) meow -- a value
  h) [1,44,"meow"] -- an array slice from 0 to end  
g) [44,"meow"] -- an array slice of 1 to 2
  i) ["meow",44,1] -- an array slice from 2 to 0 (reverse order)
h) [1,44,"meow"] -- an array slice from 0 to end (-1), meaning the entire original array
  j) ["meow",44,1] -- an array slice from end to 0 (reverse order)
i) [1,44] -- an array slice from 0 to second to last (-2)
  ERROR a) -- java.lang.ArrayIndexOutOfBoundsException, can't use negatives with a single index param (works OK with slices).  
j) ["meow",44,1] -- an array slice from 2 to 0 (reverse order)
  ERROR b) -- java.lang.ArrayIndexOutOfBoundsException, the last valid index is 2
k) [44,1] -- an array slice from second to last (-2) to 0 (reverse order)
 
Reverse Order is just if the 2nd number is lower than the first, except with -1 which means end of list. Think of it as a wrapping number line going from 0 to N. Starting at 0, then minus 1 brings you to end of list. -2 would be 2nd from end of list. But it only wraps once that way and not past the end of list. So, referencing N+1 will give you an out of bounds error like with ERROR b.
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.}}

Revision as of 14:02, 2 May 2021

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