Working with Lists and Associative Arrays

Programmer Guide > Working with Structures > Working with Lists and Associative Arrays

Lists and associative arrays allow you to create dynamic data structures in PV‑WAVE. Lists contain collections of variables and/or expressions. An associative array is like a list, except each element in an associative array is given a unique name. This name is then used to reference its associated array element.

Unlike other kinds of arrays, the elements of a list or associative array do not have to be the same data type. Furthermore, the contents and size of lists and associative arrays can be modified dynamically, while an application is running.

note	A list or associative array definition creates a new data type.

A list and Associative Array shows a list, on top, consisting of an array of variables and expressions, which do not have to be of the same data type. An associative array, shown on the bottom, consists of pairs of key names (strings) and values (variables or expressions). A list is referenced using subscript numbers, just like a 1D array. The elements of an associative array are referenced by key name.

Figure 6-1: A list and Associative Array

Defining a List

Use the LIST function to create a list:

result = LIST(expr1 ,..., exprn)

where expr1 , ..., exprn are expressions or variables. These expressions or variables are the elements of the list array.

The elements of a list can be any of the nine basic PV‑WAVE data types, other structures or arrays of structures, and other lists or associative arrays. In addition, lists and associative arrays can be used as structure fields.

Example

A list is created using the LIST function. The elements in the list do not have to have the same data type.

lst = LIST(1B, 2.2, '3.3', {,a:1, b:lindgen(2)})

The INFO command shows the contents of the list.

INFO, lst, /Full

; PV-WAVE prints the following:

; LST  LIST = List(4)

; BYTE  = 1

; FLOAT   = 2.20000

; STRING   = '3.3'

; STRUCT   = ** Structure $1, 2 tags, 24 length:

; A  INT 1

; B  LONG Array(2)

The PRINT command also shows the contents of the list.

PRINT, lst

; PV-WAVE prints: {   1    2.200003.3{    1    0    1}

Defining an Associative Array

Use the ASARR function to create an associative array. You can call ASARR in the following two ways:

result = ASARR(key1, expr1 , ..., keyn, exprn)

where key1, expr1 , ..., keyn, exprn are pairs of key names (strings) and expressions or variables. A key name is a string that uniquely identifies the expression or variable that immediately follows.

result = ASARR(keys_arr, values_list)

where keys is an array of key names (strings) and values is a list array containing the expressions and/or variables. The first element in the keys array is paired with (and uniquely identifies) the first element in the values array, and so on.

Example 1

An associative array is created using the first form of the ASARR function. Key names and values are specified as separate parameters.

as = ASARR('byte', 1B, 'float', 2.2, 'string', $
'3.3', 'struct', {,a:1, b:lindgen(2)})

Example 2

An associative array, equivalent to the array in Example 1, is created using the second form of the ASARR function, described previously. An array of key names is created first, followed by an array of values. Note that the values do not have to be of the same data type.

as=ASARR(['byte', 'float', 'string', 'struct'], $
LIST(1B, 2.2, '3.3', {,a:1, b:lindgen(2)}))

The INFO command shows the contents of the associative array.

INFO, as, /Full

; PV-WAVE prints the following:

; AS  AS. ARR  = Associative Array(4)

; byte  BYTE  = 1

; struct  STRUCT  = ** Structure $3, 2 tags, 12 length:

; A INT  1

; B LONG  Array(2)

; float  FLOAT  = 2.20000

; string  STRING  = '3.3'

The PRINT command also shows the contents of the array.

PRINT, as

; PV-WAVE prints the following:

; {'byte' 1 'struct'{ 1 0 1} 'float' 2.20000 'string'3.3 }

Defining a List within a Structure within an Associative Array

The following example shows how to nest a structure and a list within an associative array. This example has applications in GUI tool development, where associative arrays can be used to store information about the attributes of a GUI tool.

; Define a data structure to hold variables and attributes for a

; GUI tool.

strDef = {Main_Data_Str, attrs:ASARR(), vars: LIST()}

; Create an empty associative array that will hold the GUI tool

; data structure. This array will be filled in later, possibly

; in another procedure.

dataStr = ASARR()

; Call the tool Wg1.

dataStr('Wg1') = {Main_Data_Str}

; Set a size attribute for the Wg1 tool.

dataStr('Wg1').attrs('size') = [512, 512]

; Set a list of variables for the Wg1 tool.

dataStr('Wg1').vars = LIST('VAR1', 'VAR2')

How to Reference a List

To reference elements in a list, follow the same rules as you would to reference elements of any 1D array:

variable_name(subscript_list)

where variable_name is a variable that contains a list, and subscript_list is a list of expressions, constants, or subscript ranges containing the values of one or more subscripts.

Nested lists are subscripted like multi-dimensional arrays:

variable_name(subscript, subscript, ...)

note	If the elements of nested lists are of type structure or associative array, they follow the same rules for referencing structures or associative arrays.

How to Reference an Associative Array

The basic syntax of a reference to a element of an associative array is:

variable_name (key_name)

where variable_name must be a variable that contains an associative array, and key_name is the name of the key (a string) and must exist for the associative array.

Embedded, nested associative arrays use a subscripting scheme similar to that of multi-dimensional arrays:

variable_name(key_name1, key_name2, ...)

note	If the elements of nested associative arrays are of type structure or list, they follow the rules for subscripting structures or lists.

Supported Operations for Lists

You can perform the following kinds of operations on lists.

Insert

Insert elements expr1 , ..., exprn between the (i–1)-th and i-th element of the list.

lst = [lst(0:i-1), expr1,..., exprn, lst(i:*)]

Append

Append elements expr1, ..., exprn after the last element in the list.

lst = [lst, expr1,..., exprn]

Prepend

Prepend elements expr1, ..., exprn before the first element in the list.

lst = [expr1,...,exprn, lst]

Replace

Replace elements between element start and element end with the elements expr1, ..., exprn .

lst = [lst(0:start), expr1,...exprn, lst(end:*)]

Delete

Delete elements between element start and element end.

lst = [lst(0:start), lst(end:*)]

Create Sublists

The method for creating sublists is the same as creating subarrays. For example:

; Create a sublist from a specific range of elements.

sublist = lst(from:to)

; Create a sublist from a specified element to the last element.

toend   = lst(from:*)

; Create a sublist from the first element to a specified element.

startto = lst(0:to)

; Create a sublist containing specified elements only.

sublist = lst([0,2,5])

Enumeration

Lists can be referenced in loops just like other kinds of arrays:

FOR i = 0, N_ELEMENTS(lst) - 1 do BEGIN

; do something with the variable

lst(i) = lst(i) + 1

ENDFOR

Supported Operations For Associative Arrays

You can perform the following kinds of operations on associative arrays:

Create a New Element

If the associative array asa exists, the following statement adds a new expression to the array with the given key name:

asa('newkey') = expr

Concatenate

The following statement concatenates the associative arrays asa1, asa2, ... , asan in the associative array asa_new.

asa_new = [asa1, asa2,..., asan]

Subset

The following statement creates a new associative array that is a subset of an existing associative array.

note	Only the key names are required to specify the subset.

asa_sub = asa(['key1', 'key2'])

Retrieve Keys

The ASKEYS function returns the key names for an associative array.

keys = ASKEYS(asa)

The following statements show how you can enumerate associative array elements.

keys = ASKEYS(asa)

for i = 0, N_ELEMENTS(asa) - 1 do asa(keys(i)) = expr

Test for Keys

The ISASKEY function lets you test for the presence of a key name in an associative array.

result = ISASKEY(asa, 'key')

Lists, Associative Arrays Input and Output

To read and write lists and associative arrays, use the procedures READ, READF, PRINT, and PRINTF. Lists and associative arrays are transferred in much the same way as simple data types, with each element of the list or associative array transferred in order.

Writing a List or Associative Array with PRINT or PRINTF

You can write a list or an associative array with PRINT or PRINTF. By default, each element of the list or associative array is output in the default format of the element's data type. The entire list or associative array is enclosed in { } (braces). Each value of an associative array element is preceded by the key name enclosed in ” ” (double quotes).

Example

The contents of an associative array are printed with the PRINT command. This example uses the same code used to demonstrate nesting.

; Define a data structure to hold variables and attributes.

strDef = {Main_Data_Str, attrs:ASARR(), vars: LIST()}

; Create an empty associative array that will hold the GUI tool

; data structure. This array will be filled in later, possibly

; in another procedure.

dataStr = ASARR()

; Call the tool Wg1 and set a size attribute for the Wgl tool.

dataStr('Wg1') = {Main_Data_Str}

dataStr('Wg1').attrs('size') = [512, 512]

; Set a list of variables for the Wg1 tool.

dataStr('Wg1').vars = LIST('VAR1', 'VAR2')

; Print the contents of the associative array.

PRINT, dataStr

; PV-WAVE prints: {'Wg1'{{'size' 512 512}{ VAR1 VAR2}}}

Reading a List or Associative Array with READ or READF

You can read data into an associative array or list using the READ or READF function. This is similar to reading data into a structure; however, associative array elements must be read in a particular order. You can determine this order with the ASKEYS function, as shown in the following example:

; Create an associative array.

as = ASARR('byte', 1B, 'float', 2.2, 'string', $
'hello', 'struct', {,a:1, b:lindgen(2)})

; Get the correct order of elements in the associative array.

; Note that the order is different than the order of the

; parameters in the ASARR function used to create the array.

PRINT, ASKEYS(as)

; PV-WAVE prints: byte struct float string

; Read in some data. Input to READ and READF must be separated

; by at least one space.

READ, as

: 4 5 6 7 8.8 hello

PRINT, as

; PV-WAVE prints: {”byte”   4 ”struct”{   5   6   7 }

; PV-WAVE prints: ”float”     8.80000 ”string” hello}

Version 2017.1