Parameter
Last updated on
May 16, 2021
|
Also applies to ColdFusion
Description
Inserts an element at the beginning of a list.
Returns
A copy of the list, with value inserted at the first position.
Category
Function syntax
ListPrepend(list, value [, delimiters, includeEmptyFields ])
History
ColdFusion (2018 release) Update 5:
- Introduced named parameters.
- New parameter added- includeEmptyFields.
See also
ListAppend, ListInsertAt, ListSetAt; Lists in Data types- Developing guide in the Developing ColdFusion Applications
Parameters
|
|
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. Characters that separate list elements. The default value is comma. If this parameter contains more than one character, ColdFusion only uses the first character and ignores the others. |
|
includeEmptyFields |
Boolean to determine to include empty fields from the list that is prepended to the list. |
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 the empty string (""), ColdFusion returns the contents of the value parameter.
Example 1
<cfscript>
myList="Tokyo,Bangkok,Jakarta,Manila,Bangalore,Shanghai";
myAppend=ListPrepend(myList,"Singapore");
WriteOutput(myAppend); // Inserts Singapore at the beginning of the list
</cfscript>
Output
Singapore,Tokyo,Bangkok,Jakarta,Manila,Bangalore,Shanghai
Example 2
When includeEmptyFields="true"
<cfscript> mylist="John,Paul,George" writeOutput(ListPrepend(list=mylist,value=",,,Ringo,,",delimiter=",",includeEmptyFields="true")) </cfscript>
Output
,,,Ringo,,,John,Paul,George
<cfscript> mylist="Paul,George" writeOutput(ListPrepend(list=mylist,value=",,John,,,Ringo,,",delimiter=",",includeEmptyFields="true")) </cfscript>
Output
,,John,,,Ringo,,,Paul,George
When includeEmptyFields="false"
<cfscript> mylist="John,Paul,George" writeOutput(ListPrepend(list=mylist,value=",,,Ringo,,",delimiter=",",includeEmptyFields="false")) </cfscript>
Output
Ringo,John,Paul,George
<cfscript> mylist="Paul,George" writeOutput(ListPrepend(list=mylist,value=",,John,,,Ringo,,",delimiter=",",includeEmptyFields="false")) </cfscript>
Output
Ringo,John,Paul,George
Member function
<cfscript>
mylist="Paul,George"
writeOutput(mylist.ListPrepend(",,John,,,Ringo,,",",","false"))
</cfscript>
Output
John,Ringo,Paul,George