The Cold Fusion Web Database Construction Kit
NOTE: Because the CreateDate function takes no time values as parameters, the time portion of the created date/time object is set to all zeros. See also: CreateDateTime, CreateODBCDate, CreateTime.
CreateDateTime Description: The CreateDateTime function returns a Cold Fusion date/time object that can be used with other date and time manipulation or formatting functions. CreateDateTime takes six parameters--the date's year, month, and day; and the time's hour, minute, and second.
Syntax: CreateDateTime(Year, Month, Day, Hour, Minute, Second)
Example: The following example creates a date/time object for midnight on New Year's Day 1997:
#CreateDateTime(1997, 1, 1, 0, 0, 0)#
See also: CreateDate, CreateODBCDateTime, CreateTime, ParseDateTime
CreateODBCDate Description: The CreateODBCDate function returns an ODBC date/time
field that can safely be used in SQL statements. CreateODBCDate takes a single parameter--a
Cold Fusion date/time object.
Syntax: CreateODBCDate(Date)
Example: The following example creates an ODBC date/time field for the current day (retrieved with the Now() function):
#CreateODBCDate(Now())#
NOTE: CreateODBCDate always creates an ODBC date/time field that has the time values set to zeros, even if the passed date/time object had valid time values.
TIP: CreateODBCDate takes a date/time object as a parameter. If you want to pass individual date values as parameters, use the CreateDate as the function parameter and pass the values to it.
See also: CreateDate, CreateODBCDateTime, CreateODBCTime
CreateODBCDateTime Description: The CreateODBCDateTime function returns an
ODBC date/time field that can safely be used in SQL statements. CreateODBCDateTime
takes a single parameter--a Cold Fusion date/time object.
Syntax: CreateODBCDate(Date)
Example: The following example creates an ODBC date/time field for the current day (retrieved with the Now() function):
#CreateODBCDateTime(Now())#
TIP: CreateODBCDateTime takes a date/time object as a parameter. If you want to pass individual date and time values as parameters, use the CreateDateTime as the function parameter and pass the values to it.
See also: CreateDate, CreateODBCDate, CreateODBCTime
CreateODBCTime Description: The CreateODBCTime function returns an ODBC date/time
field that can safely be used in SQL statements. CreateODBCTime takes a single parameter--a
Cold Fusion date/time object.
Syntax: CreateODBCTime(Date)
Example: The following example creates an ODBC date/time field for the current day (retrieved with the Now function):
#CreateODBCTime(Now())#
NOTE: CreateODBCTime always creates an ODBC date/time field that has the date values set to zeros, even if the passed date/time object had valid date values.
TIP: CreateODBCTime takes a date/time object as a parameter. If you want to pass individual time values as parameters, use the CreateTime as the function parameter and pass the values to it.
See also: CreateODBCDate, CreateODBCDateTime, CreateTime
CreateTime Description: The CreateTime function returns a Cold Fusion date/time
object that can be used with other time manipulation or formatting functions. CreateTime
takes three parameters--the time's hour, minute, and second.
Syntax: CreateTime(Hour, Minute, Second)
Example: The following example creates a date/time object based on three Cold Fusion fields:
#CreateTime(act_hr, act_mn, act_se)#
NOTE: Because the CreateTime function takes no date values as parameters, the date portion of the created date/time object is set to all zeros.
See also: CreateDate, CreateDateTime, CreateODBCTime
CreateTimeSpan Description: CreateTimeSpan creates a date/time object that
can be used to rapidly perform date- and time-based calculations. CreateTimeSpan
takes four parameters--days, hours, minutes, and seconds. Any of these values may
be set to zero if not needed.
Syntax: CreateTimeSpan(Days, Hours, Minutes, Seconds)
Example: The following example creates a date/time object with a time exactly six hours from now:
<CFSET #detonation# = #Now()# + #CreateTimeSpan(0, 6, 0, 0)#>
TIP: The CreateTimeSpan function is designed to speed up the process of performing date- and time-based calculations. Creating a date/time object with 30 days, and using standard addition operators to add this to an existing date/time object, is quicker than using the DateAdd function.
See also: DateAdd
DateAdd Description: DateAdd is used to add or subtract values to or from
a date/time object; to add a week, for example, or subtract a year. DateAdd takes
three parameters--the first is the date specifier (see Table 30.28), the second is
the number of units to add or subtract, and the third is the date/time object to
be processed. DateAdd returns a modified date/time object.
Syntax: DateAdd( Specifier, Units, Date)
Example: The following example returns tomorrow's date (it adds one day to today's date):
#DateAdd(`D', 1, Now())#
The next example returns a date exactly ten weeks less than the date in a table column:
#DateAdd(`WW', -10, Now())#
TIP: To subtract values from a date/time object, use the DateAdd function and pass a negative number of units. For example, -5 subtracts five units of whatever specifier was passed.
DateCompare Description: DateCompare enables you to compare two dates to see if they are the same or if one is greater than the other. DateCompare takes two parameters--the two dates to compare, which may be specified as date/time objects or string representations of dates. DateCompare returns -1 if the first date is less than the second date, 0 if they are the same, and 1 if the first date is greater than the second date.
Syntax: DateCompare(Date1, Date2)
Example: The following example verifies that a user-supplied order ship date is valid (not already passed):
<CFIF #DateCompare(ship_date, Now())# IS -1> We can't ship orders yesterday! </CFIF>
See also: DateDiff, DatePart
DateDiff Description: DateDiff returns the number of units of a passed specifier
by which one date is greater than a second date. Unlike DateCompare, which returns
the date that is greater, DateDiff tells you how many days, weeks, or months by which
it is greater. DateDiff takes three parameters--the first is the date specifier (see
Table 30.28), and the second and third are the dates to compare.
Syntax: DateDiff(Specifier, Date1, Date2)
Example: The following example returns how many weeks are left in this century by specifying today's date (using the Now() function) and the first date of the next century (using the CreateDate function) as the two dates to compare:
There are #DateDiff("WW", Now(), CreateDate(2000, 1, 1))# weeks left in this century!
NOTE: If the first date passed to DateDiff is greater than the second date, a negative value is returned. Otherwise, a positive value is returned.
See also: DateCompare, DatePart
DatePart Description: DatePart returns the specified part of a passed date.
DatePart takes two parameters--the first is the date specifier (see Table 30.28)
and the second is the date/time object to process.
Syntax: DatePart(Specifier, Date)
Example: The following example returns the day of week that a user was born (and converts it to a string date using the DayOfWeekAsString function):
You were born on a #DayOfWeekAsString(DatePart(`W', dob))#
See also: DateCompare, DateDiff, Day, DayOfWeek, DayOfYear, Hour, Minute, Month, Quarter, Second, Week, Year
Day Description: Day returns a date/time object's day of month as a numeric
value with possible values of 1-31. Day takes a single parameter--the date/time object
to be processed.
Syntax: Day(Date)
Example: The following example returns today's day of month:
Today is day #Day(Now())# of this month
See also: DayOfWeek, DayOfYear, Hour, Minute, Month, Quarter, Second, Week, Year
DayOfWeek Description: DayOfWeek returns a date/time object's day of week
as a numeric value with possible values of 1-7. DayOfWeek takes a single parameter--the
date/time object to be processed.
Syntax: DayOfWeek(Date)
Example: The following example returns today's day of week:
Today is day #DayOfWeek(Now())# of this week
See also: Day, DayOfYear, Hour, Minute, Month, Quarter, Second, Week, Year
DayOfWeekAsString Description: DayOfWeekAsString returns the English weekday
name for a passed day of week number. DayOfWeekAsString takes a single parameter--the
day of week to process, with a value of 1-7.
Syntax: DayOfWeekAsString(DayNumber)
Example: The following example returns today's day of week:
Today is #DayOfWeekAsString(DayOfWeek(Now()))#
See also: DayOfWeek, MonthAsString
DayOfYear Description: DayOfYear returns a date/time object's day of year
as a numeric value, taking leap years into account. DayOfYear takes a single parameter--the
date/time object to be processed.
Syntax: DayOfYear(Date)
Example: The following example returns today's day of year:
Today is day #DayOfYear(Now())# of year #Year(Now())#
See also: Day, DayOfWeek, Hour, Minute, Month, Quarter, Second, Week, Year
DaysInMonth Description: DaysInMonth returns the number of days in a specified
month, taking leap years into account. DaysInMonth takes a single parameter--the
date/time object to evaluate.
Syntax: DaysInMonth(Date)
Example: The following example returns the number of days in the current month:
This month has #DaysInMonth(Now())# days
TIP: DaysInMonth takes a date/time object as a parameter, and there is no equivalent function that takes a year and month as its parameters. Fortunately, this can easily be accomplished by combining the DaysInMonth and CreateDate functions. For example, to determine how many days are in February 2000, you can create a statement that looks like #DaysInMonth(CreateDate(2000, 2, 1))#.
See also: DaysInYear, FirstDayOfMonth
DaysInYear Description: DaysInYear returns the number of days in a specified
year, taking leap years into account. DaysInYear takes a single parameter--the date/time
object to evaluate.
Syntax: DaysInYear(Date)
Example: The following example returns the number of days in the current year:
This year, #Year(Now())#, has #DaysInYear(Now())# days
TIP: DaysInYear takes a date/time object as a parameter, and there is no equivalent function that takes just a year as its parameter. Fortunately, this can easily be accomplished by combining the DaysInYear and CreateDate functions. For example, to determine how many days are in the year 2000, you can create a statement that looks like #DaysInYear(CreateDate(2000, 1, 1))#.
See also: DaysInMonth, FirstDayOfMonth
FirstDayOfMonth Description: FirstDayOfMonth returns the day of the year on
which the specified month starts. FirstDayOfMonth takes a single parameter--the date/time
object to evaluate.
Syntax: FirstDayOfMonth(Date)
Example: The following example returns the day in year that the current month starts on:
#FirstDayOfMonth(Now())#
TIP: FirstDayOfMonth takes a date/time object as a parameter, and there is no equivalent function that takes just a month and year as its parameters. Fortunately, this can easily be accomplished by combining the FirstDayOfMonth and CreateDate functions. For example, to determine the day of year that March 1999 starts on, you can create a statement that looks like #FirstDayOfMonth(CreateDate(1999, 3, 1))#.
See also: DaysInMonth, DaysInYear
Hour Description: Hour returns a date/time object's hour as a numeric value
with possible values of 0-23. Hour takes a single parameter--the date/time object
to be processed.
Syntax: Hour(Date)
Example: The following example returns the current hour of day:
This is hour #Hour(Now())# of the day
See also: Day, DayOfWeek, DayOfYear, Minute, Month, Quarter, Second, Week, Year
IsDate Description: IsDate checks to see if a string contains a valid date,
and returns TRUE if it does and FALSE if it does not. IsDate takes a single parameter--the
string to be evaluated.
Syntax: IsDate(String)
Example: The following example checks to see if a user-supplied date string contains a valid date:
<CFIF #IsDate(ship_date)# IS "No"> You entered an invalid date! </CFIF>
See also: IsLeapYear, ParseDateTime
IsLeapYear Description: IsLeapYear checks to see if a specified year is a
leap year or not. IsLeapYear takes a single parameter--the year to check--and returns
TRUE if it is a leap year and FALSE if not.
Syntax: IsLeapYear(Year)
Example: The following example checks to see if this year is a leap year:
<CFIF #IsLeapYear(Year(Now()))#> #Year(Now())# is a leap year <CFELSE> #Year(Now())# is not a leap year </CFIF>
TIP: IsLeapYear takes a year as a parameter, not a date/time object. To check if a date stored in a date/time object is a leap year, use the Year function to extract the year and pass that as the parameter to IsLeapYear.
See also: IsDate
IsNumericDate Description: IsNumericDate checks to see that a value passed
as a date in the Cold Fusion internal date format is, in fact, a legitimate date.
IsNumericDate takes a single parameter--the date to be checked. This date is a floating
point value with precision until the year 9999. IsNumericDate returns TRUE if the
passed date value is valid, and FALSE if it is not.
Syntax: IsNumericDate(Real)
Example: The following example checks to see if a local variable contains a valid date:
<CFIF #IsNumericDate(var.target_date)# IS "Yes">
See also: IsDate
Minute Description: Minute returns a date/time object's minute as a numeric
value with possible values of 0-59. Minute takes a single parameter--the date/time
object to be processed.
Syntax: Minute(Date)
Example: The following example returns the current time's minutes:
#Minute(Now())# minutes have elapsed since #Hour(Now())# o'clock
See also: Day, DayOfWeek, DayOfYear, Hour, Month, Quarter, Second, Week, Year
Month Description: Month returns a date/time object's month as a numeric value
with possible values of 1-12. Month takes a single parameter--the date/time object
to be processed.
Syntax: Month(Date)
Example: The following example returns the current month:
It is month #Month(Now())# of year #Year(Now())#
See also: Day, DayOfWeek, DayOfYear, Hour, Minute, Quarter, Second, Week, Year
MonthAsString Description: MonthAsString returns the English month name for
a passed month number. MonthAsString takes a single parameter--the number of the
month to process, with a value of 1-12.
Syntax: MonthAsString(MonthNumber)
Example: The following example returns the English name of the current month:
It is #MonthAsString(Month(Now()))#
See also: DayOfWeek, Month
Now Description: Now returns a date/time object containing the current date
and time precisely to the second. Now takes no parameters.
Syntax: Now()
Example: The following example returns the current date and time, formatted for correct display:
It is now #DateFormat(Now())# #TimeFormat(Now())#
NOTE: The Now function returns the system date and time of the computer running the Cold Fusion service, not of the system running the Web browser.
ParseDateTime Description: ParseDateTime converts a date in string form into a Cold Fusion date/time object. ParseDateTime takes a single parameter--the string to be converted.
Syntax: ParseDateTime(String)
Example: The following example converts a user-supplied string containing a date into a Cold Fusion date/time object:
<CFSET #ship_date# = #ParseDateTime(FORM.ship_date)#>
See also: CreateDateTime
Quarter Description: Quarter returns a date/time object's quarter as a numeric
value with possible values of 1-4. Quarter takes a single parameter--the date/time
object to be processed.
Syntax: Quarter(Date)
Example: The following example returns the current quarter:
We are in quarter #Quarter(Now())# of year #Year(Now())#
See also: Day, DayOfWeek, DayOfYear, Hour, Minute, Month, Second, Week, Year
Second Description: Second returns a date/time object's second as a numeric
value with possible values of 0-59. Second takes a single parameter--the date/time
object to be processed.
Syntax: Second(Date)
Example: The following example returns the current minute's seconds:
We are now #Second(Now())# seconds into the current minute
See also: Day, DayOfWeek, DayOfYear, Hour, Minute, Month, Quarter, Week, Year
Week Description: Week returns a date/time object's week in the year as a
numeric value with possible values of 1-53. Week takes a single parameter--the date/time
object to be processed.
Syntax: Week(Date)
Example: The following example returns the current week in the year:
This is week #Week(Now())# of year #Year(Now())#
See also: Day, DayOfWeek, DayOfYear, Hour, Minute, Month, Quarter, Second, Year
Year Description: Year returns a date/time object's year as a numeric value
with possible values of 100-9999. Year takes a single parameter--the date/time object
to be processed.
Syntax: Year(Date)
Example: The following example returns the current year:
It is year #Year(Now())#
See also: Day, DayOfWeek, DayOfYear, Hour, Minute, Month, Quarter, Second, Week
Powerful data manipulation functions and database interaction capabilities are useless unless there are ways to display data in a clean, readable format. Cold Fusion data addresses this need by providing an array of highly capable formatting functions.
Many of these functions take optional format masks as parameters, thereby allowing even greater level of control over the final output.
DateFormat Description: DateFormat displays the date portion of a date/time
object in a readable format. DateFormat takes two parameters--the first is the date/time
object to be displayed, and the second is an optional mask value allowing exact control
of how the data is formatted. If no mask is specified, the default mask of "DD-MMM-YY"
is used. The complete set of date masks is listed in Table 30.29.
Syntax: DateFormat(Date [, mask])
| Mask | Description |
| D | Day of the month in numeric form, with no leading zero for single-digit days |
| DD | Day of the month in numeric form, with a leading zero for single-digit days |
| DDD | Day of the week as a three-letter abbreviation (for example, "Sun" for "Sunday") |
| DDDD | Day of the week as its full English name |
| M | Month in numeric form, with no leading zero for single-digit months |
| MM | Month in numeric form, with a leading zero for single-digit months |
| MMM | Month as a three-letter abbreviation (for example, "Jan" for "January") |
| MMMM | Month as its full English name |
| Y | Year as last two digits of the year, with no leading zero for years less than ten |
| YY | Year as last two digits of the year, with a leading zero for years less than ten |
| YYYY | Year as the full four digits |
Example: The following example displays today's date with the default formatting options:
Today is: #DateFormat(Now())#
The next example displays the same date, but uses the full names of both the day of week and the month:
It is #DateFormat(Now(), "DDDD, MMMM DD, YYYY")#
The final example displays today's date in the European format (day/month/year):
It is #DateFormat(Now(), "DD/MM/YY")#
NOTE: Unlike the TimeFormat function mask specifiers, the DateFormat function mask specifiers are case-insensitive.
See also: TimeFormat
DecimalFormat Description: DecimalFormat is a simplified number formatting
function that outputs numbers with two decimal places, commas to separate the thousands,
and a minus sign for negative values. DecimalFormat takes a single parameter--the
number to display.
Syntax: DecimalFormat(Number)
Example: The following example displays a table column in the decimal format:
Quantity: #DecimalFormat(quantity)#
TIP: For more precise numeric display, use the NumberFormat function.
See also: NumberFormat
DollarFormat Description: DollarFormat is a simplified U.S. currency formatting
function that outputs numbers with a dollar sign at the front, two decimal places,
commas to separate the thousands, and a minus sign for negative values. DollarFormat
takes a single parameter--the number to display.
Syntax: DollarFormat(Number)
Example: The following example displays the results of an equation (quantity multiplied by item cost) in the dollar format:
Total cost: #DollarFormat(quantity*item_cost)#
TIP: For more precise currency display, use the NumberFormat function instead.
See also: NumberFormat
HTMLCodeFormat Description: HTMLCodeFormat displays text with HTML codes with
a preformatted HTML block (using the <PRE> and </PRE> tags). HTMLCodeFormat
takes a single parameter--the text to be processed.
Syntax: HTMLCodeFormat(Text)
Example: The following example uses preformatted text to display the code used to generate a dynamic Web page:
#HTMLCodeFormat(page)#
TIP: ParagraphFormat is very useful for displaying data into FORM TEXTAREA fields.
See also: HTMLCodeFormat, ParagraphFormat
HTMLEditFormat Description: HTMLEditFormat converts supplied text into a safe
format, with any HTML control characters converted to their appropriate entity codes.
HTMLEditFormat takes a single parameter--the text to convert.
Syntax: HTMLEditFormat(Text)
Example: The following example displays the HTML code that is used to render a dynamic Web page inside a bordered box:
<TABLE BORDER> <TR> <TD>#HTMLEditFormat(page)#</TD> </TR> </TABLE>
TIP: Use HTMLEditFormat to display HTML code and tags within your page.
See also: HTMLCodeFormat, ParagraphFormat
NumberFormat Description: NumberFormat enables you to display numeric values
in a readable format. NumberFormat takes two parameters--the number to be displayed
and an optional mask value. If the mask is not specified, the default mask of "
,99999999999999" will be used. The complete set of number masks is listed in
Table 30.30.
Syntax: NumberFormat(Number [, mask])
| Mask | Description |
| _ | Optional digit placeholder |
| 9 | Optional digit placeholder (same as _ but shows decimal place more clearly) |
| . | Location of decimal point |
| 0 | Forces padding with zeros |
| () | Displays parentheses around the number if it is less than 0 |
| + | Displays a plus sign in front of positive numbers and a minus sign in front of negative numbers |
| - | Displays a minus sign in front of negative numbers and leaves a space in front of positive numbers |
| , | Separates thousands with commas |
| C | Center-justifies number within mask width |
| L | Left-justifies number within mask width |
| $ | Places dollar sign in front of the number |
| ^ | Specifies the exact location for separating left and right formatting |
Example: To demonstrate how the number masks can be used, Table 30.31 lists examples of different masks being used to format the numbers 1453.876 and -1453.876:
| Mask | Result | Notes |
| NumberFormat(1453.876, "9999") | 1454 | Because no decimal point was specified in the mask, the number is rounded to the nearest integer value. |
| NumberFormat(-1453.876, "9999") | -1454 | |
| NumberFormat(1453.876, "9999.99") | 1453.88 | Even though a decimal point is provided, the number of decimal places specified is less than is needed, so the decimal portion must be rounded to the nearest integer value. |
| NumberFormat(1453.876, "(9999.99)") | 1453.88 | Because the number is a positive number, the parentheses are ignored. |
| NumberFormat(-1453.876, "(9999.99)") | (1453.88) | Because the number is a negative number, parentheses are displayed around the number. |
| NumberFormat(1453.876, "-9999.99") | 1453.88 | Because the number is a positive number, the minus is ignored. |
| NumberFormat(-1453.876, "-9999.99") | -1453.88 | Because the number is a negative number, the minus is displayed. |
| NumberFormat(1453.876, "+9999.99") | +1453.88 | Because the number is a positive number, a plus sign is displayed. |
| NumberFormat(-1453.876, "+9999.99") | -1453.88 | Because the number is a negative number, a minus is displayed. |
| NumberFormat(1453.876, "$9999.99") | $1453.88 | |
| NumberFormat(1453.876, "C99999^9999") | 1453.876 | Because position six of the mask is a carat character, the decimal point will be positioned there even though there are less than six digits before the decimal point. This allows you to align columns of numbers at the decimal point. Without the carat, the number would have been left aligned. |
See also: DecimalFormat, DollarFormat
TimeFormat Description: TimeFormat displays the time portion of a date/time
object in a readable format. TimeFormat takes two parameters--the first is the date/time
object to be displayed, and the second is an optional mask value allowing you to
control exactly how the data is formatted. If no mask is specified, the default mask
of "hh:mm tt" is used. The complete set of date masks is listed in Table
30.32.
Syntax: TimeFormat(Date [, mask])
| Mask | Description |
| h | Hours in 12-hour clock format, with no leading zero for single-digit hours |
| hh | Hours in 12-hour clock format, with a leading zero for single-digit hours |
| H | Hours in 24-hour clock format, with no leading zero for single-digit hours |
| HH | Hours in 24-hour clock format, with a leading zero for single-digit hours |
| m | Minutes, with no leading zero for single-digit minutes |
| mm | Minutes, with a leading zero for single-digit minutes |
| s | Seconds, with no leading zero for single-digit seconds |
| ss | Seconds, with a leading zero for single-digit seconds |
| t | Single-character meridian specifier, either "A" or "P" |
| tt | Two-character meridian specifier, either "AM" or "PM" |
Example: The following example displays the current time with the default formatting options:
The time is: #TimeFormat(Now())#
The next example displays the current time with seconds in 24-hour clock:
The time is: #TimeFormat(Now(), "HH:mm:ss")#
NOTE: Unlike the DateFormat function mask specifiers, the TimeFormat function mask specifiers are case-sensitive.
See also: DateFormat
ParagraphFormat Description: ParagraphFormat converts text with embedded carriage
returns for correct HTML display. HTML ignores carriage returns in text, so for these
to be displayed correctly, they must be converted to HTML paragraph markers (the
<P> tag). ParagraphFormat takes a single parameter--the text to be processed.
Syntax: ParagraphFormat(Text)
Example: The following example displays converted text files inside a FORM TEXTAREA field:
<TEXTAREA NAME="comments>#ParagraphFormat(comments)#</TEXTAREA>
TIP: ParagraphFormat is very useful for displaying data into FORM TEXTAREA fields.
See also: HTMLCodeFormat, HTMLEditFormat
YesNoFormat Description: YesNoFormat converts TRUE and FALSE values to "Yes"
and "No". YesNoFormat takes a single parameter--the number, string, or
expression to evaluate. When evaluating numbers, YesNoFormat treats 0 as FALSE, and
any non-zero value as TRUE.
Syntax: YesNoFormat(Value)
Example: The following example converts a table Boolean value to a "Yes" or "No" string:
Member: #YesNoFormat(member)#
See also: IsBoolean
To assist you in performing calculations, Cold Fusion comes with a complete suite of mathematical and random number generation functions and arithmetic expressions.
Some of the mathematical functions take one or more numeric values as parameters. You may pass real values and integer values, as well as Cold Fusion fields, to these functions.
As with all Cold Fusion functions, these mathematical functions may be nested.
Table 30.33 lists the complete set of Cold Fusion mathematical functions. Table 30.34 lists the supported arithmetic expressions.
| Function | Parameters | Returns |
| Abs | (number) | Absolute value of passed number |
| Atn | (number) | Arc tangent of passed number |
| Ceiling | (number) | The closest integer greater than, or equal to, the passed number |
| Cos | (number) | Cosine of passed number |
| DecrementValue | (number) | Number decremented by 1 |
| Exp | (number) | E to the power of passed number |
| Fix | (number) | If passed number is greater or equal to 0, returns closest integer smaller than the passed number. If not, it returns closest integer greater than passed number |
| IncrementValue | (number) | Number incremented by 1 |
| Int | (number) | The closest integer smaller than, or equal to, the passed number |
| Log | (number) | Natural logarithm of passed number |
| Log10 | (number) | Base 10 log of passed number |
| Max | (number1, number2) | The greater of the two passed numbers |
| Min | (number1, number2) | The smaller of the two passed numbers |
| Pi | Value of pi as 3.14159265359 | |
| Rand | A random number between 0 and 1 | |
| Randomize | (number) | Seed the random number generator with the passed number |
| RandRange | (number1, number2) | A random integer value between the two passed numbers |
| Round | (number) | The integer closest (either greater or smaller) to the passed number |
| Sgn | (number) | Sign, either -1, 0, or 1, depending on whether passed number is negative, zero, or positive |
| Sin | (number) | Sine of passed number |
| Sqr | (number) | Square root of passed number |
| Tan | (number) | Tangent of passed number |
| Expression | Description |
| + | Addition |
| - | Subtraction |
| * | Multiplication |
| / | Division |
| MOD | Modular (finds remainder) |
| \ | Integer division (both values must be integers) |
| ^ | Power |
Example: This first example returns the natural logarithm of the number 10.
#Log(10)#
This next example returns the value of pi rounded to the nearest integer value, 3.
#Round(Pi())#
The following example uses the Min() and Max() functions to determine the greater and smaller of two Cold Fusion fields:
Of the two numbers #Num1# and #Num2#, Max(#Num1#, #Num2#) is the greater, and Min(#Num1#, #Num2#) is the smaller
To generate random numbers, you can use the Rand and RandRange functions. The following example generates a random number between 1 and 1000:
#RandRange(1, 1000)#
The next example creates a variable that contains a total cost of several items:
<CFSET #total# = #quantity# * #item_price#>
NOTE: If the Rand() or RandRange() functions are used prior to issuing a Randomize() statement, the random number generator will be seeded with a random value.
Cold Fusion lists are an efficient way to manage groups of information. Lists are made up of elements--values separated by delimiting characters. The default delimiter is a comma, but you can change it to any character or string.
This list format is very well suited for Cold Fusion applications because it is both the format that HTML forms use to submit fields with multiple values and the format used by SQL to specify lists in SQL statements.
When using the list manipulation functions, remember the following:
NOTE: All of the Cold Fusion list manipulation functions have names that begin with the word "list", making them easy to spot in your code.
TIP: Lists may be used in conjunction with the <CFLOOP> tag for processing.
ListAppend Description: ListAppend adds an element to a list and returns the new list with the appended element. ListAppend takes two parameters--the first is the current list, and the second is the element to be appended.
Syntax: ListAppend(List, Element)
Example: The following example appends "John" to an existing list of users and replaces the old list with the new one:
<CFSET #Users# = #ListAppend(Users, "John")#>
See also: ListInsertAt, ListPrepend, ListSetAt
ListChangeDelims Description: ListChangeDelims returns a passed list, reformatted
to use a different delimiter. ListChangeDelims takes two parameters--the first is
the list to be reformatted, and the second is the new delimiter character.
Syntax: ListChangeDelims(List, Delimiter)
Example: The following example creates a new list containing the same elements as the original list, but separated by plus signs:
<CFSET #URLUsers# = #ListChangeDelims(Users, "+")#>
TIP: The default list delimiter, a comma, is the delimiter used by SQL lists. If you're going to be passing Cold Fusion lists to SQL statements, you should use the default delimiter.
ListContains, ListContainsNoCase Description: The ListContains and ListContainsNoCase functions search through a list to find the first element that contains the specified search text. If the search text is found, the position of the element containing the text is returned; if no match is found, 0 is returned. ListContains performs a case-sensitive search, and ListContainsNoCase performs a case-insensitive search. Both functions take two parameters--the first parameter is the list to be searched, and the second parameter is the value to search.
Syntax: ListContains(List, Value)
ListContainsNoCase(List, Value)
Example: The following example returns the position of the first element to contain the text "cash"(regardless of case):
Element #ListContainsNoCase(Payments, "cash")# contains the word "cash"
NOTE: ListContains and ListContainsNoCase find substrings within elements that match the specified search text. To perform a search for a matching element, use the ListFind and ListFindNoCase functions.
See also: ListFind, ListFindNoCase
ListDeleteAt Description: ListDeleteAt deletes a specified element from a
list. ListDeleteAt takes two parameters--the first is the list to be processed, and
the second is the position of the element to be deleted. ListDeleteAt returns a modified
list with the specified element deleted. The specified element position must exist.
If you specify an element that is beyond the range of the list, an error message
will be generated.
Syntax: ListDeleteAt(List, Position)
Example: The following example deletes the second element in a list, but first verifies that it exists:
<CFIF #ListLen(Users)# GTE 2> <CFSET #Users# = ListDeleteAt(Users, 2)> </CFIF>
See also: ListRest
ListFind, ListFindNoCase Description: The ListFind and ListFindNoCase functions
search through a list to find the first element that matches the specified search
text. If a matching element is found, the position of that element is returned; if
no match is found, 0 is returned. ListFind performs a case-sensitive search, and
ListFindNoCase performs a case-insensitive search. Both functions take two parameters--the
first parameter is the list to be searched, and the second parameter is the element
text to search.
Syntax: ListFind(List, Value)
ListFindNoCase(List, Value)
Example: The following example returns the position of the MI, the value of the first element:
MI is element #ListFind(States, "MI")#
NOTE: ListFind and ListFindNoCase only find elements that exactly match the specified search text. To perform a search for substrings within elements, use the ListContains and ListContainsNoCase functions.
See also: ListContains, ListContainsNoCase
ListFirst Description: ListFirst returns the first element in a list. ListFirst
takes a single parameter--the list to be processed.
Syntax: ListFirst(List)
Example: The following example returns the first selection from a field of book titles submitted by a user:
The first title you selected is #ListFirst(titles)#
See also: ListGetAt, ListLast, ListRest
ListGetAt Description: ListGetAt returns the list element at a specified position.
ListGetAt takes two parameters--the first is the list to process, and the second
is the position of the desired element. The value passed as the position parameter
must not be greater than the length of the list or a Cold Fusion error message will
be generated.
Syntax: ListGetAt(List, Position)
Example: The following example returns the name of the fourth selection from a field of book titles submitted by a user:
The fourth title you selected is #ListGetAt(titles, 4)#
See also: ListFirst, ListLast, ListRest
ListInsertAt Description: ListInsertAt inserts a specified element into a
list, shifting all elements after it one position to the right. ListInsertAt takes
three parameters--the first is the list to be processed, the second is the desired
position for the new element, and the third is the value of the new element. The
position parameter must be no greater than the number of elements in the list. If
a greater value is provided, a Cold Fusion error message will be generated.
Syntax: ListInsertAt(List, Position, Value)
Example: The following example inserts "John" into the third position of an existing list of users and replaces the old list with the new one:
<CFSET #Users# = #ListInsertAt(Users, 3, "John")#>
See also: ListAppend, ListPrepend, ListSetAt
ListLast Description: ListLast returns the first element in a list. ListLast
takes a single parameter--the list to be processed.
Syntax: ListLast(List)
Example: The following example returns the last selection from a field of book titles submitted by a user:
The last title you selected is #ListLast(titles)#
See also: ListFirst, ListGetAt, ListRest
ListLen Description: ListLen returns the number of elements present in a list.
ListLen takes a single parameter--the list to be processed.
Syntax: ListLen(List)
Example: The following example returns the number of books selected by a user:
You selected #ListLen(titles)# titles
ListPrepend Description: ListPrepend inserts an element at the beginning of a list, pushing any other element to the right. ListPrepend returns the new list with the prepended element. ListPrepend takes two parameters--the first is the current list, and the second is the element to be prepended.
Syntax: ListPrepend(List, Element)
Example: The following example prepends "John" to an existing list of users and replaces the old list with the new one:
<CFSET #Users# = #ListPrepend(Users, "John")#>
See also: ListAppend, ListInsertAt, ListSetAt
ListRest Description: ListRest returns a list containing all the elements
after the first element. If the list contains only one element, an empty list (an
empty string) will be returned. ListRest takes a single parameter--the list to be
processed.
Syntax: ListRest(List)
Example: The following example replaces a list with the list minus the first element:
<CFSET #Users# = #ListRest(Users)#>
See also: ListDeleteAt
ListSetAt Description: ListSetAt replaces the value of a specific element
in a list with a new value. ListSetAt takes three parameters--the first is the list
to be processed, the second is the position of the element to be replaced, and the
third is the new value. The value passed to the position parameter must be no greater
than the number of elements in the list or a Cold Fusion error message will be generated.
Syntax: ListSetAt(List, Position, Value)
Example: The following searches for an element with the value of "Ben" and replaces it with the value "Benjamin":
<CFIF #ListFindNoCase(Users, "Ben")# GT 0> <CFSET #Users# = #ListSetAt(Users, ListFindNoCase(Users, "Ben"), "Benjamin")#> </CFIF>
See also: ListAppend, ListInsertAt, ListPrepend
The Cold Fusion system functions allow you to perform manipulation of file paths, create temporary files, and verify file existence.
ExpandPath Description: ExpandPath converts a path relative to the web server
document root into a fully qualified path. ExpandPath takes a single parameter--the
path to be converted.
Syntax: ExpandPath(Path)
Example: The following example returns the full path of the server's default document:
#ExpandPath("index.cfm")#
NOTE: ExpandPath requires that you pass it a relative path, and not a fully qualified path.
See also: GetTemplatePath
FileExists Description: FileExists checks for the existence of a specified
file and returns either TRUE or FALSE. FileExists takes a single parameter--the name
of the file to check. The file name cannot be a relative path, but must be specified
as a fully qualified path.
Syntax: FileExists(File)
Example: The following example checks for the existence of an image file before using it in an IMG tag:
<CFIF #FileExists("C:\root\images\logo.gif")#>
<IMG SRC="/images/logo.gif">
</CFIF>
TIP: To avoid hard coding the file name passed to the FileExists function, use the ExpandPath function to convert the relative path to an actual file name.
GetDirectoryFromPath Description: GetDirectoryFromPath extracts the drive and directory (with a trailing backslash) from a fully specified path. GetDirectoryFromPath takes a single parameter--the path to be evaluated.
Syntax: GetDirectoryFromPath(Path)
Example: The following example returns the directory portion of a current template's full file path:
#GetDirectoryFromPath(GetTemplatePath())#
See also: GetFileFromPath
GetFileFromPath Description: GetFileFromPath extracts the file name from a
fully specified path. GetFileFromPath takes a single parameter--the path to be evaluated.
Syntax: GetFileFromPath(Path)
Example: The following example returns the file name portion of a temporary file:
#GetFileFromPath(GetTempFile(GetTempDirectory(), "CF"))#
See also: GetDirectoryFromPath
GetTempDirectory Description: GetTempDirectory returns the full path of the
Windows temporary directory with a trailing backslash. GetTempDirectory takes no
parameters.
Syntax: GetTempDirectory()
Example: The following example returns the name of a temporary file beginning with the letters "CF" in the Windows temporary directory:
#GetTempFile(GetTempDirectory(), "CF")#
See also: GetTempFile
GetTempFile Description: GetTempFile returns the full path to a temporary
file for use by your application. The returned file name is guaranteed to be unique.
GetTempFile takes two parameters--the first is the directory where you'd like the
temporary file to be created, and the second is a file name prefix of up to three
characters. You may not omit the prefix, but you may pass an empty string ("
").
Syntax: GetTempFile(Directory, Prefix)
Example: The following example returns the name of a temporary file beginning with the letters "CF" in the Windows temporary directory:
#GetTempFile(GetTempDirectory(), "CF")#
TIP: To create a temporary file in the Windows temporary directory, pass the GetTempDirectory function as the directory parameter.
See also: GetTempDirectory
GetTemplatePath Description: GetTemplatePath returns the fully qualified path
of the base template being processed. GetTemplatePath takes no parameters.
Syntax: GetTemplatePath()
Example: The following example returns the full path of the base template being processed:
Processing: #GetTemplatePath()#
NOTE: GetTemplatePath returns the path of the base template being processed. If you are using GetTemplatePath in a template that is being included in a second template, the path of the second template will be returned.
Client Variables allow you to store client information so that it is available between sessions. Client variables may be accessed just like any other Cold Fusion variables, so standard variable access tools, like <CFSET>, can be used to set variables. In addition, these functions provide special variable manipulation capabilities.
For more information about client variables and how they are used, see Chapter 23, "Web Application Framework."
DeleteClientVariable Description: DeleteClientVariable deletes the name of the client variable that is passed as a parameter. Unlike other Cold Fusion variables, client variables persist over time and must be deleted with this function. DeleteClientVariable takes a single parameter--the name of the variable to delete. DeleteClientVariable returns TRUE if the variable was deleted and FALSE if it was not.
Syntax: DeleteClientVariable(Variable)
Example: The following example deletes a variable named "login_name" and sets a local variable with the function return value:
<CFSET DeleteSuccessful = #DeleteClientVariable("login_name")#>
GetClientVariablesList Description: GetClientVariablesList returns a comma- delimited list of the read-write client variables available to the template. The standard read-only system client variables, listed in Table 30.35, are not returned. GetClientVariablesList takes no parameters.
Syntax: GetClientVariablesList()
Variable Description
CFID Unique ID assigned to this client.
CFToken Unique security token that is used to verify the authenticity of a CFID value.
URLToken Text to append to URLs; contains both CFID and CFToken. (Appended automatically to <CFLOCATION> URLs.)
Example: The following example retrieves the entire list of read-write client variables:
#ListLen(GetClientVariablesList())# read-write client variables are currently active
TIP: The list of variables returned by the GetClientVariablesList function is comma-delimited, which makes it very suitable for processing with the Cold Fusion list functions.
Cold Fusion allows you to perform dynamic expression evaluation. This is an advanced technique that enables you to build and evaluate expression on-the-fly.
Dynamic expression evaluations are performed on string expressions. A string expression is a string that contains an expression. The string "1+2" contains an expression that, when evaluated, will return 3. String expressions can be as simple or as complex as needed.
Additional information on Cold Fusion expressions is available later in this chapter, in the section entitled "Cold Fusion Expressions."
DE Description: DE stands for Delay Evaluation. This function is designed
to be used with the IIF and Evaluate functions. It takes a string as a parameter
and returns the same string enclosed within quotes, with all double quotes escaped.
This enables you to pass a string to IIf and Evaluate without them being evaluated.
Syntax: DE(String)
Example: The following example uses DE to ensure that the string "A" is evaluated instead of the variable "A".
#Evaluate(DE("A"))#
Evaluate Description: Evaluate is used to evaluate string expressions. Evaluate takes one or more string expressions as parameters and evaluates them from left to right.
Syntax: Evaluate(String1, ...)
Example: The following example evaluates the variable "A":
#Evalutate("A")#
IIf Description: IIf evaluates a Boolean condition and evaluates one of two expressions depending on the results of that evaluation. If the Boolean condition returns TRUE, the first expression is evaluated; if the condition returns FALSE, the second expression is evaluated.
Syntax: IIF(Boolean condition, Expression if TRUE, Expression if FALSE)
Example: The following example checks to see if #cnt# has a value of 1 and evaluates "A" if it does, and "B" if not:
#IIf("#cnt# IS 1", "A", "B")#
SetVariable Description: SetVariable sets a specified variable to a passed value.
Syntax: SetVariable(Variable, Value)
Example: The following example sets variable #cnt# to the value returned by the passed expression:
#SetVariable(#cnt#, "A")#
Cold Fusion provides a complete set of bit manipulation functions for use by advanced developers only. These functions enable you to manipulate the individual bits within a 32-bit integer.
The complete set of bit manipulation functions is listed in Table 30.36. The descriptions for each function are given in the C/C++ syntax.
NOTE: Any start, length, or position parameters that pass to the bit manipulation functions must be in the range of 0-31.
| Function | Description |
| BitAnd(x, y) | x & y |
| BitMaskClear(x, start, length) | x with length bits starting from start cleared |
| BitMaskRead(x, start, length) | The value of the length bits starting from start |
| BitMaskSet(x, mask, start, length) | x with mask occupying the length bits starting from start |
| BitNot(x) | ~x |
| BitOr(x, y) | x | y |
| BitSHLN(x, n) | x << n |
| BitSHRN(x, n) | x >> n |
| BitXor(x, y) | x^y |
These miscellaneous functions are some of the ones you'll likely find yourself using repeatedly.
IsBoolean Description: IsBoolean checks to see whether a value can be converted
to a Boolean value or not. (Boolean values have two states only: ON or OFF [or TRUE
and FALSE].) IsBoolean takes a single parameter--the number, string, or expression
to evaluate. When evaluating numbers, IsBoolean treats 0 as FALSE and any non-zero
value as TRUE.
Syntax: IsBoolean(Value)
Example: The following example checks to see if a value can be safely converted into a Boolean value before passing it to a formatting function:
<CFIF #IsBoolean(status)# IS "Yes"> #YesNoFormat(status)# </CFIF>
See also: YesNoFormat
IsNumeric Description: IsNumeric checks to see if a specified value is numeric.
IsNumeric takes a single parameter--the value to be evaluated.
Syntax: IsNumeric(Value)
Example: The following example checks to ensure that a user entered a valid age (numeric characters only):
<CFIF #IsNumeric(age)# IS "No"> You entered an invalid age! </CFIF>
See also: InputBaseN, Val
ParameterExists Description: ParameterExists checks to see if a specified
variable exists. ParameterExists returns TRUE if the specified variable exists and
FALSE if not. ParameterExists takes a single parameter--the variable to check. This
parameter may be passed as a fully qualified variable with a preceding variable type
designator. Do not enclose the variable name in quotes.
Syntax: ParameterExists(Parameter)
Example: The following example checks to see if a variable of any type named "USER_ID" exists:
<CFIF #ParameterExists(USER_ID)# IS "Yes">
The next example checks to see if a CGI variable named "USER_ID" exists and ignores variables of other types:
<CFIF #ParameterExists(CGI.USER_ID)# IS "Yes">
NOTE: One of the most important uses of the ParameterExists function is creating dynamic SQL statements using the <CFQUERY> tag.
PreserveSingleQuotes Description: PreserveSingleQuotes is used to instruct Cold Fusion to not "escape" single quotes contained in values derived from dynamic parameters. PreserveSingleQuotes takes a single parameter--the string to be preserved.
Syntax: PreserveSingleQuotes(String)
Example: The following example uses PreserveSingleQuotes to ensure that a dynamic parameter in a SQL statement is included correctly:
SELECT * FROM Customers WHERE CustomerName IN (#PreserveSingleQuotes(CustNames)#)
QuotedValueList, ValueList Description: QuotedValueList and ValueList are used to drive one query with the results of another. Both functions take a single parameter--the name of a query column--and returns a list of all the values in that column. QuotedValueList returns a list of values that are each enclosed within quotation marks and separated by commas. ValueList returns the list separated by commas, but not enclosed in quotation marks.
Syntax: QuotedValueList(Column)
ValueList(Column)
Example: The following example retrieves a list of customers who live in states already selected by a prior query:
SELECT * FROM Customers WHERE State IN (#QuotedValueList(States)#)
NOTE: The QuotedValueList and ValueList functions are typically only used when constructing dynamic SQL statements.
TIP: The values returned by QuotedValueList and ValueList are both in the standard Cold Fusion list format and can, therefore, be manipulated by the list functions.
TIP: As a general rule, unless you need to manipulate the values in the list, you should always try to combine both the queries into a single SQL statement. The time it'll take to process one combined SQL statement will be far less than the time it takes to process two simpler statements.
URLEncodedValue Description: URLEncodedValue encodes a string in a format that may be safely used within URLs. URLs may not contain spaces or other non-alphanumeric characters. The URLEncodedValue function replaces spaces with a plus sign and non- alphanumeric characters with equivalent hexadecimal escape sequences. URLEncodedValue takes a single parameter--the string to be encoded, and returns the encoded string.
Syntax: URLEncodedValue(String)
NOTE: Cold Fusion automatically decodes all URL parameters that are passed to a template.
Example: The following example creates a URL with a name parameter that may safely include any characters:
<A HREF="details.cfm?name=#URLEncodedFormat(name)#" >Details</A>
Expressions are combinations of data, variables, operators, and functions that together create a value. Expressions are used in string manipulation, calculations, data formatting, and numerous other applications.
This first example is an expression that returns the mathematical value of 2:
1 + 1
This next example is a slightly more complex mathematical expression which returns a value of 20:
2 * (4 + 6)
The following is an example of an expression that returns a Boolean value (either TRUE or FALSE); in this case, definitely FALSE:
"Sunday" IS "Monday"
Expressions can contain functions too. This next expression returns the uppercase equivalent of the passed string:
#UCase("Michigan")#
If you've ever developed software in any strong typed language, you're going to love Cold Fusion's typeless expressions. Typeless expressions refer to Cold Fusion's ability to automatically convert data between different types as needed.
The following code sample is a good example of this. Multiplying an integer by a string will generate a compiler error (or worse) in most languages. Cold Fusion, however, knows to convert the string to a number in order to perform this calculation:
<CFSET #sum# = 12 * "6">
It is important to understand the limitations of the typeless expression parser:
© Copyright, Macmillan Computer Publishing. All rights reserved.