listGetAt

Description

Gets a list element at a specified position.

Syntax

ListGetAt(list, position [, delimiters, includeEmptyValues ])

Attributes

Attribute	Description	Required	Default
delimiters	A string or a variable that contains one. Characters that separate list elements. The default value is comma. If this parameter contains more than one character, ColdFusion processes each occurrence of each character as a delimiter.
includeEmptyValues	Optional. Set to yes to include empty values.
list	A list or a variable that contains one.
position	A positive integer or a variable that contains one. Position at which to get element. The first list position is 1.

Returns

Value of the list element at position position.

Usage

If you use list functions on strings that are delimited by a delimiter character and a space, a returned list element might contain a leading space; you use the trim function to remove such spaces from a returned element. For example, consider this list:
<cfset myList = "one hundred, two hundred, three hundred"> To get a value from this list, use the trim function to remove the space before the returned value:
<cfset MyValue = #trim(listGetAt(myList, 2))#> With this usage, MyValue = "two hundred", not " two hundred", and spaces within a list element are preserved.
ColdFusion ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.

Example

<h3>ListGetAt Example</h3> 
<!--- Find a list of users who wrote messages ---> 
<cfquery name = "GetMessageUser" datasource = "cfdocexamples"> 
    SELECT Username, Subject, Posted 
    FROMMessages 
</cfquery> 
<cfset temp = ValueList(GetMessageUser.Username)> 
<!--- loop through the list and show it with ListGetAt ---> 
<h3>This list of usernames who have posted messages numbers 
<cfoutput>#ListLen(temp)#</cfoutput> users.</h3> 
<ul> 
<cfloop From = "1" To = "#ListLen(temp)#" index = "Counter"> 
    <cfoutput><li>Username #Counter#: #ListGetAt(temp, Counter)# </cfoutput> 
</cfloop> 
</ul>

cfmldocs