Description

Formats date and time values using date and time formatting conventions.

Returns

A formatted date and time value.

History

ColdFusion (2016 release) Update 3: The masks t and tt return the character string A/P or AM/PM respectively. Use t or tt instead of the mask a.

ColdFusion 10: Added this function.

Syntax

dateTimeFormat (date)
dateTimeFormat (date [, mask])
dateTimeFormat (date [, mask, timeZone])

Properties

Parameter

Description

date

Required. A date/time object, in the range 100 AD-9999 AD.

mask

 

Optional. Characters that show how ColdFusion displays a date:

  •     d: Day of the month as digits; no leading zero for single-digit days.
  •     dd: Day of the month as digits; leading zero for single-digit days.
  •     EEE: Day of the week as a three-letter abbreviation.
  •     EEEE: Day of the week as its full name.
  •     m: Month as digits; no leading zero for single-digit months.
  •     mm: Month as digits; leading zero for single-digit months.
  •     mmm: Month as a three-letter abbreviation.
  •     mmmm: Month as its full name.
  •     yy: Year as last two digits; leading zero for years less than 10.
  •     yyyy: Year represented by four digits.
  •     YYYY: Week year represented by four digits.
  •     Y: Week year.
  •     YY: Week year as last two digits; leading zero for years less than 10.
  •     G: Period/era string. (e.g. BC, AD)
  •     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
  •     w: Week of the year as digit.
  •     ww: Week of the year as digits. Leading zero for single-digit week.
  •     W: Week of the month as digit.
  •     WW: Week of the month as digits. Leading zero for single-digit week.

The following masks tell how to format the full date and time and cannot be combined with other masks:

  • short: equivalent to m/d/y h:nn tt
  • medium: equivalent to mmm d, yyyy h:mm:ss tt
  • long: medium with full month name rather than abbreviation, followed by three-letter time zone; as in, mmmm d, yyyy h:mm:ss tt EST
  • full: equivalent to EEEE, mmmm d, yyyy h:mm:ss tt EST
The function also follows Java date time mask. For more information, refer to Date and Time Patterns topic in SimpleDateFormat Java API page.

JDK7 and JDK8 introduces the masks, w,ww,W,and WW.

timeZone

The time-zone information. You can specify in either of the following formats:

  • Abbreviation such as GMT or PST
  • Full name such as Europe/Dublin
    By default, this is the time-zone followed by the system.

Example

<cfset todayDateTime = Now()> 
<body> 
<h3>DateTimeFormat Example</h3> 
<p>Today's date and time are <cfoutput>#todayDateTime#</cfoutput>. 
<p>Using DateTimeFormat, we can display that date and time in different ways: 
<cfoutput> 
<ul> 
<li>#DateTimeFormat(todayDateTime)# 
<li>#DateTimeFormat(todayDateTime, "yyyy.MM.dd G 'at' HH:nn:ss z")# 
<li>#DateTimeFormat(todayDateTime, "EEE, MMM d, ''yy")# 
<li>#DateTimeFormat(todayDateTime, "h:nn a")# 
<li>#DateTimeFormat(todayDateTime, "hh 'o''clock' a, zzzz")# 
<li>#DateTimeFormat(todayDateTime, "K:nn a, z")# 
<li>#DateTimeFormat(todayDateTime, "yyyyy.MMMMM.dd GGG hh:nn aaa")# 
<li>#DateTimeFormat(todayDateTime, "EEE, d MMM yyyy HH:nn:ss Z")# 
<li>#DateTimeFormat(todayDateTime, "yyMMddHHnnssZ", "GMT")# 
</ul> 
</cfoutput>

Example with masks w,ww,W,and WW

<cfscript>
  dateTime = createDate(2016,2,1);
  writeOutput(dateTimeFormat(dateTime, "w"));
  writeOutput(' ' & dateTimeFormat(dateTime, "ww"));
  writeOutput(' ' & dateTimeFormat(dateTime, "W"));
  writeOutput(' ' & dateTimeFormat(dateTime, "WW"));
</cfscript>

The code sample above produces the following output:

6 06 1 01

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy