String Tools Reference - adampresley/cfpowertools GitHub Wiki

The string tools in CF PowerTools provide various handy methods for manipulating or converting strings to various handy formats and objects. These examples assume you have instantiated the StringTools object similar to the code below.

<cfset cfPowerToolsFactory = createObject("java", "com.adampresley.cfpowertools.Factory") />
<cfset stringTools = cfPowerToolsFactory.getStringTools() />

denormalize

Returns a string with lines terminated by platform-specific line separator (LF, CR, CR/LF). So, as an example, if you are running on Windows calling this method will convert all line enders of the input string to CF/LF. On Linux the line ender would be LF. denormalize returns the converted string.

Parameters:

• source - Source string to denormalize

Example

<cfset source = fileRead("C:/someUnixFile.txt") />
<cfset result = stringTools.denormalize(source) />
<!--- result == some denormalized string --->

eachLine

eachLine iterates over a string broken up by line ender. You provide Groovy code to indicate what to do with each line that is iterated over. This can be used, for example, to conditionally select lines from a string or file. eachLine returns an array.

Parameters:

• source - Source string to iterate over (each line)
• closureCode - The Groovy code to execute for each line in the string
• params - An optional structure of parameters to send to the closure code

Example

<cfsavecontent variable="source">
	This is line 1
	This is line 2
</cfsavecontent>

<cfsavecontent variable="closureCode">
	if (line.contains("1")) OUTPUT << line
</cfsavecontent>

<cfset params = { output = [] } />
<cfset result = stringTools.eachLine(source, closureCode, params) />
<!--- params.output == an array containing one line from the source --->

normalize

Returns a string with lines terminated by a linefeed. Existing carriage returns or CF/LF combinations are converted to linefeeds (LF).

Parameters:

• source - Source string to normalize

Example

<cfset source = fileRead("C:/someWindowsFile.txt") />
<cfset result = stringTools.normalize(source) />
<!--- result == some normalized string --->

splitEachLine

Iterates over a string, breaking it up by line ender, then further breaking each string line into tokens by a given regular expression. The returned result will be whatever you return from the Groovy closure code. In the example below we take a set of string lines, each lines with columns delimited by a pipe (|), parse it, and return an array of structures.

Parameters:

• source - Source string to iterate over (each line)
• regex - Regex used to break each line into tokens, or columns
• closureCode - The Groovy code to execute for each line in the string
• params - An optional structure of parameters to send to the closure code

Example

<cfsavecontent variable="source">
Adam|Presley|Programmer
Taylor|Presley|Student
</cfsavecontent>

<cfsavecontent variable="closureCode">
	OUTPUT << [ firstName: tokens[0], lastName: tokens[1], category: tokens[2] ]
</cfsavecontent>

<cfset params = { output = [] } />
<cfset result = stringTools.splitEachLine(source, closureCode, params) />
<!--- result == an array of structures, each structure having keys "firstName", "lastName", and "category" --->

stripIndent

This method will strip all leading spaces for each line in a string. stripIndent returns the newly stripped string.

Parameters:

• source - Source string to strip leading spaces from

Example

<cfsavecontent variable="source">
     Hi all, it is nice to see you
using CFPowerTools. A nifty library
   for those who need to manipulate more than
 just query data.
</cfsavecontent>

<cfset result = stringTools.stripIndent(source) />
<!--- result == no leading spaces on any lines --->

toArray

This method converts a string to an array of characters. Java has a built-in method on the String class calledtoCharArray() that turns a string into a primitive array. However we ColdFusion peeps like to work with CF arrays, or Vectors, so this gives us an array.

Parameters:

• source - The source string to convert

Example

<cfset source = "Test" />
<cfset result = stringTools.toArray(source) />
<!--- result == [ "T", "e", "s", "t" ] --->

toRegex

A method to convert a string to a Java Pattern object without having to go through the fuss of createObject. The return is a java.util.regex.Pattern object.

Parameters:

• source - A string to turn into a Java Pattern object

Example

<cfset pattern = stringTools.toRegex("(?i)[^0-9a-z_]") />

toURI

This method parses a string into a URI object. See http://docs.oracle.com/javase/6/docs/api/java/net/URI.html for more information.

Parameters:

• source - A string to parse into a URI

Example

<cfset uriString = "mailto:[email protected]" />
<cfset uriObject = stringTools.toURI(uriString) />

toURL

This method parses a string into a URL object. See http://docs.oracle.com/javase/6/docs/api/java/net/URL.html for more information.

Parameters:

• source - A string to parse into a URL

Example

<cfset urlString = "http://www.adampresley.com" />
<cfset urlObject = stringTools.toURL(urlString) />