Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Iteration functions for mapping/reducing/filtering/etc Coldfusion collections (Arrays and Structures)

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 examples
Octocat-spinner-32 src
Octocat-spinner-32 tests
Octocat-spinner-32 .gitignore
Octocat-spinner-32 Collections.cfc
Octocat-spinner-32 README.md
README.md

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.

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

Usage

// Define the callback
public boolean function greaterThan25( value, index, data ){
    return value > 25;
}

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

// Our collection to filter
data = [8,55,16,100,358,2,-6,25];

// Filter the collection
c.filter( data, greaterThan25 );

// Returns
// [55,100,358]

public any function reject( data, callback )

Returns a filtered collection of items that DO NOT pass the "test" from the provided callback.

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

Usage

// Define the callback
public boolean function greaterThan25( value, index, data ){
    return value > 25;
}

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

// Our collection to filter
data = [8,55,16,100,358,2,-6,25];

// Filter the collection
c.reject( data, greaterThan25 );

// Returns
// [8,16,2,-6,25]   

public boolean function some( data, callback )

Returns true if at least one item in the collection passes the "test" from the provided callback.

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

Usage

// Define the callback
public boolean function hasZero( value, index, data ){
    return value == 0;
}

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

// Our collection to reduce
data = [1,1,1,1,1,0,1];

// Test for some zeros
c.some( data, hasZero );

// Returns
// true

public boolean function every( data, callback )

Returns true if all of the items in the collection pass the "test" from the provided callback.

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

Usage

// Define the callback
public boolean function hasZero( value, index, data ){
    return value == 0;
}

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

// Our collection to reduce
data = [1,1,1,1,1,0,1];

// Test for all zeros
c.every( data, hasZero );

// Returns
// false

public boolean function detect( data, callback )

Returns the first item in the collection that passes the "test" from the provided callback.

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

Usage

// Define the callback
public boolean function dirtyRecord( person ){
    return person.dirty;
}

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

// Our collection to reduce
persons = [{name='Justin', dirty=false}, {name='Mary', dirty=true}, {name='John', dirty=false}];

// Find the first dirty record
c.detect( persons, dirtyRecord );

// Returns
// { index=2, value={name='Mary', dirty=true} }

public boolean function min( data, callback )

Returns the minimum value of the provided collection. The return value from the callback is used to determine the rank of the items. The return value should be a data type that can be compared using the less than (<) operator.

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

Usage

// Use employee age to find the youngest
public numeric function byAge( person, index ){
    return person.age;
}

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

// Our collection to reduce
persons = [
        {name='Jill',age=32},
        {name='Jane',age=18},
        {name='Janice',age=25}
    ];

// Find the youngest person in the collection
c.min( persons, byAge );

// Returns
// { name='Jane', age=18 }

public boolean function max( data, callback )

Returns the maximum value of the provided collection. The return value from the callback is used to determine the rank of the items. The return value should be a data type that can be compared using the greater than (>) operator.

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

Usage

// Use employee age to find the oldest
public numeric function byAge( person, index ){
    return person.age;
}

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

// Our collection to reduce
persons = [
        {name='Jill',age=32},
        {name='Jane',age=18},
        {name='Janice',age=25}
    ];

// Find the youngest person in the collection
c.max( persons, byAge );

// Returns
// { name='Jill', age=32 }      

public array function sort( data, callback )

Sorts an array collection using the provided comparator method to determine order

Callback Signature
public numeric function callback( valueA, valueB ){}

The callback is used to compare two adjacent values in the collection and should return the following under the given scenarios:

  • if A is greater than (>) B, return 1
  • if A is less than (<) B, return -1
  • if A is equal to (==) B, return 0

Usage

// Define the comparator
private numeric function ascendingOrder( valA, valB ){
    return valA - valB;
}

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

// Our collection to reduce
data = [8,6,7,4,2,3,5,1,6,9];

// Sort in ascending order
c.sort( data, ascendingOrder );

// Returns
// [1,2,3,4,5,6,6,7,8,9]

public array function flatten( data )

Flattens a nested array collection to a single level. Accepts arrays n levels deep.

Usage

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

// a deeply nested array
data = [0,[1,2,[3,[4,5]],6]];

// Sort in ascending order
c.flatten( data );

// Returns
// [0,1,2,3,4,5,6]

public any function intersect( dataA, dataB [, dataN] [, comparitor] )

Intersect takes in two or more collections of the same type and will return a new collection containing only those items that appear in all of the supplied collections. An optional comparitor method can be supplied to test for equality between collection items. By default, Collections.cfc will use the standard equality operator (==) for comparison. Note: All collections must be of the same type.

Comparitor Signature
public boolean function comparitor( valueA, valueB ){}

Usage

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

// Some collections to work with
animals1 = {
    dog = "Roof",
    cat = "meow",
    fish = "blurb",
    lion = "roar"
};

animals2 = {
    donkey = "hehaw",
    cat = "meow",
    fish = "blurb",
    horse = "brrrrr"
};

animals3 = {
    donkey = "hehaw",
    fish = "blurb",
    bird = "ka-kaw"
};

// Find the common animals
c.intersect( animals1, animals2, animals3 );    

// Returns
// { fish = "blurb" };

Change Log

  • 2011-06-21 Added intersect();

  • 2011-05-26 Added flatten()

  • 2011-05-19 Added min(), max(), detect(), reject()

  • 2011-05-12 Added sort()

Something went wrong with that request. Please try again.