Description

Formats a date value using U.S. date formats. For international date support, use LSDateFormat.

Returns

A text string representing the date formatted according to the mask. If no mask is specified, returns the value in dd-mmm-yy format.

Category

Date and time functions

Function syntax

DateFormat("date" [, "mask" ])

See also

NowCreateDateLSDateFormatLSParseDateTimeLSTimeFormatTimeFormatParseDateTime

History

ColdFusion (2016 release) Update 3: Contains the following changes:

  • You can use both lowercase and uppercase letters as mask characters.
  • The following masks are added:
    • e/E: Day in a week.
    • f/F: Day of a week in a month.
    • k/K: Hour in a day (1-24).
    • w: Week in a month.
    • W: Week in a year.

ColdFusion MX: Added support for the following mask parameter options: short, medium, long, and full.

Parameters

Parameter

Description

date

Date/time object, in the range 100 AD-9999 AD.

mask

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.
  • ddd: Day of the week as a three-letter abbreviation.
  • dddd: Day of the week as its full name.
  • e/E: Day in a week.
  • f/F: Day of a week in a month.
  • 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.
  • k/K: Hour in a day.
  • w: Week in a month.
  • W: Week in a year.
  • yy: Year as last two digits; leading zero for years less than 10.
  • yyyy/YYYY: Year represented by four digits.
  • gg: Period/era string. Ignored. Reserved. The following masks tell how to format the full date and cannot be combined with other masks:
  • short: equivalent to m/d/y
  • medium: equivalent to mmm d, yyyy
  • long: equivalent to mmmm d, yyyy
  • full: equivalent to dddd, mmmm d, yyyy
  • z: Time zone in literal format, for example, IST
  • 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: +5:30

Usage

When passing a date/time object as a string, enclose it in quotation marks. Otherwise, it is interpreted as a numeric representation of a date/time object.

Date and time values in database query results can vary in sequence and formatting unless you use functions to format them. To ensure that application users correctly understand displayed dates and times, Adobe recommends that you use this function and the LSDateFormatTimeFormat, and LSTimeFormat functions to format resultset values.

The DateFormat function is best used for formatting output, not for formatting input. For formatting input, use one of the date/time creation functions (for example, CreateDate) instead.

Example 1

<cfset todayDate = Now()> 
<body> 
<h3>DateFormat Example</h3> 
<p>Today's date is <cfoutput>#todayDate#</cfoutput>. 
<p>Using DateFormat, we can display that date in different ways: 
<cfoutput> 
<ul> 
<li>#DateFormat(todayDate)# 
<li>#DateFormat(todayDate, "mmm-dd-yyyy")# 
<li>#DateFormat(todayDate, "mmmm d, yyyy")# 
<li>#DateFormat(todayDate, "mm/dd/yyyy")# 
<li>#DateFormat(todayDate, "d-mmm-yyyy")# 
<li>#DateFormat(todayDate, "ddd, mmmm dd, yyyy")# 
<li>#DateFormat(todayDate, "short")# 
<li>#DateFormat(todayDate, "medium")# 
<li>#DateFormat(todayDate, "long")# 
<li>#DateFormat(todayDate, "full")# 
</ul> 
</cfoutput>

Example 2: Using masks z, Z, X, XX, and XXX

<cfscript>
    writeoutput(dateFormat(now(), "ddd, mmmm dd, yyyy z")); // Displays Fri, September 16, 2016 IST
    writeoutput(dateFormat(now(), "ddd, mmmm dd, yyyy Z")); // Displays Fri, September 16, 2016 +0530
    writeoutput(dateFormat(now(), "ddd, mmmm dd, yyyy X")); // Displays Fri, September 16, 2016 +05
    writeoutput(dateFormat(now(), "ddd, mmmm dd, yyyy XX")); // Displays Fri, September 16, 2016 +0530
    writeoutput(dateFormat(now(), "ddd, mmmm dd, yyyy XXX")); // Displays Fri, September 16, 2016 +05:30
</cfscript>

Example 3: Using masks as uppercase and lowercase letters

<cfscript>
	writeoutput(DateFormat(now(),"yyyy/mm/dd ABCDEFGHIJKLMNOPQRSTUVWXYYYYZ")); // Displays 2016/09/16 ABC16Fri3AD20IJ8L9NOPQR800TUV3+052016+0530
	writeoutput(DateFormat(now(),"yyyy/mm/dd abcdefghijklmnopqrstuvwxyyz")); // Displays 2016/09/16 abc16Fri3AD8ij20l9nopqr30tuv38x16IST
</cfscript>

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