TimeFormat

Description

Formats a time value using U.S. English time formatting conventions.

Returns

A custom-formatted time value. If no mask is specified, returns a time value using the hh:nn tt format. For international time formatting, see LSTimeFormat.

Function syntax

TimeFormat(time [, mask ])

History

ColdFusion 10: The mask "m or M" for minute is deprecated. Recommended "n or N".

ColdFusion MX 6.1: Added the mask character L or l to represent milliseconds.

ColdFusion MX:

Changed the way extra characters are processed: this function processes extra characters within the maskvalue differently than in earlier releases, as follows:
- ColdFusion 5 and earlier: the function returns the time format and an apostrophe-delimited list of the extra characters. For example, TimeFormat(Now(), "hh:mm:ss dog") returns 8:17:23 d'o'g.
- ColdFusion MX: the function returns the time format and the extra characters. For example, for the call above, it returns 8:17:23 dog.
  If the extra characters are single-quoted (for example, hh:mm:ss 'dog'), ColdFusion 5 and ColdFusion MX return the time format and the extra characters: 8:17:23 dog.
Added support for the following mask parameter options: short, medium, long, and full.

Parameters

Parameter	Description
time	A date/time value or string to convert
mask	Masking characters that determine the format: h: hours; no leading zero for single-digit hours (12-hour clock) hh: hours; leading zero for single-digit hours (12-hour clock) H: hours; no leading zero for single-digit hours (24-hour clock) HH: hours; leading zero for single-digit hours (24-hour clock) n: minutes; no leading zero for single-digit minutes nn: minutes; a leading zero for single-digit minutes s: seconds; no leading zero for single-digit seconds ss: seconds; leading zero for single-digit seconds l or L: milliseconds, with no leading zeros t: one-character time marker string, such as A or P tt: multiple-character time marker string, such as AM or PM short: equivalent to h:mm tt medium: equivalent to h:mm:ss tt long: medium followed by three-letter time zone; as in, 2:34:55 PM EST full: same as long z: Time zone in literal format, for example, GMT Z: Time zone in hours of offset (RFC 822 TimeZone), for example, +0530 X: Time zone in hours of offset in ISO 8601 format. The following are the three ways of using 'X': X: +05 XX: +0530 XXX: +05:30

Parameter

Description

time

A date/time value or string to convert

mask

Masking characters that determine the format:

h: hours; no leading zero for single-digit hours (12-hour clock)
hh: hours; leading zero for single-digit hours (12-hour clock)
H: hours; no leading zero for single-digit hours (24-hour clock)
HH: hours; leading zero for single-digit hours (24-hour clock)
n: minutes; no leading zero for single-digit minutes
nn: minutes; a leading zero for single-digit minutes
s: seconds; no leading zero for single-digit seconds
ss: seconds; leading zero for single-digit seconds
l or L: milliseconds, with no leading zeros
t: one-character time marker string, such as A or P
tt: multiple-character time marker string, such as AM or PM
short: equivalent to h:mm tt
medium: equivalent to h:mm:ss tt
long: medium followed by three-letter time zone; as in, 2:34:55 PM EST
full: same as long
z: Time zone in literal format, for example, GMT
Z: Time zone in hours of offset (RFC 822 TimeZone), for example, +0530
X: Time zone in hours of offset in ISO 8601 format. The following are the three ways of using 'X':
- X: +05
- XX: +0530
- XXX: +05:30

Usage

When passing a date/time value as a string, enclose it in quotation marks. Otherwise, it is interpreted as a number representation of a date/time object.Database query results for date and time values can vary in sequence and formatting unless you use functions to format the results. To ensure that dates and times display with appropriate formatting, and that users of your ColdFusion application are not confused by dates and times displayed, Adobe recommends that you use the DateFormat and TimeFormat functions to format date and time values from queries.

Example

<cfset todayDate = #Now()#> 
<body> 
<h3>TimeFormat Example</h3> 
<p>Today's date is <cfoutput>#todayDate#</cfoutput>. 
<p>Using Timeformat, we can display the value in different ways: 
<cfoutput> 
<ul> 
<li>#TimeFormat(todayDate)# 
<li>#TimeFormat(todayDate, "hh:nn:ss")# 
<li>#TimeFormat(todayDate, "hh:nn:sst")# 
<li>#TimeFormat(todayDate, "hh:nn:sstt")# 
<li>#TimeFormat(todayDate, "HH:nn:ss")# 
</ul> 
</cfoutput> 
<p>To generate a standard ISO 8601 W3C Date and Time string like 
1997-07-16T19:20, concatenate a DateFormat function, the character T, and a 
TimeFormat function. 
For example: dateformat(now(), "yyyy-mm-dd")#T#TimeFormat(now(), "HH:nn:ss") 
produces:</p> 
<cfoutput>#dateformat(now(), "yyyy-mm-dd")#T#TimeFormat(now(), "HH:nn:ss")#</cfoutput> 
</body>

<cfscript>
    writeoutput(timeFormat(now(), "hh:mm:ss, z"));
    writeoutput(timeFormat(now(), "hh:mm:ss, Z"));
    writeoutput(timeFormat(now(), "hh:mm:ss, X"));
    writeoutput(timeFormat(now(), "hh:mm:ss, XX"));
    writeoutput(timeFormat(now(), "hh:mm:ss, XXX"));
</cfscript>

TimeFormat

Applies to

Description

Returns

Category

Function syntax

See also

History

Parameters

Usage

Example

Example of using masks z, Z, X, XX, and XXX