List Functions

list ( list op list )

Operation between two lists. op is one of the operators below :

The boolean operators are :

list ( list op number )
list ( number op list )

Operations between lists and numbers. op is any of the operations defined above.

list ( list and list )
list ( list or list )
list ( not list )

Conjunction, Disjunction and Negation.

list ( list and number ) list ( number or list )

Boolean operations between lists and numbers.

any list[number]
list list[number,number]
list list[number,number,number]

Apply the [] to a list to return element(s) from that list. Note that array indices start at 1 :

• mylist[n] returns the nth element of mylist

• mylist[n,m] returns the nth to the mth elements of mylist

• mylist[n,m,i] returns every ith of the nth to the mth elements of mylist

# copies elements 1, 5, 9, 13, 17 of x into y
Y = X[1,20,4]

list list[vector]

Extract a selection of elements from a list. The vector supplied as the argument provides the set of indices to be used. For example:   

# copies elements 2, 1, 3 from x to y
i = |2,1,3|
y = x[i]
 

number ( any in list )
number ( any not in list )

Tests whether a value is in a list or not. Returns a 0 (false) or 1 (true)

list ( list & list )

Concatenate two lists. Note that to add a single element to a list, it must first be converted into a single-element list, for example:

mylist = mylist & [23]

list abs( list )
list acos( list )
list asin( list )
list atan( list )
list cos( list )
list exp( list )
list int( list )
list log( list )
list log10( list )
list neg( list )
list sgn( list )
list sin( list )
list sqrt( list )
list tan( list )
list div( list,list )
list max( list,list )
list min( list,list )
list max( list,number )
list min( list,number )
list mod( list,list )

Computational functions – the function is applied to each element in the list; for functions that take two lists as arguments, both lists must have the same number of elements. For example, calling sin on a list of numbers will internally call sin(number) for each element of the input list, putting the results into a new output list. This helps avoid the need to write loops to process data in some circumstances. Note that for large data sets (1000s of values), the vector data type is more efficient for numeric computations.

To take sin as an example, the following two pieces of code are exactly equivalent:

b = [1, 5, 9, geopoints, fieldset]
a = sin(b)                # version 1


a = nil                   # version 2
for i = 1 to count(b) do  # version 2
    a = a & [sin(b[i])]   # version 2
end for                   # version 2

This shows that the types of the elements in the input lists are not restricted – a list can contain many different data types (e.g. [number, vector, geopoints]) and as long as the requested function is valid for each type, the correct result will be returned. If the requested operation is illegal for that element (e.g. sin(['hello'])) then it will fail on that element. See the descriptions of these functions for the relevant data types.

number count( list )

Returns the number of elements in a list.

number or list find( list,any )
number or list find( list,any,string )

Searches the given list for an item and returns the index of the first occurrence of it. If an optional third argument is given as the string 'all', then a list of the indexes of all occurrences of the item is returned. In both cases, if the item is not contained in the list, nil is returned.

list list( any,any,...)

Returns a list built from its arguments.

list sort( list )

Sorts a list in ascending order.

list sort( list,string )

Sorts a list given a comparison, expressed as a string : Ascending "<", descending ">"; you may specify the sorting criterium in a comparison function :

function compare(a,b)
    return a < b
end compare 

numbers = [1,5,3,9,0,4,6,7,8,2]


print (sort(numbers, ">"))       # prints in decreasing order
print (sort(numbers, "compare")) # prints in ascending order

Note that it is not valid to sort a list which contains more than one type of data element.

list sort_indices( list )
list sort_indices( list,string )

Sorts a list and returns the sorted indices. The default behaviour is to sort in ascending order unless an alternative comparison function is provided. See example under sort_and_indices() to see how this function works.

list sort_and_indices( list)
list sort_and_indices( list,string )

Sorts a list and returns a list of pairs of list items and their corresponding indices in the original list. The default behaviour is to sort in ascending order unless an alternative comparison function is provided. The following example illustrates sort_indices() and sort_and_indices():

original = [10, 12, 9, 7, 6]
comparison = "<"

sorted_list = sort (original, comparison)
sorted_indices = sort_indices (original, comparison)
sorted_both = sort_and_indices (original, comparison)

print ('Original list : ', original)
print ('Sorted list : ', sorted_list)
print ('Sorted indices : ', sorted_indices)
print ('Sort and indices : ', sorted_both)

Note that in this example it is not necessary to provide a comparison operator, as "<" is the default anyway. The output is as follows:

Original list    : [10,12,9,7,6]
Sorted list      : [6,7,9,10,12]
Sorted indices   : [5,4,3,1,2]
Sort and indices : [[6,5],[7,4],[9,3],[10,1],[12,2]]

list unique( list )

Returns a list of the unique elements in the input list.

vector vector( list )

Returns a vector containing the numeric elements of the input list. Any nil list elements are converted to vector_missing_value. Any other non-numeric elements will cause an error. If the input list is empty, the function returns nil.