Panorama > Formulas > Collections
 
getstructurevalue(
getstructurevalue(
STRUCTURE
,
INDEX
)

The getstructurevalue( function extracts a value from a structure of nested Data Dictionaries and/or Data Arrays.

Parameters

This function has two parameters:

structure – a structured collection of data. This must be a data dictionary or data array, which may contain nested dictionaries or arrays.

index – is the desired index into the collection. For data dictionaries the index must be text, for data arrays it must be an integer. This parameter can be repeated to access multiple levels of the structure.

Description

This function extracts a value from a structure of nested Data Dictionaries and/or Data Arrays. You can use this function in lieu of multiple nested getdictionaryvalue( and array( functions.

For example, supposed you have a variable named people that contains a data array of different people. Each element of this array contains a dictionary with different attributes for each person (name, address, etc.). One of these attributes is a data array of each person’s children. With this formula, you could find the name of the second child of the 4th person.

array(getdictionaryvalue(array(people,4),"Children"),2)

That’s a rather contorted formula. We can make it much simpler by using the getstructurevalue( function instead.

getstructurevalue(people,4,"Children",2)

In this example the structured data in people has three levels. There is an index parameter for each level of the structure. If the level is an array, the corresponding index parameter must be an integer. If the level is a dictionary, the corresponding index parameter must be text (the name of the desired element).

The getstructurevalue( function is ideal for working with JSON data that has been converted into a Panorama variable with the jsonimport( function. The code below will construct a people variable along the lines discussed above.

let people = jsonimport(|||
[
    {"Name" : "Jack", "Color" : "Blue", "Size" : 38, "Children" : ["Mary", "Ellen", "Mark"]},
    {"Name" : "Mary", "Color" : "Red", "Size" : 29, "Children" : ["Wayne"]},
    {"Name" : "Bob", "Color" : "Orange", "Size" : 31, "Children" : ["Bill", "Tom"]}
    {"Name" : "Eric", "Color" : "Yellow", "Size" : 40, "Children" : ["Jeff", "Ryan"]},
    {"Name" : "Rita", "Color" : "Blue", "Size" : 24, "Children" : ["Matthew"]},
]
|||)

The getstructurevalue( function can be used to extract various components of this structured data.

getstructurevalue(people,4,"Children",2) ☞ Ryan
getstructurevalue(people,2,"Name") ☞ Mary
getstructurevalue(people,3,"Size") ☞ 31

You don’t have to include an index for every level of the structure. If you omit one or more levels, the function will return a structure, in this case an array.

arraysize(getstructurevalue(people,3,"Children")) ☞ 2
exportdataarray(getstructurevalue(people,3,"Children"),", ") ☞ Bill, Tom

If you specify an element that doesn’t exist, the getstructurevalue( function will return an error. Use the catcherror( function if you want to ignore the error.

See Also

History

VersionStatusNotes
10.2NewNew in this version.