Time zones can cause confusion even for super villains. But the Xojo framework has got you covered, whether you are out to do good or evil.

If you’ve written code for long enough, you’ve probably had bugs where you failed to consider some of the differences between two dates.

Consider the following Classic Xojo framework example that adds 3 hours to a specific date:

Dim d As New Date(2017, 11, 5)
d.Hour = d.Hour + 3
MsgBox(Str(d))

Easy enough, right? Unfortunately, while code like this will provide the correct result most of the time, it won’t this time because on November 5th, 2017 here in the United States, Daylight Savings ends. As a result, the value return will be off by an hour.

API 2.0 solves this problem by introducing the DateTime and DateInterval classes which is used to add or subtract time and takes into account time zones:

Var d As New DateTime(2017, 11, 5, 0, 0, 0, 0, TimeZone.Current)
Var di As New DateInterval(0, 0, 0, 3)
d = d + di
MessageBox(d.ToString)

This example creates a new date and provides the current time zone then creates a DateInterval and assigns it 3 hours. The DateInterval is then added to the date and the result displayed. This code will always be correct because time zones are being considered. This one is pretty straightforward because it’s only dealing with US Daylight Savings Time but imagine if one date was tied to someone in the US and another to someone in Europe. Not only do you have different time zones but Daylight Savings Time starts and stops on different dates between the US and Europe. The new DateTime and DateInterval classes in API 2.0 handle all of that complexity for you. Because the new DateTime class understands time zones, using TimeZone.Current for example, means you don’t even have to think about it at all. Your calculations will just work no matter where the user is in the world.

The API 2.0 solution requires one extra line of code. However, that one extra line gets you code that will always produce the correct result. The Date class in the Classic Xojo framework will be right most of the time but when it’s wrong, you may wrack your brain for a while trying to figure out why. That extra line of code is worth every keystroke.

This example deals only with time zones but the DateTime and DateInterval classes also handle leap years for you as well. That’s another example where it would be very easy to miss the fact that a leap year occurred and get the wrong result.

The changes to date and time handling in API 2.0 are just a few examples of why we have created it and why it’s worth your time to start using it.

Note: This post was updated for API 2.0 on June 15th, 2020.

Use the new Framework, Luke

The Xojo.Core.Date and Xojo.Core.DateInterval classes under the new, Xojo framework make it really easy to get the difference between two given dates. The code you’ll need for this is as easy as this:

Using Xojo.Core
Dim dateA As date = New Date(2017,10,23, TimeZone.current)
Dim dateB As date = New Date(2017,11,23, TimeZone.Current)
Dim result As DateInterval = dateB - dateA
MsgBox result.Years.ToText+ " " + result.Months.ToText + " " + result.Days.ToText

The key here is in the use of the subtract operator that gives as result a TimeInterval instance. Thus, accessing the properties of this instance will get the years, months and days elapsed between the two compared dates. Take into account the importance of the order of your Date operands when used with the subtract operator. I mean, if the rightmost date is higher than the leftmost date, then probably you will get some negative values for the properties. In some cases, this will be the expected behaviour for the logic of your app… other times, you will prefer to check this before getting the DateInterval instance in order to get proper values.

Date difference for existing code

But, what if you want to get the same function for your current code based on the date class? Here you can opt for several options. The one we are going to put in practice is based in the use of the Xojo Module in combination with the Class Extension OOP feature. In fact, Class Extension is the way we can extend the functionallity of an existing Class. Straight, right? So, in order to achieve this the first step, add a new Module to a Xojo project and name it using the Inspector Panel (for example, “Extents”). Then, select the newly created module and add a new Method to it using the following signature:

• Method Name: Difference
• Parameters: Extends d As Date, RightDate As Date
• Return Type: Dictionary

Next, we will add some text constants to the Module, that will be used by the Method and help any calling code that wants to access the result.

• kDay As String = Day
• kDay As String = Month
• kYear As String = Year

Afterwards, select the Difference method and type the following lines of code in the resulting Code Editor:

Dim difference As Double = RightDate.TotalSeconds - d.TotalSeconds
Dim days As Integer
Dim years As Integer
Dim months As Integer
Dim dateResult As New date
dateResult.TotalSeconds = difference
days = dateResult.Day - 1
years = dateResult.Year - 1904
months = dateResult.Month - 1
Dim result As New Dictionary
result.Value(kDay) = days
result.Value(kYear) = years
result.Value(kMonth) = months
Return result

As you can see, the code is simple enough. In order to simplify the code to a maximum, this example opts to give the result as an Instance of Dictionary and using the previously definied constant to store the “Year”, “Months” and “Days” of difference between the compared dates. If you want, you can use an additional Structure or Class to return the result (your own DateInterval?).

To test the new Class Extension, add an Open Event to the Window or App object of your project and type this lines of code:

Dim d As New date(2017,10,24)
Dim d1 As New date(2017,11,30)
Dim interval As Dictionary = d.Difference(d1)
MsgBox interval.Value(kYear) + " " + interval.Value(kMonth) + " " + interval.value(kDay)

A new Date Class that makes the Difference

There is a third option that we can explore that is more OOP oriented: create our own Date class and implement the subtract operator on it. More or less the thing that we do when using Xojo.Core.Date.

For that, the first step is adding a new class to a Xojo Project (Insert > Class). Use the following data in the Inspector Panel:

• Name: MyDateClass
• Super: Date

Next, add to the class the same constant we defined in the previous section (kDay, kMonth and kYear). These will be used to define the keys in the resulting dictionary and to ease operations from the calling code too.

The most important thing is adding a new Method to our class with the following data:

• Method Name: Operator_Subtract
• Parameters: rightMostDate as Date
• Return Type: Dictionary

The Operator_Subtract method instructs the Xojo compiler so you can use the minus sign (-) between two instances of the class. Type these lines of code for the method:

Dim difference As Double = self.TotalSeconds - rightMostDate.TotalSeconds

Dim days As Integer
Dim years As Integer
Dim months As Integer

Dim dateResult As New date

dateResult.TotalSeconds = difference

days = dateResult.Day - 1
years = dateResult.Year - 1904
months = dateResult.Month - 1

Dim result As New Dictionary

result.Value(kDay) = days
result.Value(kYear) = years
result.Value(kMonth) = months

Return result

Then in the Open Event of a Window, or the App object, check the class with the following code:

Dim d2 As New MyDateClass(2017,10,24)
Dim d3 As New MyDateClass(2017,11,30)

interval = d3 - d2

MsgBox interval.Value(kYear) + " " + interval.Value(kMonth) + " " + interval.value(kDay)

Javier Rodri­guez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has be using Xojo since 1998. He manages AprendeXojo.com and is the developer behind the GuancheMOS plug-in for Xojo Developers and the Snippery app, among others.

*Read this post in Spanish

First, remember the old Date class remains available for desktop/web/console projects.

In this post I’m specifically talking abou the new Xojo.Core.Date class. The big change is that Xojo.Core.Date is now immutable. With the old Date class, if you changed Date properties in the “wrong” order, such as set Day to 31 before setting Month to 9 then unexpected things start to happen. It also caused problems with things like FolderItem.ModificationDate (for example) because you might think you could actually change the modification date by directly changing its Date properties, but that doesn’t actually work.

So Xojo.Core.Date is immutable. You get a new Date by using one of the Constructors. If you need the current date, you use Date.Now. And with this we’ve added the companion DateInterval and TimeZone classes to make it easy to do math on Dates and to convert a date/time to a different time zone.

In particular, you can now do arithmetic on Dates. For example, if you want to get the Date that is two months earlier than now, you can create a DateInterval and subtract it from the Date:

Dim twoMonths As New DateInterval
twoMonths.Month = 2 // 2 month interval

// Get date two months before today
Dim past As Date = Date.Now - twoMonths

Or if you want to know the the interval until Jan 1, 2030:

Dim d2 As New Date(2030, 1, 1, TimeZone.Current)
Dim interval As DateIntervalinterval = d2 - Date.Now

Need to convert the current date/time to GMT? Try this:

Dim GMTZone As New TimeZone("GMT")
Dim GMTDate As New Date(Date.Now.SecondsFrom1970, GMTZone)

You can use Xojo.Core.Date in all project types (Desktop, Web, Console and iOS).

Update (June 2020):

Since this was written, the DateTime class was added as part of API 2.0.