Structure Tools Reference - adampresley/cfpowertools GitHub Wiki
The structure tools in CF PowerTools provide various handy methods for manipulating, extracting, and searching structures. These examples assume you have instantiated the StructTools object similar to the code below.
<cfset cfPowerToolsFactory = createObject("java", "com.adampresley.cfpowertools.Factory") />
<cfset structTools = cfPowerToolsFactory.getStructTools() />
extract
Extracts items from a structure (but leaves original intact) into a new structure based on a list of keys. This list of keys can be an array or a string list.
Parameters:
- source - Source structure to extract from
- keys - An array or list of keys to extract
Example
<cfset source = { key1 = 1, key2 = 2, key3 = 3, key4 = 4 } />
<cfset result = structTools.extract(source, "KEY2,KEY4") />
<!--- result == { key2 = 2, key4 = 4 } --->
<cfset source = { key1 = 1, key2 = 2, key3 = 3, key4 = 4 } />
<cfset result = structTools.extract(source, [ "KEY2", "KEY4" ]) />
<!--- result == { key2 = 2, key4 = 4 } --->
findAll
Finds all structure items that match the criteria as defined by the Groovy closure code in condition. The closure code will receive the variable item for each iterated item. The item variable is a Map.Entry class, and thus can be reference like item.key and item.value.
Parameters:
- source - Source structure to iterate over
- condition - String containing code which defines search criteria
- params - An optional structure of parameters to send to your closure code
Example
<cfset source = { key1 = 1, key2 = 2, key3 = 3 } />
<cfset result = structTools.findAll(source, "item.value > 1") />
<!--- result == { key2 = 2, key3 = 3 } --->
findFirst
Finds the first structure items that matches the criteria as defined by the Groovy closure code in condition. The closure code will revieve the variable "item" for each iterated item. The item variable is a Map.Entry class, and thus can be reference like item.key and item.value.
Parameters:
- source - Source structure 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 = { key1 = 1, key2 = 2, key3 = 3 } />
<cfset result = structTools.findAll(source, "item.value > 1") />
<!--- result == { key2 = 2 } --->
groupBy
Sorts all structure items into groups determined by the Groovy 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 a Map.Entry class, and thus can be reference like item.key and item.value.
Parameters:
- source - Source structure 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 = { a = 1, b = 2, c = 3, d = 4, e = 5, f = 6 } />
<cfset result = structTools.groupBy(source, "item.value % 2") />
<!--- result == { 0 = { b = 2, d = 4, f = 6 }, 1 = { a = 1, c = 3, e = 5 } } --->
intersect
Returns a structure of the intersection of two structures. Any items that exist in both structures are added to the result structure.
Parameters:
- struct1 - The first structure
- struct2 - The second structure
Example
<cfset s1 = { name = "Adam", age = 32 } />
<cfset s2 = { name = "Adam", height = 6.0 } />
<cfset result = structTools.intersect(s1, s2) />
<!--- result == { name = "Adam" } --->
merge
Takes an array of structures and merges the keys together. If duplicate keys exist, last one wins.
Parameters:
- sourceList - An array of structures to merge
Example
<cfset s1 = { name = "Adam" } />
<cfset s2 = { age = 32 } />
<cfset s3 = { test = "Another key", age = 33 } />
<cfset result = structTools.merge([ s1, s2, s3 ]) />
<!--- result = { name = "Adam", age = 33, test = "Another key" } /> --->
minus
Takes out all items found in compareTo from source. Kind of like a subtraction problem.
Parameters:
- source - Source structure to remove items from
- compareTo - Structure which contains the basis of items to remove from source
Example
<cfset source = { name = "Adam", age = 32, height = 6.0 } />
<cfset compareTo = { age = 32 } />
<cfset result = structTools.minus(source, compareTo) />
<!--- result == { name = "Adam", height = 6.0 } --->
reMerge
Takes an array of structures and merges the keys together if the regular express "regex" condition is met. The regex is tested against the keys. If duplicate keys exist, last one wins.
Parameters:
- sourceList - An array of structures to merge
- regex - A string or Pattern object with a regular expression to match. When a structure's key matches the regex it is added to the resulting struct
Example
<cfset s1 = { name = "Adam" } />
<cfset s2 = { age = 32, companyName = "adampresley.com" } />
<cfset s3 = { test = "Another key", age = 33 } />
<cfset result = structTools.merge([ s1, s2, s3 ], "(?i)(.*)name") />
<!--- result = { name = "Adam", companyName = "adampresley.com" } /> --->
sort
Sorts a structure 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. Each item is a Map.Entry class, and thus can be reference like item1.key and item1.value.
Parameters:
- source - Source structure to sort
- condition - String containing Groovy code telling us how to sort the structure
- params - An optional structure of parameters to send to your closure code
Example
<cfset source = { a = 3, b = 1, c = 2 } />
<cfset result = structTools.sort(source, "item1.value <=> item2.value") />
<!--- result == { b = 1, c = 2, a = 3 } --->