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
Function syntax
DateFormat(date [, mask])
See also
Now, CreateDate, LSDateFormat, LSParseDateTime, LSTimeFormat, ParseDateTime
History
ColdFusion (2021 release) Update 1: We've fixed the issue with mask in the function. For more information, see the bug. We recommend updating to Update 1.
ColdFusion (2021 release): Added a JVM flag -Dcoldfusion.datemask.useDasdayofmonth. It defaults to false but when set to true and the mask contains D (uppercase D), the mask treats the value as d (lowercase d), day of the month. Hence, dateformat(now(), "mm-D-yyyy") is the same as dateformat(now(), "mm-d-yyyy") when flag is set to true. By default Capital D is used to specify Day of the year. See example below.
ColdFusion (2018 release) Update 3. ColdFusion (2016 release) Update 10, and ColdFusion 11 Update 18: Input formats "m/d" or "d/m", where masks m as month and d as date with valid month/day numerals are no more considered as valid date input. For example, see Example 2.
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 of the year as digit .
- ww : Week of the year as digits. Leading zero for single-digit week.
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:
|
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 LSDateFormat 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
<cfscript>
Date1 = "{ts '2018-11-15 12:13:50'}";
dateformat= DateFormat(Date1)
dateformat1= DateFormat(Date1,"e")
dateformat2= DateFormat(Date1,"f")
dateformat3= DateFormat(Date1,"k")
dateformat4= DateFormat(Date1,"w")
dateformat5= DateFormat(Date1,"ww")
writeOutput("date is : " & dateformat & "<br/>")
writeOutput("day in a week is : " & dateformat1 & "<br/>")
writeOutput("day of a week in a month : " & dateformat2 & "<br/>")
writeOutput("hour in a day: " & dateformat3 & "<br/>")
writeOutput("week of the year as a digit: " & dateformat4 & "<br/>")
writeOutput("Week of the year as digits. Leading zero for single-digit week. : " & dateformat5 & "<br/>")
</cfscript>
Output
date is : 15-Nov-18
day in a week is : Thu
day of a week in a month : 3
hour in a day: 12
week of the year as a digit: 46
Week of the year as digits. Leading zero for single-digit week. : 46
<cfscript>
writeOutput("The date is: " & DateFormat('04/10/2019','mm-dd'))
</cfscript>
The code above runs as expected and produces the following output:
The date is: 04-10
However, the code below throws an exception since the input date is in an incorrect format.
<cfscript>
// This snippet throws an exception
writeOutput("The date is: " & DateFormat('04/10','mm-dd'))
</cfscript>
<cfscript>
writeOutput(dateformat(now(), "mm-D-yyyy") & "<br/>")
writeOutput(dateformat(now(), "mm-d-yyyy") & "<br/>")
</cfscript>