Description
Inserts an element in a list.
Returns
A copy of the list_,_ with value inserted at the specified position.
Category
Function syntax
ListInsertAt(list, position, value [, delimiters, includeEmptyFields ])
See also
ListDeleteAt, ListAppend, ListPrepend, ListSetAt; Lists in Data types- Developing guide in the Developing ColdFusion Applications
Parameters
Parameter |
Description |
|---|---|
includeEmptyFields |
Optional. Set to yes to include empty values. |
list |
A list or a variable that contains one. |
position |
A positive integer or a variable that contains one. Position at which to insert element. The first list position is 1. |
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 processes each occurrence of each character as a delimiter. |
Usage
When inserting an element, ColdFusion inserts a delimiter. If delimiters contains more than one delimiter, 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.
Throws
If this function attempts to insert an element at position 0, or specifies a value for position that is greater than the size of array, this function throws an InvalidArrayIndexException error.
Example
<!--- This example shows ListInsertAt ---> <cfquery name = "GetParkInfo" datasource = "cfdocexamples"> SELECT PARKNAME,CITY,STATE FROM PARKS WHERE PARKNAME LIKE 'DE%' </cfquery> <cfset temp = ValueList(GetParkInfo.ParkName)> <cfset insert_at_this_element = ListGetAt(temp, "3", ",")> <cfoutput> <p>The original list: #temp# </cfoutput> <cfset temp2 = ListInsertAt(Temp, "3", "my Inserted Value")>
<cfscript>
myList="Tokyo,Bangkok,Jakarta,Manila,Bangalore,Shanghai";
myInsert=ListInsertAt(myList,4,"Mumbai");
WriteOutput(myInsert); // Inserts Mumbai after Jakarta
</cfscript>
Output
Tokyo,Bangkok,Jakarta,Mumbai,Manila,Bangalore,Shanghai