|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Functions
|
|
|
|
Functions are predefined operations you can use to manipulate data. In ColdFusion, functions let you perform decision-making, date/time-formatting, and other common operations automatically.
ColdFusion provides a variety of functions that perform many types of tasks. For example, you can use a mathematical function to take the square root of a number, or a string function to find the first letter of a word.
See the CFML Language Reference for a full catalog of ColdFusion functions.
|
|
|
|
Function types |
|
|
|
In ColdFusion, functions are organized by category, as shown in the following table:
Function Categories
|
Category
|
Purpose
|
Administrative functions
|
Perform actions on client variables.
|
Array functions
|
Create, edit, and manage arrays.
|
Date and Time functions
|
Perform date-and-time actions.
|
Decision functions
|
Test for arrays, queries, and simple values.
|
Display and Formatting functions
|
Control the display of dates, times, and numbers.
|
Dynamic Evaluation functions
|
Evaluate dynamic expressions, define variable values.
|
International locale functions
|
Perform date, time, and currency formatting based on a specified locale, such as French (Standard) and French (Canadian).
|
List functions
|
Perform actions on lists.
|
Mathematical and Trigonometric functions
|
Perform mathematical operations on values.
|
Query functions
|
Perform actions on queries.
|
Strings functions
|
Perform actions on text values.
|
Structure functions
|
Create, edit, and manage structures.
|
System-level functions
|
Perform actions on directories and paths.
|
|
|
|
|
Function usage |
|
|
|
All functions return a value, which is one of the basic expression objects:
- Numbers
- Strings
- Boolean values
- Date-and-time objects
- Lists
- Arrays
- Structures
- Queries
- COM objects
Often, the returned value is computed based on some data passed to the function from the ColdFusion application page. Data is passed to functions via their arguments (also known as parameters).
Although some functions take no parameters, such as, Now() which returns the current date and time, most functions take at least one argument. Any valid ColdFusion expression can be an argument to a function. This means that functions can take functions as arguments. (This is known as nesting functions.)
The following table illustrates function syntax and usage guidelines.
Function Syntax Guidelines
|
Usage
|
Example
|
The exception -- no arguments
| Function()
|
Basic format
| Function(Data)
|
Nesting functions
| Function1(Function2(Data))
|
Separate multiple arguments with commas
| Function(data1, data2, data3)
|
Enclose string arguments in single or double quotes
| Function('This is a demo') Function("This
is a demo")
|
Arguments are expressions
| Function1(X*Y, Function2("Text"))
|
To learn how to insert functions in various types of expressions see Using Pound Signs.
|
|
|
|
Optional arguments in functions |
|
|
|
Some functions may take optional arguments after their required arguments. If omitted, optional arguments take some default value. For example:
Replace("FooFoo", "Foo", "Boo") returns "BooFoo"
Replace("FooFoo", "Foo", "Boo", "ALL") returns "BooBoo"
The difference in behavior is explained by the fact that the Replace function takes an optional fourth argument which specifies the scope of replacement. The default value is "ONE" which explains why only the first occurrence of "Foo" was replaced with "Boo". In the second example, a fourth argument is provided that forces the function to replace all occurrences of "Foo" with "Boo".
|
|
|
|
Functions that return a Boolean |
|
|
|
When you test the return of any function that returns a Boolean value, the output will always appear to be YES or NO. The actual Boolean return is TRUE or FALSE, but when tested in a CFIF statement, the Boolean return is converted to its string equivalent, YES or NO.
Each of the following examples demonstrates a valid test for a Boolean return:
<CFIF #booleanfunction(arg1, arg2)# IS TRUE>
<CFIF #booleanfunction(arg1, arg2)# IS "YES">
<CFIF #booleanfunction(arg1, arg2)# IS 1>
<CFIF #booleanfunction(arg1, arg2)#>
Note in the second example that YES must be enclosed in quotation marks since it is resolved as a string. This is an important point to keep in mind for an example such as:
<CFSET ReturnValue= #booleanfunction(arg1, arg2)#>
<CFIF ReturnValue IS "YES">
|
|
|
|
Preferred method
|
|
|
The preferred method from the previous examples omits the explicit condition from the expression, as shown below:
<CFIF #booleanfunction(arg1, arg2)#>
|
|
|
  
|
|
|
AllaireDoc@allaire.com
Copyright © 1998, Allaire Corporation. All rights reserved.
|
|