Date Objects vs Date Strings in ColdFusion

To use dates effectively in ColdFusion it is important to understand when you are dealing with dates represented internally as Strings and when you are dealing with dates represented internally as date Objects.

This is particularly important when dealing with non US dates formats.

So how do you know when you are using a date string or using a date object?

Some examples of dates stored within ColdFusion as strings

1) Dates submitted as form data

2) Dates constructed by joining strings together in an application. For example:

<cfset myDate = day & "/" & month & "/" & year>

3) Dates hardcoded in an application. For example:

<cfset myDate = "1/2/2007">

4) Dates read from text fields in a database

When you <cfoutput> a date string on the screen it looks identical to the original string:

So the code:

<cfset myDate = "23/10/2006">
<cfoutput>#myDate#</cfoutput>

simply displays:
23/10/2007
23/10/2006

Some examples of dates stored within ColdFusion as actual Date objects

1) Dates returned by most of the date functions are date objects. These include:
now()
createDate()
createDateTime()
parseDateTime()
lsParseDateTime()

2) Dates read from date or timestamp type fields in a database

When you display a date object on the screen it displays a representation of the date. For example, the code:

<cfset myDate = now()>
<cfoutput>#myDate#</cfoutput>

Displays something like:
{ts ’2006-10-23 20:17:35′}

Now you know you’re dealing with a real date object when you see something like this.

Remember that this is just a visual representation of the date. It is not really stored internally as a string starting with "{ts" inside ColdFusion.

How does ColdFusion work with dates?

Whenever you need to perform any kind of date operation, ColdFusion first ensures you are working with a real date object, and not a string.

If you have a date string, then ColdFusion will silently convert the string to date object and then perform the operation.

ColdFusion’s silent confusion with string to date conversions

OK, so if you are dealing with strings then ColdFusion silently converts them to dates:

Consider the following code:

<cfset d1 = "2/3/2007">
<cfset d2 = "13/3/2007">
<cfoutput>
#month(d1)#<br>
#month(d2)#<br>
</cfoutput>

The result here is:

2

3

So, for the first date, ColdFusion assumes the date is in US m/d/y format. For the second date, this assumption does not work (no such thing as month 13) so it next guesses that the date is in d/m/y format instead.

Always perform date parsing on your date strings

Whenever you need to work with dates always convert them to date objects before you do anything else.

This primarily affects code that deals with non US dates, so you should

1) Ensure you have set the correct locale using setLocale()

2) Use lsParseDateTime() on your date strings

So rather than having code such as:

<cfset d1 = "2/3/2007">
<cfset d2 = "13/3/2007">
<cfoutput>
#month(d1)#<br>
#month(d2)#<br>
</cfoutput>

You should use always use code such as

<cfset d1 = lsParseDateTime("2/3/2007")>
<cfset d2 = lsParseDateTime("13/3/2007")>
<cfoutput>
#month(d1)#<br>
#month(d2)#<br>
</cfoutput>

Which, here in Australia, correctly displays:

3

3