CFML Reference

ListPrepend

Description

Inserts an element at the beginning of a list.

Return value

A copy of the list, with value inserted at the first position.

Category

List functions

Syntax

ListPrepend(list, value [, delimiters ])

See also

ListAppend, ListInsertAt, ListSetAt

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 processes each occurrence of each character as a delimiter.

Usage

When prepending an element to a list, ColdFusion inserts a delimiter. If delimiters contains more than one delimiter character, ColdFusion uses the first delimiter in the string; if delimiters is omitted, ColdFusion uses a comma.

ColdFusion ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.

If the delimiters parameter is empty (""), ColdFusion replaces the list with the contents of 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>

Example

<!--- This example shows ListPrepend --->
<cfquery name = "GetParkInfo" datasource = "cfsnippets">
  SELECT PARKNAME,CITY,STATE
  FROM PARKS
  WHERE PARKNAME LIKE 'DE%'
</cfquery>
<cfset temp = ValueList(GetParkInfo.ParkName)>
<cfset first_element = ListFirst(temp)>
<cfoutput><p>The original list: #temp#</cfoutput>
<!--- now, insert an element at position 1--->
<cfset temp2 = ListPrepend(Temp, "my Inserted Value")>

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

Version 6

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

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-pt216.htm

Add Comment