The LIST function creates a new list. A list is a compound data type that contains elements of different data types, including any mixture of scalars, arrays, structures, pointers, object references, and other lists or hashes.
Lists have the following properties:
Note: While you can use familiar IDL array syntax to access elements in a list, it is important to remember that a list does not behave like an array in all cases. See below for a full description of the characteristics of a list.
Result = LIST( [Value1, Value2, ... Valuen] [, /EXTRACT] [, LENGTH=value] [, /NO_COPY])
Returns a reference to a newly-created list.
Each Value argument can be a variable or expression of any IDL data type including !NULL. If no Value argument is supplied, a reference to an empty list is returned.
Normally, if a Value argument refers to an array or a list, that array or list is inserted into the new list as a single element. If the EXTRACT keyword is specified, any Value argument that contains an array or a list will be disassembled, and each element of the array or list will be added to the new list as a separate element. The EXTRACT keyword has no effect if none of the Value arguments are arrays or lists.
Set this keyword to an integer value to create a list with the specified number of elements. If LENGTH is greater than the number of Value arguments, the Value arguments supplied are cyclically repeated to fill out the list. If no Value arguments are supplied, all list elements will contain the value !NULL.
If the NO_COPY keyword is set, the value data is taken away from the Value variable and attached directly to the list variable. The default behavior is to make a copy of the input values.
Create a list containing seven scalar values:
list=LIST('one', 2.0, 3, 4l, PTR_NEW(5), {n:6}, COMPLEX(7,0))
Create a list containing two arrays:
array1 = [2,3,4,5]
array2 = [2.0,3.0,4.0,5.0]
list1 = LIST(array1, array2)
PRINT, N_ELEMENTS(list1)
IDL Prints:
2
Create a list containing all of the elements of an array:
array1 = [2,3,4,5]
list2 = LIST(array1, /EXTRACT)
PRINT, N_ELEMENTS(list2)
IDL Prints:
4
The List::Add procedure method adds elements to an existing list. In its simplest form, List::Add places a single value on the end of the specified list. The optional Index argument allows you to insert an element at a specific list index. When used in conjunction with the List::Remove method, List::Add makes it easy to implement a stack or queue using a LIST variable.
list.Add,Value [, Index] [, /EXTRACT] [, /NO_COPY]
A variable or expression of any IDL data type including !NULL.
The zero-based index at which to insert the Value argument. The element that previously occupied the position specified by Index, and all elements that follow it, will have their index values incremented by one. If Index is not specified, the Value argument is added to the end of the list.
Normally, if the Value argument refers to an array or a list, that array or list is inserted into the list as a single element. If the EXTRACT keyword is specified, a Value argument that contains an array or a list will be disassembled, and each element of the array or list will be added to the new list as a separate element. The EXTRACT keyword has no effect if the Value arguments is neither an array nor a list.
If the NO_COPY keyword is set, the value data is taken away from the Value variable and attached directly to the list variable. The default behavior is to make a copy of the input values.
list = LIST(1, 2, 3)
list.Add, 4
PRINT, list
IDL Prints:
1 2 3 4
list.Add, 100, 0
PRINT, list
IDL Prints:
100 1 2 3 4
list.Add, [2.1, 2.2, 2.3], 3, /EXTRACT
PRINT, list
IDL Prints:
100 1 2 2.1 2.2 2.3 3 4
The List::Count function method returns the number of elements in the list. Optionally, the List::Count method can return the number of matches to a given value.
Result = list.Count( [Value] )
By default, returns an integer containing the number of elements in the list. If Value is supplied, returns an integer giving the number of occurrences of Value within the list.
Note: See the List::Where method for the rules that are used for comparing values.
A value to search for within the list.
None
The List::IsEmpty function method tests whether the list is empty or not.
Result = list.IsEmpty( )
Returns 1 if the list contains zero elements, and 0 otherwise.
None.
None.
The List::Remove method removes elements from a list and optionally returns the removed value.
list.Remove [, Indices] [, /ALL]
or
Value = list.Remove( [, Indices] [, /ALL] )
If List::Remove( ) is called with a single Index, it returns the value of the specified element.
If List::Remove( ) is called with multiple Indices (or the ALL keyword), it returns a new list containing the specified elements.
Note: If the list is empty, calling the List::Remove() function method will throw an error. The List::Remove procedure method will quietly return.
A scalar index or array of indices of list elements to be removed. If no Indices are supplied, the last element is removed.
Set this keyword to remove all entries in List, leaving the list empty, but still in existence.
Create a list and print its contents:
list = LIST(98.6, 'narwhal', [2, 4, 6, 8], COMPLEX(3,3))
PRINT, list
IDL Prints:
98.6
narwhal
2 4 6 8
( 3.00000, 3.00000)
Now delete some list elements and print the contents again:
list.Remove, [1, 3]
PRINT, list
IDL Prints:
98.6
2 4 6 8
Show the number of elements in the list:
PRINT, N_ELEMENTS(list)
IDL Prints:
2
Now remove the last element off the list, printing the removed value:
PRINT, list.Remove()
IDL Prints:
2 4 6 8
The List::Reverse procedure method reverses the order of elements in a list.
list.Reverse
None.
None.
Create a list, then reverse it and print its contents:
list = LIST(98.6, 'narwhal', [2, 4, 6, 8], COMPLEX(3,3))
list.Reverse
PRINT, list
IDL Prints:
( 3.00000, 3.00000)
2 4 6 8
narwhal
98.6
The List::ToArray function method returns an array containing all of the list values, converted to a single data type. The TYPE keyword may be used to control the result type, while the MISSING keyword may be used to control the behavior for missing or illegal values.
If the list contains all scalar values then the result will be a vector with the same number of elements as the list. If the list contains arrays of the same shape then the result will be an array of one higher dimension, where the first dimension will contains the same number of elements as the list, and the higher dimensions will match the array dimensions. For example, if the list contains 5 elements, each of which is a [10, 20] array, then the List::ToArray method will return a [5, 10, 20] array.
Note: If the list contains only one element, and it is a scalar, then the result will be a 1-element array.
Note: If the list contains only one element, and it is an array, then the result will be an array where the first dimension is 1. For example, if the list contains a single vector of length 100, then the result will be an array of dimensions [1, 100]. If you also use the /TRANSPOSE keyword then the trailing dimension of 1 will be dropped, and the result will simply be an array of the same dimensions as the list element.
Result = list.ToArray( [MISSING=value] [, /NO_COPY] [, /TRANSPOSE] [, TYPE=value] )
The result is an array containing all of the list values, converted to the same IDL data type. If the list is empty then !NULL is returned.
None.
Set this keyword to a value of the same type as the returned result. The default behavior of the List::ToArray method is to throw an error if a list element cannot be converted to the desired data type. If MISSING is set, and a list element cannot be converted, then the MISSING value is returned for that element. If the list contains arrays instead of scalars then MISSING may either be a scalar (in which case every element of a missing sub-array is set to that value) or MISSING may be an array of the same dimensions as the arrays within the list.
Set this keyword to move each element from the list to the output array. When finished, the list will be empty.
If the list contains arrays instead of scalars, then the default behavior is to have the first dimension contain the number of list elements. Set this keyword to transpose the resulting array so that the last dimension contains the list elements. For example, if the list contains 5 elements, each of which is a [10, 20] array, then by default the List::ToArray method will return a [5, 10, 20] array. If TRANSPOSE is set then the result will be a [10, 20, 5] array.
Set this keyword to an integer or a string giving the IDL type code of the result array. All values within the list will then be converted to this type. The default behavior is to use the type of the first element in the list.
Create a list of mixed types, then return an array of a single type:
list = LIST(1, '23', 3.14, COMPLEX(4))
; Default behavior is to return the same type as the first element
arr = list.ToArray()
HELP, arr
PRINT, arr
IDL Prints:
ARR INT = Array[4]
1 23 3 4
Now force the data type to be different:
list = LIST(1, '23', 3.14, COMPLEX(4))
arr = list.ToArray(TYPE='FLOAT')
HELP, arr
PRINT, arr
IDL Prints:
ARR FLOAT = Array[4]
1.00000 23.0000 3.14000 4.00000
Now add some non-numeric values, and use the MISSING keyword:
list = LIST(1, 'oops', 3.14, !NULL)
arr = list.ToArray(TYPE='INT', MISSING=-99)
HELP, arr
PRINT, arr
IDL Prints:
ARR INT = Array[4]
1 -99 3 -99
Create a list of arrays, then return an array of higher dimension:
list = LIST(FINDGEN(10), INDGEN(10), BYTARR(10))
; Default behavior is to return the same type as the first element
HELP, list.ToArray()
; Now use the TRANSPOSE keyword to flip the dimensions
HELP, list.ToArray(/TRANSPOSE)
IDL Prints:
ARR FLOAT = Array[3, 10]
ARR FLOAT = Array[10, 3]
The List::Where function method returns an array of indices for those list elements that are equal to a certain value.
Note: The method call list.Where(Value) is equivalent to calling WHERE(list EQ Value), and is simply provided as a programming convenience.
Result = list.Where( Value [, COMPLEMENT=variable] [, COUNT=variable] [, NCOMPLEMENT=variable] )
Returns an array of integers containing the list subscripts. If there are no matches, !NULL is returned. The following rules are used when comparing values:
A variable or expression of any IDL data type, including !NULL.
Set this keyword to a named variable that will return an array of integers containing the list subscripts that do not contain the value.
Set this keyword to a named variable that will return the number of matches.
Set this keyword to a named variable that will return the number of indices within the COMPLEMENT array.
The following example generates a random integer and an array of ten random integers (both between 0 and 9). The sample uses Where to determine if there are any matches of the value in the list.
rndmVal = FIX(10 * RANDOMU(seed, 1))
rndmArr = FIX(10 * RANDOMU(seed, 10))
l = LIST(rndmArr, /EXTRACT)
matches = l.Where(rndmVal)
PRINT, 'Random value = ', rndmVal
PRINT, 'Random array = ', rndmArr
PRINT, 'Matching indices = ', matches
Sample output:
Random value = 7
Random array = 6 9 4 7 2 5 9 5 7 8
Matching indices = 3 8
To combine two lists to make a new list, use the + operator:
list1 = LIST('zero', 1, 2.0)
list2 = LIST(!PI, COMPLEX(4,4), [5,5,5,5,5])
list3 = list1 + list2
PRINT, list3
IDL Prints:
zero
1
2.00000
3.14159
( 4.00000, 4.00000)
5 5 5 5 5
Note that
list3 = list1 + list2
is exactly equivalent to:
list3 = LIST()
list3.Add, list1, /EXTRACT
list3.Add, list2, /EXTRACT
The EQ operator does an element-by-element comparison. The operator syntax is list1 EQ list2, and EQ returns a byte array of 1s (the elements are equal) or 0s (the elements are not equal). The length of the result is the length of the shortest list. If both lists are empty lists, the scalar value 1 is returned.
Note: See the List::Where method for the rules that are used for comparing values.
To compare two lists:
list1 = LIST('alpha', 5, 19.9)
list2 = LIST('alpha', 'abc', 19.9)
PRINT, list1 EQ list2
IDL Prints:
1 0 1
When comparing each element of a list with a value (a scalar or array of any type) of the form list EQ value, the EQ operator returns a byte array of 1s or 0s. The length of the result is the length of the list. If the list is an empty list, the scalar value 0 is returned.
To compare a list with a scalar value:
list3 = LIST('beta', 99, 300.73)
value = 99
PRINT, list3 EQ value
IDL Prints:
0 1 0
To compare a list with an array:
list4 = LIST(3, 7, 9, 12, [4, 33, 9, 64, 43], 'alpha')
array = [4, 33, 9, 64, 43]
PRINT, list4 EQ array
IDL Prints:
0 0 0 0 1 0
Note: IDL treats the array as a single item for the comparison.
The NE operator behaves in the opposite manner of EQ. Instead of returning the byte value 1 for a match, NE returns the byte value 1 if two list elements are not a match.
In many cases, you can access elements of a list variable using standard IDL array syntax, as if the list were a one-dimensional array.
To copy the value of a single list element into a new variable, leaving the list unchanged, use array syntax:
value = list[Index]
where Index is the zero-based index of the desired element within the list. Negative indices may be used to index from the end. For example, list[-1] would retrieve the last element.
To retrieve the last element in a list and remove it, use the list.Remove function method:
value = list.Remove()
To retrieve a specific element in a list and remove it:
value = list.Remove(Index)
where Index is the zero-based index of the desired element within the list.
To insert a single value at the end of a list, creating a new list element, use the list.Add method:
list.Add, Value
where Value is the value to be stored in the new list element.
To insert a single value at a specified position within a list:
list.Add, Value, Index
where Value is the value to be stored in the new list element, and Index is the zero-based index of the position at which the element should be inserted.
To change the value of a single list element, use array syntax:
list[Index] = Value
where Index is the zero-based index of the desired element within the list and Value is the new value.
To create a new list that is a subset of an existing list, use array syntax:
newList = origList[ [Index0, Index1, ..., Indexn-1] ]
Here newList is a new list variable that contains copies of the elements from origList specified by the indices Index0, Index1, ..., Indexn-1.
You can also create a sub-list using the array minimum and maximum index syntax:
newList = origList[minIndex:maxIndex]
For example:
newList = origList[4:8]
would create a new list variable consisting of the fifth through ninth elements of origList.
Similarly, you can use the minimum, maximum, and stride syntax:
newList = origList[minIndex:maxIndex:stride]
For example:
newList = origList[3:15:3]
would create a new list variable consisting of elements 3, 6, 9, 12, and 15 of origList.
To insert multiple elements into an existing list, use list.Add with an array or list as the argument, and set the EXTRACT keyword. By default, elements are inserted at the end of the list; include the Index argument to specify where in the list the new elements should be inserted:
list.Add, array, /EXTRACT
list.Add, otherList, /EXTRACT
list.Add, otherList, Index, /EXTRACT
For example:
list.Add, [2,3,6,8], /EXTRACT
inserts four integers at the end of list.
Similarly, to insert the values from another list at the beginning of the target list:
subList = LIST('zero', 1, 2.0)
list.Add, subList, 0, /EXTRACT
Here, the string 'zero', the integer 1, and the floating point number 2.0 are inserted into list as the first three elements.
Change the value of multiple list elements in a single operation by specifying the indices to be replaced in the existing list and providing the replacement values in another list:
list[[Index1, Index2, ..., Indexn]] = otherList
list[minIndex:maxIndex] = otherList
list[minIndex:maxIndex:stride] = otherList
Note that the expressions on the left and right sides of the equals sign must specify the same number of elements.
To copy a list reference, simply assign it to a new variable:
newList = origList
It is important to understand that with this operation, newList and origList are references to the same list; modifying an element in one list modifies the same element in the other list. For example, if we create list2 as a copy of list1 and then change the value of an element in list2, the same element in list1 also changes:
list1 = LIST('zero', 1, 2.0)
list2 = list1
list2[0] = 0L
HELP, list1[0], list2[0]
IDL Prints:
<Expression> LONG = 0
<Expression> LONG = 0
Note that both lists contain the new value for the first element.
To create a new list variable whose elements are copies of the values in the original list, use array syntax to copy all of the elements of the original list:
newList = origList[*]
For example:
list1 = LIST('zero', 1, 2.0)
list2 = list1[*]
list2[0] = 0l
HELP, list1[0], list2[0]
IDL Prints:
<Expression> STRING = 'zero'
<Expression> LONG = 0
Note that the value in list1 remains unchanged.
To iterate through the elements in a list, use a loop and standard array syntax to index each list element:
FOR i = 0, N_ELEMENTS(list)-1 DO BEGIN
; do something with each element
PRINT, list[i]
ENDFOR
For example:
list = LIST('zero', 1, 2.0)
FOR i=0, N_ELEMENTS(list)-1 DO PRINT, list[i]
You may also use FOREACH to iterate over the list elements:
list = LIST(77.97, 'Galactic', [2, 7, 1, 8, 2])
FOREACH element, list DO BEGIN
PRINT, 'Element = ', element
ENDFOREACH
If a list item contains an array, another list, or a hash, individual elements within that item may be accessed and modified using standard array syntax. In this case, the first dimension must be a scalar that specifies the list element, and the higher dimensions are used to index into the array itself. The higher dimensions may be any combination of scalars, subscript ranges, or index arrays. The syntax looks like:
values = list[index, sub0, sub1,...]
list[index, sub0, sub1,...] = values
where index is a scalar that specifies the list element, and sub0, sub1,... are the subscript ranges or indices for the contained array.
For example, to create a "ragged" array, where each element is a vector of a different length:
list = LIST( FINDGEN(100), FINDGEN(67), FINDGEN(93), FINDGEN(120) )
; Print the 6th element of the first vector
print, list[0, 5]
; Print every other element of the 3rd vector
print, list[2, 0:*:2]
; Change several elements of the 4th vector
list[3, [5,10,15,20]] = -1
In this example, we create a list that contains some strings and a two-dimensional array:
list = LIST( 'Sensor Data', 'April 1, 2001', HANNING(100, 50) )
; Modify the element in the center of the array
list[2, 50, 25] = 0.0
; Change an entire column of the array
list[2, 99, *] = -1.0
; Extract a subset of the array
help, list[2, 10:15, 7:11]
IDL prints:
<Expression> FLOAT = Array[6, 5]
In this example, we create a list that contains another list (which contains an array) and a hash:
list = LIST( 'Sensor Data', 'April 2', $
LIST('MyData', DIST(20, 30)), $
HASH('LINESTYLE', 3, 'THICK', 2) )
; Extract the entire array from the sub-list
help, list[2, 1]
; Extract a subset of the array within the sub-list
help, list[2, 1, 10:15, [20,21,22] ]
; Add a new key-value to the hash within the list
list[3, 'COLOR'] = 'blue'
; Extract a value from the hash
help, list[3, 'COLOR' ]
IDL prints:
<Expression> FLOAT = Array[20, 30]
<Expression> FLOAT = Array[6, 3]
<Expression> STRING = 'blue'
Note: When indexing into an array contained within a list, the first dimension must always be the index of the list element. Since IDL can only handle a maximum of eight dimensions, you can only use up to seven dimensions when indexing into an array within a list. If the array is contained within a list (which is itself contained within a list), the maximum number of dimensions will be six, and so on.
The logical truth operator evaluates a list. It returns a value of 1 (TRUE) if the list is non-empty, and returns 0 (FALSE) if the list is empty.
IF (list) THEN . . .
The logical negation operator negates the logical value of a list:
IF (~list) THEN . . .
If list is TRUE, the statement evaluates as FALSE, and so on.
The N_ELEMENTS function returns the number of elements in a list:
Result = N_ELEMENTS(list)
If list contains zero elements, or if list is an undefined variable, 0 is returned.
For more information, see N_ELEMENTS .
The ISA function can determine whether the given variable is a list:
x = LIST('apple', 99, 57.3)
PRINT, ISA(x, 'LIST')
IDL prints:
1
For more information, see ISA.
The TYPENAME function returns the type LIST for a list variable:
x = LIST(1, 'hello', 5.0)
PRINT, TYPENAME(x)
IDL prints:
LIST
For more information, see TYPENAME.
The HELP procedure provides general information about a list variable:
newList = LIST('apple', 99, 27.3, [10, 20, 30])
HELP, newList
IDL prints:
NEWLIST LIST <LIST ID=1 NELEMENTS=4>
In this case, the variable name is NEWLIST, the type name is LIST, the heap ID is 1, and there are four elements in the list.
The PRINT procedure gives the value for each list element:
newList = LIST('apple', 99, 27.3, [10, 20, 30])
PRINT, newList
IDL prints:
apple
99
27.3000
10 20 30
|
8.0 |
Introduced |
|
8.1 |
Added NO_COPY keyword to ToArray function method Added ability to index into arrays within a list Added Count, FindValue, IsEmpty methods |
| 8.2 | Added the Where method, deprecated the FindValue method |