Skip to main content
Previous section   Next section

ListGet

Returns an element from a list.

Synopsis

ListGet(list[,position[,default]])

Arguments

list An expression that evaluates to a valid list. A Caché list must be created using ListBuild or ListFromString, or extracted from another list using List.
position Optional — An integer specifying the position of the element (counting from 1).
default Optional — An expression that provides the value to return if the list element has an undefined value.

Description

ListGet returns the requested element in the specified list. If the value of position refers to a nonexistent member or identifies an element with an undefined value, the specified default value is returned.

The ListGet function is identical to the one- and two-argument forms of the List function except that, under conditions that would cause List to produce a <NULL VALUE> error, ListGet returns a default value. See the description of the List function for more information on conditions that return <NULL VALUE> errors.

Arguments

position

An integer that specifies the target list element. If it is omitted, the function defaults to examine the first element of the list. If the value of position is -1, ListGet examines the last element of the list.

default

Supplies a default value to return when the element has no value. For example, an omitted element (1,,3) or an undefined variable (1,x,3). The default is not returned for an empty (zero-length) string value. If you omit the default argument, a zero-length string is assumed for the default value.

Examples

The following example demonstrates how to use the ListGet function:

myList = ListBuild("Red","Blue",,"Yellow")
Println ListGet(myList)           ' prints Red
Println ListGet(myList,2,"White") ' prints Blue
Println ListGet(myList,3,"White") ' prints White
Copy code to clipboard

The following example shows the difference between an undefined value and an empty string value:

myList = ListBuild("Red","",,"Yellow")
Println "Empty: ",ListGet(myList,2,"White")   ' prints empty string
Println "Default: ",ListGet(myList,3,"White") ' prints White
Copy code to clipboard

See Also