ListAppend

Description

Concatenates a list or element to a list.

Return value

A copy of the list, with value appended. If delimiter = "", returns a copy of the list, unchanged.

Syntax

ListAppend(list, value [, delimiters ])

Parameters

Parameter Description

list
A list or a variable that contains one.

value
An element or a list of elements.

delimiters
A string or a variable that contains one. Character(s) that separate list elements. Default: comma.
If this parameter contains more than one character, ColdFusion uses only the first character.

Parameter	Description
list	A list or a variable that contains one.
value	An element or a list of elements.
delimiters	A string or a variable that contains one. Character(s) that separate list elements. Default: comma. If this parameter contains more than one character, ColdFusion uses only the first character.

Usage

ColdFusion inserts a delimiter character before value.

To add an element to the beginning or end of a list, Macromedia recommends that you do so with code such as the following, rather than with the listAppend or listPrepend functions:

<cfset MyValue = "another element">
<cfif listLen(myList) is 0>

  <cfset myList = MyValue>
<cfelse>
  <cfset myList = myList & ", " & MyValue>
</cfif>

The following table shows examples of ListAppend processing:

Statement Output Comment

listAppend('elem1,elem2', '' )

elem1,elem2,
Appended element is empty; delimiter is last character in list; list length is 2

listAppend('', 'elem1,elem2' )

elem1,elem2
List length is 2

listAppend ("one___two", "three", "___")

"one___two_three"
Inserted the first character of delimiters before "three."

Statement	Output	Comment
listAppend('elem1,elem2', '' )	elem1,elem2,	Appended element is empty; delimiter is last character in list; list length is 2
listAppend('', 'elem1,elem2' )	elem1,elem2	List length is 2
listAppend ("one___two", "three", "___")	"one___two_three"	Inserted the first character of `delimiters` before "three."

Example

<h3>ListAppend Example</h3>
<!--- First, query to get some values for our list elements--->
<cfquery name = "GetParkInfo" datasource = "cfsnippets">
SELECT PARKNAME,CITY,STATE
FROM PARKS WHERE PARKNAME LIKE 'AL%'
</cfquery>
<cfset temp = ValueList(GetParkInfo.ParkName)>
<cfoutput>
<p>The original list: #temp#
</cfoutput>
<!--- now, append a park name to the list --->
<cfset temp2 = ListAppend(Temp, "ANOTHER PARK")>
...