Up to this point, you’ve looked at functions that enable you to obtain information about a list and its elements. Li stAppend performs a different role: It alters the contents of a list. Specifically List Append adds an element to the end of the list using the form ListAppendCL i st Element Delimiters). The delimiter argument is optional and needed only if your list requires delimiters other than the default comma. The list and element arguments are required.
For instance consider the list A;B;C; 0′ . To add “E’ to the end of the list, use ListAppendC”A;B;C;O”, ‘E’,’; ‘). This will retum a new list: ‘A;B;C;O;E’.
ListPrepend plays the opposite role of Li stApp”end in that it adds a new element to the start of a list using the syntax ListPrependCL i st, Element, Oelimiters). As an example, ListPr~pendC ‘B,C,O, E’, “A’) returns the list ‘A,B,C,O, E’ .
ListChange Delimsis a function whose utility is immediately apparent. The function isused to change existing delimiters in a list to a new character or set of characters.
The question here is: Why might this be useful? Consider some possible sources of lists: Users submitting forms may provide information in lists, or outside applications (such as Microsoft Excel) may generate lists in a file, which you then use in your Cold- Fusion applications.
In some cases, however, the default delimiter in these lists from outside sources won’t meet your needs. For instance, if a list has commas for delimiters and you want to add an element that includes a comma, you will have a problem. The only way around this is to change the delimiter in the original list before adding the new element.
That’s where ListChangeDe’ i mscomes in. The function takes the form ListChange- .’. 1ims(L i st, NewD~1imi ter [, Del; miters]). The last argument, specifying the existing delimiters, isvt necessary unless the list uses a delimiter other than the default comma.
Until now, most of the functions you have looked at have manipulated lists or returned elements from a list in a limited manner
ListGetAt, however, is the first of a series of functions we are presenting that enable you to retrieve or manipulate single elements in a specific fashion. With Li stGetAt, you can retrieve a single element from a list by specifying its numerical position in the list. The function is used as follows: Li stGetAt(L i st, Posi ti on [, Del imi ters]). As usual, the delimiter argument is optional if the list uses the default delimiter.
The position is specified numerically with 1 being the first element in the list, 2 the second element, 3 the third element and so on until the last element in the list. The easiest way to understand how this works is to consider a list of the letters of the alphabet:”A•B,C,D, E, F,G,H, I , J ,K, L,M , N,0, P, Q, R, S,T, U , V,W , X,Y,Z·. Table 14.1 shows examples of how Li stGetAt works if this list is stored in the variable A1 phabet .
If you choose a position that is out of the list’s range (for instance in the preceding example both 0 and 27 are out of range-O is too small and there is no 2~ element in the list), then ColdFusion will generate an error.
List Insert At
Like L; stGetAt, L; stInsertAt uses numerical references to indicate the place in the list to insert a new element. This function provides more flexibility than Li stAppend and L; stPrepend, which can add elements only at the beginning or end of a list.
listSetAt is closely akin to listInsertAt in that it changes the contents of a list. However rather than adding an element, it changes the value of an existing element. The function takes the formLi stSetAt(Li st, Pos it; on NewValue Delimiters).
For instance, if instead of inserting a new element before Ein our alphabet list, you
want to replace the E,you simply use Li stSetAt(A’ ph abet ,5, “1”) and the resulting list will start with A, B , C, 0,1, F,G,.”
After learning about Li stGetAt, L; stIns,ertAt, and L; stSetAt, you should find the role of Li stDe 1eteAt fairly obvious: to delete an element from a list that is specified by its numeric position and to return the new list. And the structure of the function should be clear: Li stDe’ eteAt(L i st, Pos it; on, Del im; ters).
So, to delete the Efrom our alphabet list, you would use: L; 5tOe’ eteA t (A’ ph abet , 5).
To make lists really useful, you need to be able to check whether a given value matches any element in the list. Li stFi nd provides one way to do this. This function returns the numeric position of the list’s first element that matches a specified value. To find a value, use the form Li stF; nd(List Value Deimiters).
How does this work? It is quite simple. The function compares the first element to the value: If it matches, the position is returned. If not, then the function proceeds to the next element and repeats the same process. This continues until there is a match or all elements
in the list fail to match. If no element matches, then 0 is returned.
Because the numeric position of an element is returned, the function provides more utility than simply determining whether an element is in a list. The resulting numeric position can subsequently be used with Li stGetAt, L; stInsertAt, L; stSetAt, and L; stDeleteAt.
With respect to the way in which matches occur, L; stFi nd performs a case-sensitive match on entire elements. This means that matches to substrings inside elements are not found. .
For instance, in the previous alphabet example, you can use L; stFi nd(A1phabet , “E’) to see whether the character Eis in the list. This will return a value of 5. Because the search is case sensitive, this means L; stFi nd(A1ph abet , “e”) will fail to find a match.
As another example, consider the following list: “one, two, th ree, four five”. Table 14.2 shows how different examples of the Li stFi nd function will work with this list.
Li s~Fi ndNoCase is a simple extension of Li stFi nd. The difference is that the search is case1insensitive. Therefore, Li stFi ndNoCase(A 1phabet, “E”) and Li stFi ndNoCase (Alphabet, “e’) will both produce matches, as will Li stFi ndNoCase(” one, two, three,four,five” ,”three”) and ListFindNoCase(“one,two,th ree,four, five” , ‘Three”).
Li stContai ns is also similar to Li stFi nd, but the difference lies not in the treatment of uppercase and lowercase characters but rather substrings. Li stContai ns matches not only complete elements but substrings as well.
Therefore.In our examples with the list “one, two, three, four, five”, both Li st-Contai ns( “one, two, three, four, fi ve” , “three”) and Li stContai ns (“One, two, three ,four, fi ve” , “thr”) generate matches for position 3.Like Li stFi nd, Li stContai ns uses case-sensitive searches
ListContai nsNoCase extends Li stContai ns to include case-insensitive searches.
Therefore, all these examples produce matches:
• ListContainsNoCase(“one,two,three,four,five” ,”three”)