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

NowCreateDateLSDateFormatLSParseDateTimeLSTimeFormatParseDateTime

History

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:

  • 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.
  • eee/EEE: Day of the week as a three-letter abbreviation.
  • eeee/EEEE: Day of the week as its full name. 
  • 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.
  • M: Month in year.
  • D: Day in year.
  • k/K: Hour in a day.
  • w: Week in a month.
  • W: Week in a year.
  • 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.
  • Y: Week year.
  • YY: Week year as last two digits; leading zero for years less than 10.
  • 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 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

 

Example 2

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

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