Array Tools Reference - adampresley/cfpowertools GitHub Wiki
The array tools in CF PowerTools provide various handy methods for manipulating arrays. It is useful when you need to search for complex items, find permutations, and more. These examples assume you have instantiated the ArrayTools object similar to the code below.
<cfset cfPowerToolsFactory = createObject("java", "com.adampresley.cfpowertools.Factory") />
<cfset arrayTools = cfPowerToolsFactory.getArrayTools() />
addRepeatedly
Takes an item and adds it to an array as many times as specified by numToAdd. The source array is modified directly.
Parameters:
- source - Source array to add item to
- itemToAdd - The item to add to the source array
- numToAdd - The number of times to add itemToAdd
Example
<cfset a = [] />
<cfset s = { firstName = "Adam", lastName = "Presley" } />
<cfset arrayTools.addRepeatedly(a, s, 2) />
<!--- a == [ { firstName = "Adam", lastName = "Presley" }, { firstName = "Adam", lastName = "Presley" } ] --->
combinations
Takes 2 or more arrays, and will return an array or arrays, each sub-array a set of unique combinations of all the input arrays. The return result is this new array of combinations.
Parameters:
- arrayOfArrays - An array containing arrays of items to combine
Example
<cfset arrays = [ ["a", "b"], [1, 2] ] />
<cfset combinations = arrayTools.combinations(arrays) />
<!--- combinations == [ ["a", 1], ["b", 1], ["a", 2], ["b", 2] ] --->
findAll
Finds all values in an array that match the criteria as defined by the Groovy closure code in condition. The closure code has passed to it the variable "item" for each iterated item from the array. If the item matches whatever criteria you wish you must return true or false, telling findAll to include the item in the result. The returned result is an array of the matched items.
Parameters:
- source - Source array to iterate over
- condition - String containing Groovy code which defines search criteria
- params - An optional structure of parameters to send to your closure code
Example
<cfset source = [ 1, 2, 3, 4 ] />
<cfset result = arrayTools.findAll(source, "item % 2 == 0") />
<!--- result == [ 2, 4 ] --->
findFirst
Finds the first value in an array that match the criteria as defined by the Groovy closure code in condition. The closure code has passed to it the variable "item" for each iterated item from the array. If the item matches whatever criteria you wish you must return true or false, telling findFirst to include the item in the result. The returned result is an array of the matched item.
Parameters:
- source - Source array to iterate over
- condition - String containing Groovy code which defines search criteria
- params - An optional structure of parameters to send to your closure code
Example
<cfset source = [ 1, 2, 3, 4 ] />
<cfset result = arrayTools.findFirst(source, "item > 1") />
<!--- result == [ 2 ] --->
groupBy
Sorts all array items into groups determined by the code defined in condition. The condition code should return the key that the item should be grouped by. item is the variable name for each iterated item and is passed into your Groovy closure code for each item in the array iterated over. The returned result is a structure who's keys are the values you returned from your code. The values for each key will be an array of the items that fall under that key's group.
Parameters:
- source - Source array to iterate over
- condition - String containing Groovy code which defines grouping criteria
- params - An optional structure of parameters to send to your closure code
Example
<cfset source = [ 1, 2, 3, 4 ] />
<cfset result = arrayTools.groupBy(source, "item % 2") />
<!--- result == { "0" = [ 2, 4 ], "1" = [ 1, 3 ] } --->
intersect
Returns an array of the intersection of two arrays. Any items that exist in both arrays are added to the result array.
Parameters:
- arary1 - The first array
- array2 - The second array
Example
<cfset a1 = [ 1, 2, 3, 4 ] />
<cfset a2 = [ 3, 4 ] />
<cfset result = arrayTools.intersect(a1, a2) />
<!--- result == [ 3, 4 ] --->
max
Returns the maximum value of the items in the source array. If the source array contains numeric values this will be the highest number. If string values are used a string comparison is done. If you provide closure code in the condition argument variables item1 and item2 will be passed to your closure, and you must return which one is highest, similar to a comparator.
Parameters:
- source - Source array to get max of
- condition - String containing Groovy code which defines max criteria (optional)
- params - An optional structure of parameters to send to your closure code
Example
<cfset source = [ 1, 2, 3, 4 ] />
<cfset result = arrayTools.max(source) />
<!--- result == 4 --->
<cfset source = [ "hello", "hi", "hey" ] />
<cfset result = arrayTools.max(source, "item1.length() <=> item2.length()") />
<!--- result == "hello" --->
min
Returns the minimum value of the items in the source array. If the source array contains numeric values this will be the lowest number. If string values are used a string comparison is done. If you provide closure code in the condition argument variables item1 and item2 will be passed to your closure, and you must return which one is highest, similar to a comparator.
Parameters:
- source - Source array to get min of
- condition - String containing Groovy code which defines min criteria (optional)
- params - An optional structure of parameters to send to your closure code
Example
<cfset source = [ 1, 2, 3, 4 ] />
<cfset result = arrayTools.min(source) />
<!--- result == 1 --->
<cfset source = [ "hello", "hi", "hey" ] />
<cfset result = arrayTools.min(source, "item1.length() <=> item2.length()") />
<!--- result == "hi" --->
minus
Takes out all items found in "compareTo" from "source". Kind of like a subtraction problem. minus returns the new array.
Parameters:
- source - Source array to remove items from
- compareTo - Array which contains the basis of items to remove from source
Example
<cfset source = [ 1, 2, 3, 4 ] />
<cfset compareTo = [ 2, 4 ] />
<cfset result = arrayTools.minus(source, compareTo) />
<!--- result == [ 1, 3 ] --->
permutations
Iterates over all permutation (unique) of an array and returns an array of arrays, each sub-array being a permutation set.
Parameters:
- source - Source array to permutate
Example
<cfset source = [ 1, 2 ] />
<cfset result = arrayTools.permutations(source) />
<!--- result == [ [1, 2], [2, 1] ] --->
remove
Removes items from an array that are matched according to the Groovy code closure in condition. The closure code will have a variable named item passed to it for each item in the array, and you will return true if the item should be removed from the array. Return false to keep the item.
Parameters:
- source - Source array to remove stuff from
- condition - String containing Groovy code which determines if an item should be removed
- params - An optional structure of parameters to send to your closure code
Example
<cfset source = [ 1, 2, 3, 4 ] />
<cfset result = arrayTools.remove(source, "item % 2") />
<!--- result == [ 2, 4 ] --->
removeDuplicates
Removes duplicate items from an array. If you pass Groovy closure code into condition there are two possible modes: single item, and comparator, which is dictated by the third argument (defaults to single). In single mode your closure gets a variable named item passed to it and you return true if the item is to be removed (false to keep it). When in comparator mode each item is passed in as item1 and item2, and is treated as a comparator, meaning you must return zero (0) if the items are the same and should be removed. A non-zero value indicate the values are greater than or less than each other and should stay. This is useful when remove duplicate items from an array that are complex in nature, like an array of structures.
Parameters:
- source - Source array to make unique
- condition - String containing Groovy code which determines if an item should be removed
- comparatorMode - True/false to run as a comparator. Defaults to false
- params - An optional structure of parameters to send to your closure code
Example
<cfset source = [ 1, 2, 2, 3 ] />
<cfset result = arrayTools.removeDuplicates(source) />
<!--- result == [ 1, 2, 3 ] --->
<cfset source = [ 1, 2, 2, 4 ] />
<cfset result = arrayTools.removeDuplicates(source, "item % 2") />
<!--- result == [ 2, 4 ] --->
<cfset source = [ 1, 2, 2, 3, 3, 4 ] />
<cfset result = arrayTools.removeDuplicates(source, "item1 <=> item2", true) />
<!--- result == [ 1, 2, 3, 4 ] --->
removeRange
Removes items from an array starting at startIndex, deleting up to endIndex (inclusive). If endIndex is zero or less, the function will only delete the item at startIndex. If endIndex is less than or equal to startIndex then the function will only delete the item at startIndex. If there are no items in the array the function simply returns.
Parameters:
- source - Source array to remove items from
- startIndex - The starting index to start removing at
- endIndex - The index of where to stop removing
Example
<cfset a = [ 1, 2, 3, 4, 5, 6 ] />
<cfset arrayTools.removeRange(a, 2, 4) />
<!--- a == [ 1, 5, 6 ] --->
sort
Sorts an array based on Groovy closure code defined in condition. Your closure code will have the variables item1 and item2 passed to it, and you must return -1, 0, or 1 to determine how items are sorted. Anything can be in the source array, making this sort function very powerful.
Parameters:
- source - Source array to sort
- condition - String containing Groovy code telling us how to sort the array
- params - An optional structure of parameters to send to your closure code
Example
<cfset source = [ 2, 1, 3, 5, 4 ] />
<cfset result = arrayTools.sort(source, "item1 <=> item2") />
<!--- result == [ 1, 2, 3, 4, 5 ] --->
split
Splits a source array into two different arrays based on the criteria provided in your condition closure. The closure will be passed the variable item. To put items into the first group return 1, otherwise return 0 to place items in the second group.
Parameters:
- source - Source array to split up
- condition - String containing Groovy code which determines how to split the source array
- params - An optional structure of parameters to send to your closure code
Example
<cfset source = [ 1, 2, 3, 4 ] />
<cfset result = arrayTools.split(source, "item % 2") />
<!--- result == [ [2,4], [1,3] ] --->