ListSetAt

Description

Replaces the contents of a list element.

Returns

A copy of a list, with a new value assigned to the element at a specified position.

Function syntax

ListSetAt(list, position, value [, delimiters, includeEmptyValues ])

History

ColdFusion MX: Changed delimiter modification: ColdFusion MX does not modify delimiters in the list. (In earlier releases, in some cases, replaced delimiters with the first character in the delimiters parameter.)

Parameters

Parameter	Description
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 set a value. The first list position is 1.
value	An element or a list of elements.
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.

Usage

When assigning an element to a list, ColdFusion inserts a delimiter. If delimiters contains more than one delimiter, ColdFusion uses the first delimiter in the string, or, if delimiters was omitted, a comma. ColdFusion ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.

Example

<h3>ListSetAt 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.Subject)> 

<!--- loop through the list and show it with ListGetAt ---> 
<h3>This is a list of <cfoutput>#ListLen(temp)#</cfoutput> 
subjects posted in messages.</h3> 

<cfset ChangedElement = ListGetAt(temp, 2)> 
<cfset TempToo = ListSetAt(temp, 2, "I changed this subject", ",")> 
<ul> 
<cfloop From = "1" To = "#ListLen(temptoo)#" INDEX = "Counter"> 
<cfoutput><li>(#Counter#) SUBJECT: #ListGetAt(temptoo, Counter)# 
</cfoutput> 
</cfloop> 
</ul> 
<p>Note that element 2, "<cfoutput>#changedElement#</cfoutput>", 
has been altered to "I changed this subject" using ListSetAt.