Functions



Functions typically manipulate data and return a result. You can also create user-defined functions (UDFs), sometimes referred to as custom functions.

Functions have the following general form:

functionName([argument1[, argument2]]...)

Some functions, such as the Now function take no arguments. Other functions require one or more comma-separated arguments and can have additional optional arguments. All ColdFusion functions return a value. For example, Round(3.14159) returns the value 3.

Built-in functions

ColdFusion built-in functions perform a variety of tasks, including, but not limited to, the following:

  • Creating and manipulating complex data variables, such as arrays, lists, and structures

  • Creating and manipulating queries

  • Creating, analyzing, manipulating, and formatting strings and date and time values

  • Evaluating the values of dynamic data

  • Determining the type of a variable value

  • Converting data between formats

  • Performing mathematical operations

  • Getting system information and resources

For alphabetical and categorized lists of ColdFusion functions, see ColdFusion Functions in the CFML Reference.

You use built-in functions throughout ColdFusion pages. Built-in functions are frequently used in a cfset or cfoutput tag to prepare data for display or further use. For example, the following line displays today’s date in the format October 24, 2007:

<cfoutput>#DateFormat(Now(), "mmmm d, yyyy")#</cfoutput>

This code uses two nested functions. The Now function returns a ColdFusion date-time value representing the current date and time. The DateFormat function takes the value returned by the Now function and converts it to the desired string representation.

Functions are also valuable in CFScript scripts. ColdFusion does not support ColdFusion tags in CFScript, so you must use functions to access ColdFusion functionality in scripts.

Implicit Get and Set Functions

ColdFusion components support private properties with public setter and getter methods. This behavior supports object-oriented programming by letting you hide component properties from direct access.

By default, properties that you specify by using the <cfproperty> tag have implicit setPropertyName and getPropertyName methods that access the PropertyName property in the CFC variables scope.

Use the following code, for example, to set and get the MyProp property of myCFC component:

myCFC.setMyProp(27); 
theProp = myCFC.getMyProp();

Features of properties with setter and getter methods include the following:

  • Component properties you assign with the set method are in the Variables scope that is private to the CFC. You can get or reset the properties only by calling get or set methods.

  • If a property has a type attribute value, ColdFusion validates the data you pass to the setter function. The default attribute has no effect on the property and does not set an initial property value.

  • A direct assignment statement, such as myCFC.MyProp=27 creates a standard This scope variable in the CFC, even if you specify the property in a cfproperty tag. The This scope variable is independent of the properties that you access using the set and get methods. In fact, you can have a This scope variable with the same name as a property that you access using the set and get methods.

  • Use the cfproperty tag getter and setter attributes to control access to a property from outside the CFC:

    A setter attribute value of true allows application code to set the property (the default behavior).

    A false value specifies that the property can only be set from within the CFC. The getter attribute works similarly.

  • Explicit set or get methods override the implicit set and get methods. Therefore, if a CFC has a MyProp property with an explicit setMyProp method, and you call the setMyProp() function in your application code, ColdFusion uses your function and not an implicit function.

Validate and validateparams attributes

The validate attribute available with <cfproperty> takes the validator to be used for validating data when implicit setter for this property is called. It takes the following validators:

  • string

  • boolean

  • integer

  • numeric

  • date

  • time

  • creditcard: A 13-16 digit number conforming to the mod10 algorithm.

  • email: A valid e-mail address.

  • eurodate: A date-time value. Any date part must be in the format dd/mm/yy. The format can use /, -, or . characters as delimiters.

  • regex: Matches input against pattern specified in validateparams.

  • ssn: A U.S. social security number.

  • telephone: A standard U.S. telephone number.

  • UUID: A Home Universally Unique Identifier, formatted 'XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXXXXX', where 'X' is a hexadecimal number.

  • guid: A Universally Unique Identifier of the form "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" where 'X' is a hexadecimal number

  • zipcode: U.S., 5- or 9-digit format ZIP codes

The validateparams attribute available with <cfproperty> takes the parameters required by the validator specified in the validate attribute. This should be specified in the implicit struct notation.

  • min: Minimum value if validate is integer/numeric/

  • max: Maximum value if the validate is integer/numeric/

  • minLength: Minimum length of the string if the validate is string

  • maxLength: Maximum length of the string if the validate is string

  • pattern: regex expression if the validator specified in validate attribute is regex

For example, the following code sets the validators for e-mail, zipcode, and age of an employee.

Note: For age, validate checks if the value is an integer and validateparams checks the range of the value supplied.
<!---Setting validators for an employee's e-mail, age, and zipcode---> 
<cfcomponent> 
<cfproperty name="mail" validate="email"> 
<cfproperty name="zip" validate="zipcode"> 
<cfproperty name="age" validate="integer" validateparams="{min=18,max=60}"> </cfcomponent>

User-defined functions

You can write your own functions, user-defined functions (UDFs). You can use these functions in ColdFusion expressions or in CFScript. You can call a user-defined function anywhere you can use a built-in CFML function. You create UDFs using the cffunction tag or the cfscriptfunction statement. UDFs that you create using the cffunction tag can include ColdFusion tags and functions. UDFs that you create in CFScript can only include functions. You can create stand-alone UDFs or encapsulate them in a ColdFusion component.

User-defined functions let you encapsulate logic and operations that you use frequently in a single unit. This way, you can write the code once and use it multiple times. UDFs ensure consistency of coding and enable you to structure your CFML more efficiently.

Typical user-defined functions include mathematical routines, such as a function to calculate the logarithm of a number; string manipulation routines, such as a function to convert a numeric monetary value to a string such as “two dollars and three cents”; and can even include encryption and decryption routines.

Note: The Common Function Library Project at www.cflib.org includes a number of free libraries of user-defined functions.

For more information on user-defined functions, see Writing and Calling User-Defined Functions.