cfloop: looping over a list, a file, or an array

Description

Looping over a list steps through elements contained in any of these entities:

  • A variable

  • A value that is returned from an expression

  • An array

  • A file

    Looping over a file does not open the entire file in memory.

Syntax

<cfloop  
    index = "index name" 
    array = "array" 
    characters = "number of characters" 
    delimiters = "item delimiter" 
    file = "absolute path and filename"> 
    list = "list items" 
    ... 
</cfloop>

See also

cfabort, cfbreak, cfcontinue, cfexecute, cfexit, cfif, cflocation, cfswitch, cfthrow, cftry; cfloop and cfbreak in the Developing ColdFusion Applications

History

ColdFusion 8: Added the characters, file, and array attributes.

Attributes

Attribute

Req/Opt

Default

Description

index

Required

In a list, file, or array loop, the variable to receive the next element.

list

Required unless you specify a filename in the file attribute

A list, variable, or filename; contains a list.

array

Optional

An array.

characters

Optional

The number of characters to read during each iteration of the loop from the file specified in the file attribute. If the value of the characters attribute is more than the number of characters in the file, ColdFusion uses the number of characters in the file.

delimiters

Optional

Characters that separate items in list.

file

Optional

The absolute pathname of the on-disk or in-memory text file to read, one line at a time. This is helpful when reading large text files, because you can reuse the value of the index variable, which contains the current line of the file. When the loop completes, ColdFusion closes the file.

Example

This loop displays four names:

<cfloop index = "ListElement" list = "John,Paul,George,Ringo">  
    <cfoutput>#ListElement#</cfoutput><br>  
</cfloop>

You can put more than one character in the delimiters attribute, in any order. For example, this loop processes commas, colons, and slashes as list delimiters:

<cfloop index = "ListElement" list = "John/Paul,George::Ringo" delimiters = ",:/">  
    <cfoutput>#ListElement#</cfoutput><br>  
</cfloop>

ColdFusion skips the second and subsequent consecutive delimiters between list elements. Thus, in the example, the two colons between "George" and "Ringo" are processed as one delimiter.

To loop over each line of a file, use the tag as follows:

<cfloop file="c:\temp\simplefile.txt" index="line"> 
    <cfoutput>#line#</cfoutput><br> 
</cfloop>

To read a specified number of characters from a text file during each iteration of the loop, use the tag as follows:

<cfloop file="c:\temp\simplefile.txt" index="chars" characters="12">  
    <cfoutput>#chars#</cfoutput><br> 
</cfloop>

When you read the following text file, ColdFusion reads 12 characters during each iteration of the loop; the result appears as follows:

Text file

Result

This is line 1.

This is line 2.

This is line 3.

This is line 4.

This is line 5.

This is line 6.

This is line 7.

This is line 8.

This is line 9.

This is line 10.

This is line 11.

This is line

1. This is

line 2. Th

is is line 3

. This is l

ine 4. This

is line 5.

This is lin

e 6. This i

s line 7. T

his is line

8. This is

line 9. Thi

s is line 10

. This is l

ine 11.

To loop over an array, you can do the following:

<cfset x = ["mars","earth", "venus", "jupiter"]> 
<cfloop array="#x#" index="name"> 
    <cfoutput>#name#</cfoutput><br> 
</cfloop>