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")>
...

Version 6

Comments are no longer accepted for ColdFusion MX. ColdFusion 8 is the current version.

Comments

PENNY506 said on Feb 10, 2004 at 6:22 PM :

So, we're not supposed to use the ListAppend function -- per Macromedia's recommendation above?? Is this for real? Please clarify.

halL said on Feb 11, 2004 at 7:18 AM :

The recommendation to use a direct string concatenation operator in place of ListAppend and ListPrepend was probably added as an optimization recommendation.
However, at least as of ColdFusion MX 6.1, it is incorrect and the function is faster.
Therefore, you should use the functions.

No screen name said on Sep 14, 2005 at 2:20 PM :

Not so sure, I remember having ListAppend not working in 6.1

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/6/CFML_Reference/functions-pt24.htm