ListQualify |
Description
Inserts a string at the beginning and end of list elements.
Returns
A copy of the list, with qualifier before and after the specified element(s).
Category
List functions
Function syntax

    ListQualify(list, qualifier [, delimiters ] [, elements ])

History
ColdFusion 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
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 attribute.
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 the first
| character as the delimiter and ignores the remaining characters.
elements | all: all elements
| char: elements that are composed of alphabetic characters

Usage
The 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 = "cfsnippets">
    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 quotes 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 &quot; to denote quotation marks
    because the quotation mark character is a control character. --->
    <cfset qualifiedList2 = ListQualify(myList,"&quot;",",","CHAR")>

    <!--- output the array as a list --->
    <cfoutput>
       <p>The contents of the second qualified list are:   </p>
       <p>#qualifiedList2#</p>
    </cfoutput>

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

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 the first character as the delimiter and ignores the remaining characters.

elements |

- all: all elements
- char: elements that are composed of alphabetic characters