Using ColdFusion Data Types

The variables you have used thus far are simple variables, are defined, and contain a value. ColdFusion supports three advanced data types that I'll briefly introduce now: lists, arrays, and structures.

NOTE

This is just an introduction to lists, arrays, and structures. All three are used repeatedly throughout the rest of this book, so don't worry if you do not fully understand them by the time you are done reading this chapter. Right now, the intent is to ensure that you know these exist and what they are. You'll have lots of opportunities to use them soon enough.

Lists

Lists are used to group together related information. Lists are actually strings (plain text)what makes them lists is that a delimiter is used to separate items within the string. For example, the following is a comma-delimited list of five U.S. states:

 California,Florida,Michigan,Massachusetts,New York

The next example is also a list. Even though it might not look like a list, a sentence is a list delimited by spaces:

 This is a ColdFusion list

Lists are created just like any other variables. For example, this next line of code uses the <cfset> tag to create a variable named fruit that contains a list of six fruits:

 <cfset fruit="apple,banana,cherry,grape,mango,orange">

The code in Listing 8.7 demonstrates the use of lists. Type the code and save it as list.cfm in the 8 directory; then execute it. You should see an output similar to the one shown in Figure 8.11.

Listing 8.7. `list.cfm`

 <html> <head>  <title>List Example</title> </head> <body> <cfset fruit="apple,banana,cherry,grape,mango,orange"> <cfoutput> Complete list: #fruit#<BR> Number of fruit in list: #ListLen(fruit)#<BR> First fruit: #ListFirst(fruit)#<BR> Last fruit: #ListLast(fruit)#<BR> <cfset fruit=ListAppend(fruit, "pineapple")> Complete list: #fruit#<BR> Number of fruit in list: #ListLen(fruit)#<BR> First fruit: #ListFirst(fruit)#<BR> Last fruit: #ListLast(fruit)#<BR> </cfoutput> </body> </html>

Figure 8.11. Lists are useful for grouping related data into simple sets.

Let's walk through the code in Listing 8.7. A <cfset> is used to create a list. As a list is simply a string, a simple variable assignment can be used.

Next comes the <cfoutput> block, starting with displaying #fruit# (the complete list). The next line of code uses the ListLen() function to return the number of items in the list (there are six of them). Individual list members can be retrieved using ListFirst() (used here to get the first list element), ListLast() (used here to get the last list element), and ListGetAt() (used to retrieve any list element, but not used in this example).

Then another <cfset> tag is used, as follows:

 <cfset fruit=ListAppend(fruit, "pineapple")>

This code uses the ListAppend() function to add an element to the list. You will recall that functions return copies of modified variables, not modified variables themselves. So the <cfset> tag assigns the value returned by ListAppend() to fruit, effectively overwriting the list with the new revised list.

Then the number of items, as well as the first and last items, is displayed again. This time 7 items are in the list, and the last item has changed to pineapple.

As you can see, lists are very easy to use and provide a simple mechanism for grouping related data.

NOTE

I mentioned earlier that a sentence is a list delimited by spaces. The default list delimiter is indeed a comma. Actually, though, any character can be used as a list delimiter, and every list function takes an optional delimiter attribute if necessary.

Arrays

Arrays, like lists, store multiple values in a single variable. But unlike lists, arrays can contain far more complex data (including lists and even other arrays).

Unlike lists, arrays support multiple dimensions. A single-dimensional array is actually quite similar to a list: It's a linear collection. A two-dimensional array is more like a grid (imagine a spreadsheet), and data is stored in rows and columns. ColdFusion also supports three-dimensional arrays, which can be envisioned as cubes of data.

If this all sounds somewhat complex, well, it is. Arrays are not as easy to use as lists, but they are far more powerful (and far quicker). Here is a simple block of code that creates an array and displays part of it; the output is shown in Figure 8.12. To try it out, type the code in Listing 8.8 and save it as array1.cfm.

Listing 8.8. `array1.cfm`

 <html> <head>  <title>Array Example 1</title> </head> <body> <cfset names=ArrayNew(2)> <cfset names[1][1]="Ben"> <cfset names[1][2]="Forta"> <cfset names[2][1]="Ray"> <cfset names[2][2]="Camden"> <cfset names[3][1]="Leon"> <cfset names[3][2]="Chalnick"> <cfset names[4][1]="Angela"> <cfset names[4][2]="Buraglia"> <cfoutput> The first name in the array #names[1][1]# #names[1][2]# </cfoutput> </body> </html>

Figure 8.12. Arrays treat data as if they were in a one-, two-, or three-dimensional grid.

Arrays are created using the ArrayNew() function. ArrayNew() requires that the desired dimension be passed as a parameter, so the following code creates a two-dimensional array named names:

 <cfset names=ArrayNew(2)>

Array elements are set using <cfset>, just like any other variables. But unlike other variables, when array elements are set the element number must be specified using an index (a relative position starting at 1). So, in a single dimensional array, names[1] would refer to the first element and names[6] would refer to the sixth. In two-dimensional arrays, both dimensions must be specified, as seen in these next four lines (taken from the previous code listing):

 <cfset names[1][1]="Ben"> <cfset names[1][2]="Forta"> <cfset names[2][1]="Ray"> <cfset names[2][2]="Camden">

names[1][1] refers to the first element in the first dimensionthink of it as the first column of the first row in a grid. names[1][2] refers to the second column in that first row, and so on.

When accessed, even for display, the indexes must be used. Therefore, the following line of code

 The first name in the array #names[1][1]# #names[1][2]#

generates this output:

 The first name in the array Ben Forta

For a better view into an array, you can use a tag named <cfdump>. Listing 8.9 contains the code for array2.cfm (the same as array1.cfm, but with different output code). The output is shown in Figure 8.13.

Listing 8.9. `array2.cfm`

 <html> <head>  <title>Array Example 1</title> </head> <body> <cfset names=ArrayNew(2)> <cfset names[1][1]="Ben"> <cfset names[1][2]="Forta"> <cfset names[2][1]="Ray"> <cfset names[2][2]="Camden"> <cfset names[3][1]="Leon"> <cfset names[3][2]="Chalnick"> <cfset names[4][1]="Angela"> <cfset names[4][2]="Buraglia"> <cfdump var="#names#"> </body> </html>

Figure 8.13. `<cfdump>` is a great way to inspect array contents.

We'll take a look at <cfdump> again in a moment. But for now, as you can see, although they're not as easy to use as lists, arrays are a very flexible and powerful language feature.

Structures

Structures are the most powerful and flexible data type within ColdFusion, so powerful in fact that many internal variables (including ones listed in Appendix D, "Special ColdFusion Variables and Result Codes") are actually structures.

Simply put, structures provide a way to store data within data. Unlike arrays, structures have no special dimensions and are not like grids. Rather, they can be thought of as top-level folders that can store data, or other folders, which in turn can store data, or other folders, and so on. Structures can contain lists, arrays, and even other structures.

To give you a sneak peek at what structures look like, here is some code. Give it a try yourself; save the file as structure.cfm (see Listing 8.10), and you should see output as shown in Figure 8.14.

Listing 8.10. `structure.cfm`

 <html> <head>  <title>Structure Example</title> </head> <body> <cfset contact=StructNew()> <cfset contact.FirstName="Ben"> <cfset contact.LastName="Forta"> <cfset contact.EMail="ben@forta.com"> <cfoutput> E-Mail: <a href="mailto:#contact.EMail#">#contact.FirstName# #contact.LastName#</a> </cfoutput> </body> </html>

Figure 8.14. Structures are the most powerful data type in ColdFusion and are used internally extensively.

Structures are created using StructNew(), whichunlike ArrayNew()takes no parameters. After a structure is created, variables can be set inside it. The following three lines of code all set variables with the contact structure:

 <cfset contact.FirstName="Ben"> <cfset contact.LastName="Forta"> <cfset contact.EMail="ben@forta.com">

To access structure members, simply refer to them by name. #contact.FirstName# accesses the FirstName member of the contact structure. Therefore, the code

 <a href="mailto:#contact.EMail#">#contact.FirstName# #contact.LastName#</a>

generates this output:

 <a href="mailto:ben@forta.com">Ben Forta</a>

And that's just scratching the surface. Structures are incredibly powerful, and you'll use them extensively as you work through this book.

For simplicity's sake, I have described only the absolute basic form of structure use. ColdFusion features an entire set of structure manipulation functions that can be used to better take advantage of structuresyou use some of them in the next chapter, "CFML Basics."

"Dumping" Expressions

I showed you a tag named <cfdump> in Listing 8.9 above. This tag is never used in live applications, but it's an invaluable testing and debugging tool. <cfdump> lets you display any expression in a cleanly formatted table. You saw an example of dumping an array previously; now let's try another example. Type the following code into a new document (see Listing 8.11), save it as cfdump1.cfm, and then execute it in your browser. The output is shown in Figure 8.15.

Listing 8.11. `cfdump1.cfm`

 <html> <head>  <title>&lt;cfdump&gt; Example 1</title> </head> <body> <cfset contact=StructNew()> <cfset contact.FirstName="Ben"> <cfset contact.LastName="Forta"> <cfset contact.EMail="ben@forta.com"> <cfdump var="#contact#"> </body> </html>

Figure 8.15. `<cfdump>` is an invaluable diagnostics and debugging tool capable of displaying all sorts of data in a clean and easy-to-read format.

In this listing we've removed the <cfoutput> block. Instead, a <cfdump> tag is being used to dump (display) the contents of the contact structure. As you can see in Figure 8.14, <cfdump> creates a nicely formatted table containing the data contained within the structure. Our structure was pretty simple (three members, and no nested data types) but as the variables and data types you work with grow in complexity you'll find <cfdump> to be an invaluable utility tag.

Here is one final <cfdump> example, this time dumping the contents of two special variable scopes. SERVER is a structure (that contains two other structures) containing ColdFusion and operating system information. CGI is a structure that contains all sorts of data provided by the Web browser, Web server, and ColdFusion. Type the following code into a new document (see Listing 8.12), save it as cfdump2.cfm, and then execute it in your browser. The output is shown in Figure 8.16.

Listing 8.12. `cfdump2.cfm`

 <html> <head>  <title>&lt;cfdump&gt; Example 2</title> </head> <body> <h1>SERVER</h1> <cfdump var="#SERVER#"> <h1>CGI</h1> <cfdump var="#CGI#"> </body> </html>

Figure 8.16. `<cfdump>` can display all ColdFusion data types, including nested data types.

TIP

<cfdump> actually does more than just paint an HTML table. Try clicking on any of the boxes with colored backgrounds; you'll be able to collapse and expand them as needed. When working with very large complex expressions this feature is incredibly useful, and to make it work ColdFusion automatically generates DHTML code (with supporting JavaScript) all automatically. To appreciate just how much work this little tag does, View Source in your Web browser.

Lists

Listing 8.7. list.cfm

Figure 8.11. Lists are useful for grouping related data into simple sets.

Arrays

Listing 8.8. array1.cfm

Figure 8.12. Arrays treat data as if they were in a one-, two-, or three-dimensional grid.

Listing 8.9. array2.cfm

Figure 8.13. <cfdump> is a great way to inspect array contents.