Skip to main content

List

Returns elements from a list.

Synopsis

List(list[,position[,end]])

List(list[,position[,end]])=value

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 that specifies the position of the list element to return, or the beginning of a sublist range if end is specified. Specify an expression that evaluates to a non-zero positive integer. You can use –1 to specify the last element in the list. If position is not specified, it defaults to 1 (the first element in list).
end Optional — An integer that specifies the position of the list element which is the final element in the sublist range. Specify an expression that evaluates to an integer. Use –1 to specify the last element in the list.

Description

List returns elements from a list. The elements returned depend on the specified arguments.

  • List(list) returns the first element string in the list.

  • List(list,position) returns the element indicated by the specified position. The position argument must evaluate to an integer. List elements are numbered beginning with 1.

  • List(list,position,end) returns a “sublist” containing the elements of the list from the specified start position through the specified end position, inclusive.

You can also use ListNext to sequentially return elements from a list.

Arguments

list

An encoded list string containing one or more elements. Lists can be created using ListBuild or ListFromString, or extracted from another list by using the List function. The following are valid list arguments:

myList = ListBuild("Red", "Blue", "Green", "Yellow")
Println List(myList, 2) 'prints Blue
subList = List(myList,2,4)
Println List(subList, 2) 'prints Green

In the following example, subList is not a valid list argument, because a List returns a single element as an ordinary string, not an encoded list string:

myList = ListBuild("Red", "Blue", "Green", "Yellow")
subList = List(myList,2)
Println List(subList,1)  ' INVALID OPERATION

Attempting to use the List function on an ordinary string generates a runtime error.

position

The position of a list element to return. List elements are counted from 1. If position is omitted, the first element is returned. If the value of position is 0 or greater than the number of elements in the list, Caché issues a <NULL VALUE> error. If the value of position is negative one (–1), List returns the final element in the list.

If the end argument is specified, position specifies the first element in a range of elements. Even when only one element is returned (when position and end are the same number) this value is returned as an encoded list string. Thus, List(x,2) is not identical to List(x,2,2), as shown in the following example:

MyList = ListBuild("A","B","C")
x = List(MyList,2)
y = List(MyList,2,2)
If x=y Then
  Println "Lists are identical"
Else
  Println "Lists not identical"
End If

end

The position of the last element in a range of elements. You must specify position to specify end. When end is specified, the value returned is an encoded list string. Because of this encoding, such strings should only be processed by other List functions.

If the value of end is:

  • greater than position, an encoded string containing a list of elements is returned.

  • equal to position, an encoded string containing the one element is returned.

  • less than position, the null string ("") is returned.

  • greater than the number of elements in list, it is equivalent to specifying the final element in the list.

  • negative one (–1), it is equivalent to specifying the final element in the list.

When specifying end, you can specify a position value of zero (0). In this case, 0 is equivalent to 1.

Note that List(list,1) is not equivalent to List(list,1,1) because the former returns a string, while the latter returns a single-element list. Furthermore, the first can receive a <NULL VALUE> error, whereas the second cannot; if there are no elements to return, it returns a null string.

fruit = ListBuild("apple","banana","pear")
PrintLn List(fruit,1)
PrintLn List(fruit,1,1)

List Errors

The following List argument values generate an error:

  • If the list parameter does not evaluate to a valid list, List generates a <LIST> error. You can use the ListValid function to determine if a list is valid.

  • If the list parameter evaluate to a valid list that contains a null value, or concatenates a list and a null value, List generates a <NULL VALUE> error. All of the following are valid lists (according to ListValid) for which List generate a <NULL VALUE> error:

    PrintLn List("")
    PrintLn List(ListBuild())
    PrintLn LIST(ListBuild(NULL))
    PrintLn LIST(ListBuild(,))
    PrintLn LIST(ListBuild() & ListBuild("a","b","c"))
  • If the position parameter is 0 or a fractional number less than 1 and no end parameter is used, List generates a <NULL VALUE> error.

  • If the value of the position parameter refers to a nonexistent list member and no end parameter is used, List generates a <NULL VALUE> error.

  • If the value of the position parameter identifies an element with an undefined value, and no end parameter is used, List generates a <NULL VALUE> error.

  • If the value of the position parameter or the end parameter is less than -1, List generates a <RANGE> error.

Setting List

You can use List on the left of the equal sign to replace a specified element in a list with another element value. You can perform the following operations:

  • Replace one element value with a new value:

    fruit = ListBuild("apple","banana","pear")
    PrintLn List(fruit,2)
    List(fruit,2) = "orange"
    PrintLn List(fruit,2)
  • Replace a range of element values with the same number of new values:

    fruit = ListBuild("apple","peach","pear","plum")
    PrintLn List(fruit,2)," ",List(fruit,3)
    List(fruit,2,3)=ListBuild("orange","banana")
    PrintLn List(fruit,2)," ",List(fruit,3)
  • Replace a range of element values with a larger or smaller number of new values:

    fruit = ListBuild("apple","pear","plum","tangerine")
    PrintLn List(fruit,2)," ",List(fruit,3)," ",List(fruit,4)
    List(fruit,2,3)=ListBuild("orange","banana","peach")
    PrintLn List(fruit,2)," ",List(fruit,3)," ",List(fruit,4)," ",List(fruit,5)
  • Remove an element or a range of element values:

    fruit = ListBuild("apple","pear","plum","tangerine")
    PrintLn List(fruit,2)," ",List(fruit,3)," ",List(fruit,4)
    List(fruit,2,3)=""
    PrintLn List(fruit,2)

To replace the final element in a list use a position of -1. Note that List(inlint,-1)=value and List(inlint,-1,-1)=value perform different operations: List(inlint,-1)=value replaces the value of the last element; List(inlint,-1,-1)=value deletes the last element, then appends the specified list.

To remove the final element of a list, use List(inlint,-1,-1)="".

Examples

The following examples demonstrates how to use the List function:

myList = ListBuild("Red","Blue","Green","Yellow")
color4 = List(myList,4) ' returns value of the 4th element
Println color4             ' prints Yellow
sublist = List(myList,2,3) ' returns the 2nd and 3rd elements as a list
Println List(sublist,1)    ' prints Blue

Because multi-element lists contain non-printing list encoding characters, Println should only be used to display single list items.

See Also

FeedbackOpens in a new tab