Collections.cfc

Collections.cfc is a library of iteration methods for Coldfusion arrays and structures.

Here is an blog post that walks you through various ways in which to use the library, or you can jump right over to the code from the example.

Tested on Railo 3.2.2 and Adobe Coldfusion 9.0.1

##public any function map( data, callback ) Create a new collection by executing the provided callback on each element in the provided collection

Callback Signature
public any function callback( value, index, collection ){}

Usage

// Define the callback
public numeric function multiplyAgeBy20( value, index, data){
	return value.age * 20;
}

// Create the Collections object
c = new Collections();

// Our collection to map
data = { 'John'={age=20},'Kelley'={age=30}, 'Nicole'={age=40} };

// Map the collection
c.map( data, multiplyAgeBy20 );

// Returns
// {'John'=400,'Kelley'=600, 'Nicole'=800};

##public any function reduce( data, callback [, initialvalue ] ) Executes the provided callback for each element in the collection (from left to right) passing in the value from the previous execution (the accumulatedValue), the value of the current index, the index itself and the original provided collection. Use this method to reduce a collection to a single value. Structure collections will be iterated by key name in ascending order (i.e. mystruct['apple'], mystruct['banana'], mystruct['cucumber'], ...).

Callback Signature
public any function callback( accumulatedvalue, value, index, collection ){}

Usage

// Define the callback
public string function concatValues( previous, current, index, data ){
	return previous & current;
}

// Create the Collections object
c = new Collections();

// Our collection to reduce
data = {'apple'='a','banana'='b','cucumber'='c'};

// Reduce the collection
c.reduce( data, concatValues );

// Returns
// "abc"

// Alternative call w/ initial value
c.reduce( data, concatValues, "Z" );

// Returns
// "Zabc"

##public any function reduceRight( data, callback [, initialvalue ] ) Executes the provided callback for each element in the collection (from right to left) passing in the value from the previous execution (the accumulatedValue), the value of the current index, the index itself and the originaly provided collection. Use this method to reduce a collection to a single value. Structure collections will be iterated over by key name in descending order(i.e. ..., mystruct['cucumber'], mystruct['banana'], mystruct['apple']).

Callback Signature
public any function callback( accumulatedvalue, value, index, collection ){}

Usage

// Define the callback
public string function concatValues( previous, current, index, data ){
	return previous & current;
}

// Create the Collections object
c = new Collections();

// Our collection to reduce
data = {'apple'='a','banana'='b','cucumber'='c'};

// Reduce the collection from the right
c.reduceRight( data, concatValues );

// Returns
// "cba"

// Alternative call w/ initial value
c.reduce( data, concatValues, "Z" );

// Returns
// "Zcba"

##public void function forEach( data, callback ) Applies the provided callback on each item in the collection.

It's important to note that while no data is returned from this function, your provided collection could be mutated inside of the callback. Structures are pass-by-reference in both Railo and Adobe Coldfusion and thus are subject to modification. Arrays however are pass-by-value in Adobe CF, but are pass-by-reference in Railo.

Callback Signature
public void function callback( value, index, collection ){}

Usage

// Define the callback
public void function justAandB( value, index, data ){
	data[index] = value < 4 ? "a" : "b";
}

// Create the Collections object
c = new Collections();

// Our collection to reduce
data = {a=1,b=2,c=3,d=4,e=5,f=6};

// Iterate over the collection
c.foreach( data, justAandB );

// Mutated collection is now
// {a="a",b="a",c="a",d="b",e="b",f="b"}

##public any function filter( data, callback ) Returns a filtered collection of items that pass the "test" from the provided callback.