|
ColdFusion Day 42: ================ LISTAPPEND Up to this
point, you've looked at functions that enable you to obtain information about a
list and its elements. ListAppend performs a different role:
It alters the content of a list. Specifically, ListAppend adds
an element to the end of a list using the form ListAppend(List, Element,
Delimiters). The delimiter argument is optional and needed only if your list
requires delimiters other than the default commas. The list and element
arguments are required. For
instance, consider the list "A;B;C;D;". To add "E" to the
end of the list, use
ListAppend("A;B;C;D","E",";") This will return a
new list: "A;B;C;D;E". LISTPREPEND ListPrepend
plays the opposite role of ListAppend in that it adds a new element to the
start of a list using the syntax ListPrepend(List, Element, Delimiters). As an
example, ListPrepend("B,C,D,E","A") returns a
list: "A,B,C,D,E". LISTCHANGEDELIMS ListChangeDelims is a function whose utility is
immediately apparent. The function is used to change existing delimiters in a
list to a new character or set of characters. The
question here is why? 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 ColdFusion 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 ListChangeDelims comes in. The function takes the form
ListChangeDelims(List, NewDelimiter, Delimiters). The last argument, specifying
the existing delimiters, is not necessary unless the list uses a delimiter
other than the default comma. NOTE
When using ListChangeDelims, it is important to note that your
original list may have several possible delimiters, and not all delimiters in
the list will be identical. After using ListChangeDelims, all
delimiters in the list will be identical and will match the new delimiter
specified as an argument to the function. LISTGETAT 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 from a list by specifying its numerical position in the list. The
function is used as follows: ListGetAt(List, Position, Delimiters). 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,O,P,Q,R,S,T,U,V,W,X,Y,Z". Table 13.1
shows examples of how ListGetAt works if the list is stored in the variable
Alphabet. TABLE 13.1: Using ListGetAt EXAMPLE
VALUE RETURNED BY FUNCTION ListGetAt(Alphabet,1)
A ListGetAt(Alphabet,5)
E ListGetAt(Alphabet,26) Z 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 - 0 is too small and there is
no 27th element in the list), then ColdFusion will generate an error. LISTINSERTAT Like ListGetAt,
ListInsertAt uses numerical references to indicate the place
in the list to insert a new element. This function provides more flexibility
than ListAppend and ListPrepend which can add elements only at the beginning or
end of a list. ListInsertAt allows the insertion of an element
immediately before a specified element using the form ListInsertAt(List,
Position, NewElement, Delimiters). For
instance, building on our previous example using ListGetAt,
ListInsertAt(Alphabet, 5, "1") would insert the element 1 immediately
before the element E in the list - producing a list that starts
with: A,B,C,D,1,E,F,G.... There are
two caveats to note when using ListInsertAt:
* If your list includes multiple
delimiters, then the extra delimiter that will be added with the new element
will be the first character in the list of the delimiters you provide as an
argument to ListInsertAt.
* If you are using a list generated by another application,
you may find that the elements are organized as follows:
element1, element2, element3, element4 Although it
appears that commas act as delimiters in this list, in reality both commas and
blank spaces are acting as delimiters. If you don't specify both spaces and
commas as delimiters when adding a new element with ListInsertAt,
the result will look something like this:
element1,newelement, element2, element3, element4 If you
specify the spaces as delimiters as well as commas, then your results will look
like this:
element1, newelement, element2, element3, element4 When using ListInsertAt
in this scenario, you need to decide which approach best suits your needs. LISTSETAT 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 form
ListSetAt(List, Position, NewValue, Delimiters). For
instance, if instead of inserting a new element before E in our Alphabet list,
you want to replace the E, you simply use ListSetAt(Alphabet,5,"1")
and the resulting list will start with A,B,C,D,1,F,G,... LISTDELETEAT After
learning about ListGetAt, ListInsertAt, and ListSetAt,
you should find the role of ListDeleteAt 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: ListDeleteAt(List, Position, Delimiters). So, to
delete the E from our Alphabet list, you would use ListDeleteAt(Alphabet,5). LISTFIND To make
lists really useful, you need to be able to check whether a given value matches
any element in the list. ListFind 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:
ListFind(List, Value, Delimiters). 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 ListGetAt, ListInsertAt,
ListSetAt, and ListDeleteAt. With
respect to the way in which matches occur, ListFind 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 ListFind(Alphabet,
"E") to see whether the character E is in the list. This will return
a value of 5. Because the search is case-sensitive, this means
ListFind(Alphabet, "E") will fail to find a match. As an
example, consider the following list "one, two, three, four, five".
Table 13.2 shows how different examples of the ListFind
function will work with this list. TABLE 13.2: Using ListFind FUNCTION
RESULT ListFind("one,
two, three, four, five","three")
Returns a value of 3 ListFind("one,
two, three, four, five","thr")
No match is found ListFind("one,
two, three, four,
five","Three")
No match is found |