You need to create a date/time object.

You can write the date/time value as a string, or use the CreateDate(), CreateTime(), CreateDateTime(), or CreateODBCDate() function depending on your specific needs.

Internally, ColdFusion stores dates and times as real numbers. The date is stored as the integer part of the number, and the time is stored as the fractional part. 0 represents 12:00 am on 12/30/1899. 7:00 pm on 12/31/2002 would be 37621.79167. The whole part of the number represents 37621 days since 12/30/1899 while .79167, or 7 pm is obtained by dividing the hour (19) by the total number of hours in a day (24). Storing dates in this manner allows ColdFusion to quickly and efficiently store and manipulate dates and times.

From a human readability standpoint, this format isn't very friendly. Because of this, ColdFusion allows you to refer to date/time objects as strings. You can specify dates and times separately, or combined. Dates must be in the range 100 AD to 9999 AD and can be written as:

12/31/02

12/31/2002

12-31-2002

2002-12-31

December 31, 2002

Dec 31, 2002

{ts '2002-12-31 00:00:00'}

ColdFusion handles two-digit years from 00 to 29 as twenty-first century dates and two digit years from 30 to 99 as twentieth-century dates.

Times are accurate to the second and can be written as:

7pm

7:00p

7:00pm

07:00pm

19:00:00

{ts '1899-12-30 19:00:00'}

Combined date/time objects can be written as any combination of the above. For example, a combined ODBC formatted date/time object looks like this:

{ts '2002-04-01 21:51:50'}

Date/Time values can be assigned to variables using and :

<cfset x="12/31/2002">
<cfparam name="x" default="12/31/2002">

They can also be coded directly in tag attributes and function parameters:

<cfcookie name="ID" value="12" expires="12/31/2002">
or
<cfset x = dateFormat("12/31/2002")>

While this may seem like an easy way to create dates, it can be problematic if you ever need to represent your dates in a locale other than English (US). The main problem has to do with the month and day portion of the date. In the U.S., dates are usually written mm-dd--yyyy. The month is first, followed by the day, then the year. In many other locales, the month and day parts of the date are reversed. Because of this, it is recommended you always use the CreateDate(), CreateTime(), or CreateDateTime() functions to create date/time objects. These functions can be used in any locale and will ensure that the dates and times you create can be used with any locale.

To create a date object, use CreateDate():

<cfset x = createDate(2002,12,31)>
<cfoutput>#x#</cfoutput>

The function requires three parameters, the year, the month, and the day. This removes any ambiguity regarding the position and value of the day and month portions of the date object.

Likewise, you can create a time object using CreateTime():

<cfset x=CreateTime(19,0,0)>
<cfoutput>#x#</cfoutput>

CreateTime() requires you to pass the hour (using the 24-hour clock), minute, and second.

To create a combined date/time object, use CreateDateTime():

<cfset x=CreateDateTime(2002,12,31,7,0,0)>
<cfoutput>#x#</cfoutput>

This function requires you to specify the year, month, day, hour (24-hour clock), minute, and second for the date/time object you want to create.

This question was written by Rob Brooks-Bilson
It was last updated on January 6, 2006.

Categories

Dates/Times

Comments

comments powered by Disqus