View comments | RSS feed

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:mm tt format. For international time formatting, see LSTimeFormat.

Category

Date and time functions, Display and formatting functions

Function syntax

TimeFormat(time [, mask ])

See also

CreateTime, Now, ParseDateTime, LSTimeFormat, DateFormat

History

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

ColdFusion MX:

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
  • l or L: milliseconds. l gives 3 digits. L gives 2 digits.
  • 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

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 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>   
<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:mm:ss")
produces:</p>
<cfoutput>#dateformat(now(), "yyyy-mm-dd")#T#TimeFormat(now(), "HH:mm:ss")#</cfoutput>
</body>

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | KnowledgeBase | Bug Reporting

Version 7

Comments


No screen name said on Jan 18, 2007 at 6:09 AM :
the milliseconds mask l or L doesn't work correctly.

both give the same result and not the (l:3 digit L:2 digit)

Infact both return 3:digit unless the number has a trailing 0 in which case they both return 2:digit.
digicidal said on May 17, 2007 at 5:47 PM :
I think this is a bug in the documentation (referring to the two digit milliseconds) - since a two digit number would be very confusing in describing 1000th's of a second. Milliseconds should always be displayed as a 3 digit number unless it has a LEADING zero. I believe the previous poster said TRAILING and a trailing zero should definitely be included in the number.
halL said on May 18, 2007 at 1:25 PM :
The documentation is incorrect.
Both l and L have the same effect:
You get a variable-length number of milliseconds, with no leading zeros.

 

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

Current page: http://livedocs.adobe.com/coldfusion/7/htmldocs/00000651.htm