|
ListQualify
DescriptionInserts
a string at the beginning and end of list elements.
ReturnsA copy
of the list, with qualifier before and after the specified
elements.
Function syntaxListQualify(list, qualifier [, delimiters, elements, includeEmptyValues ])
HistoryColdFusion
MX: Changed behavior: as the elements parameter
value, you must specify "all" or "char";
otherwise, ColdFusion throws an exception. (In earlier releases,
the function ignored an invalid value, and used "all";
this was inconsistent with other functions.)
Parameters
Parameter
|
Description
|
includeEmptyValues
|
Optional. Set to yes to
include empty values.
|
list
|
A list or a variable that contains one.
|
qualifier
|
A string or a variable that contains one.
Character or string to insert before and after the list elements
specified in the elements parameter.
|
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 uses
the first character as the delimiter and ignores the remaining characters.
|
elements
|
|
UsageThe new
list might not preserve all of the delimiters in the list.
ColdFusion
ignores empty list elements; thus, the list "a,b,c,,,d" has four
elements.
Example<cfquery name = "GetEmployeeNames" datasource = "cfdocexamples">
SELECT FirstName, LastName
FROM Employees
</cfquery>
<h3>ListQualify Example</h3>
<p>This example uses ListQualify to put the full names of the
employees in the query within quotation marks.</p>
<cfset myArray = ArrayNew(1)>
<!--- loop through query; append these names successively
to the last element --->
<cfloop query = "GetEmployeeNames">
<cfset temp = ArrayAppend(myArray, "#FirstName# #LastName#")>
</cfloop>
<!--- sort that array descending alphabetically --->
<cfset myAlphaArray = ArraySort(myArray, "textnocase")>
<!--- show the resulting array as a list --->
<cfset myList = ArrayToList(myArray, ",")>
<cfoutput>
<p>The contents of the unqualified list are as follows: </p>
#myList#
</cfoutput>
<!--- show the resulting alphabetized array as a qualified list with
single quotation marks around each full name.--->
<cfset qualifiedList1 = ListQualify(myList,"'",",","CHAR")>
<!--- output the array as a list --->
<cfoutput>
<p>The contents of the qualified list are as follows: </p>
<p>#qualifiedList1#</p>
</cfoutput>
<!--- show the resulting alphabetized array as a qualified list with quotation
marks around each full name. We use " to denote quotation marks
because the quotation mark character is a control character. --->
<cfset qualifiedList2 = ListQualify(myList,""",",","CHAR")>
<!--- output the array as a list --->
<cfoutput>
<p>The contents of the second qualified list are: </p>
<p>#qualifiedList2#</p>
</cfoutput>
|