TimeFormat

Description

Formats a time value.

Return value

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

Syntax

TimeFormat(time [, mask ])

History

New in ColdFusion MX: This function processes extra characters within the mask value 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:ssdog") returns 8:17:23d'o'g.
ColdFusion MX: the function returns the time format and the extra characters. For example, for the call above, it returns 8:17:23dog.

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:23dog.

New in ColdFusion MX: This function supports the short, medium, long, and full mask attribute options.

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)

m: Minutes; no leading zero for single-digit minutes

mm: 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

t: One-character time marker string, such as A or P

tt: Multiple-character time marker string, such as AM or PM

short

medium

long

full

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) `m`: Minutes; no leading zero for single-digit minutes `mm`: 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 `t`: One-character time marker string, such as A or P `tt`: Multiple-character time marker string, such as AM or PM short medium long full

Usage

When passing a date/time value as a string, you must 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, Macromedia recommends that you use the DateFormat and TimeFormat functions to format date and time values from queries. For more information and examples, see TechNote 22183, "ColdFusion Server (5 and 4.5.x) with Oracle: Formatting Date and Time Query Results," at http://www.coldfusion.com/Support/KnowledgeBase/SearchForm.cfm.

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:mm:ss")#
  <li>#TimeFormat(todayDate, "hh:mm:sst")#
  <li>#TimeFormat(todayDate, "hh:mm:sstt")#
  <li>#TimeFormat(todayDate, "HH:mm:ss")#
</ul>
</cfoutput>  
</body>

Version 6

Comments are no longer accepted for ColdFusion MX. ColdFusion 8 is the current version.

Comments

rbils@amkor.com said on Jun 8, 2002 at 1:00 AM :

What's the difference between the Long and Full masks? I've tried all sorts of times with these two masks, and so far, they always output the same format. If there's no explanation, should this be a bug?

GiskardOlivaw said on Apr 29, 2003 at 5:46 PM :

MX got it right:

4/29/03
Apr 29, 2003
April 29, 2003
Tuesday, April 29, 2003

No screen name said on Aug 24, 2004 at 6:47 AM :

can anyone help with using timeformat and date format together?

Sydneybeachgirl said on Dec 12, 2005 at 4:07 PM :

To format date and time together try using the following functions together on the same date field - just substitute 'mydate' for your CF date variable:
#DATEFORMAT(mydate,'d/m/yyyy')# #TIMEFORMAT(mydate,'hh:mm:ss')#

Works for me :)

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/6/CFML_Reference/functions-pt2105.htm