View comments | RSS feed
Contents > CFML Reference > ColdFusion Functions > ListAppend PreviousNext

ListAppend

Concatenates a list or element to a list.

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

List functions

ListAppend(list, value [, delimiters ])

ListPrepend, ListInsertAt, ListGetAt, ListLast, ListSetAt

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.

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

 

<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")>
...
Contents > CFML Reference > ColdFusion Functions > ListAppend PreviousNext

ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | Bug Reporting

Version 6.1

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

Comments


nathandintenfas s said on Mar 4, 2004 at 2:41 PM :
Is that really Macromedia's "best practice" -- if you did that in a loop (which is where this kind of thing happens most), wouldn't the performance penalty of the conditional logic and listLen() outweigh the benefit of not using listAppend()? Why is listAppend() no longer suggested for use?
jrunrandy said on Mar 5, 2004 at 6:12 AM :
In testing this out, the Macromedia recommendation proves wrong. I think this comment dates back to Beta versions of ColdFusion MX and we didn't remove it after the developers fixed the code.
jonese said on May 17, 2004 at 12:30 PM :
So is MM going to update there online docs etc?

also are there any known bugs with ListAppend? I've got a fellow CF Programmer that's having some odd dealings with it. He switched to this "recommended way" and all is well... but i'd like to see listappend work as advertised :)
No screen name said on Oct 5, 2004 at 11:15 AM :
ListAppend("one___two", "three", "___")

Worst example ever....
Why not use delimiters that can actually be distinguished from each other?
Also, when are the additional delimiters used?

Btw, why are the examples so poor in these docs? Macromedia really needs to check out PHP's online documentation for an example of how to create GOOD online docs.
Mike@Jobscience said on Jan 28, 2005 at 4:26 PM :
Why does the following produce results that are not in line with the way CF treats lists?

<cfset example = "item1">
<cfset example = listAppend( example, "" )>
<cfset example = listAppend( example, "" )>
#example#<br>


gives you: "item,,"

instead of just: "item"

which would be expected since CF ignores extra delims in a list count or loop. In this case the Macromedia "best practice" is actually the correct way to append items to a list. This brings up a serious point, why are all the list functions not implemented the same way???

 

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

Current page: http://livedocs.adobe.com/coldfusion/6.1/htmldocs/functib4.htm