A library for the creation and analysis of simple to complex temporal relationships. Use cases include scheduling, date calcuations, and time based relationship analysis. The initial concept is based off of Martin Fowlers Recurring Events for Calendars paper, but has since evolved a bit.

All classes in this library extend off of the TExpression base class which also provides some of the basic functionality common to all Temporal Expressions (TE's). There are two categories of TE's in the library. The first are complex TE's (TEIs, TEIsAfter, TEIsBefore, TEInRange) which implement factory constructors that generate a TE based on the type of data being tracked. Second are the compounding TE's which take other TE's as inputs and combine them together in some way (TEDiff, TEIntersect, TEUnion, TENot). Both categories of TE's have the same basic functionality.

An example use case follows:

Introduction

So, what exactly does this library do you say? Why would I ever want to use it? I will answer the second first, you probably will not, especially after you look at the code behind it. But I needed something like it for a quick project, and figured I might as well share it so that somebody who knows what they are doing can make it better.

The answer to the first question is a little easier. There are times when a programmer needs to represent complex recurring events in code. We will go through a fairly complex example in this short article, which should demonstrate how to use the library.

The example scenario

You and your Significant Other (called SO from here on out) have decided to purchase a timeshare rental in a Park City condominium. At the time of purchase you were told that you would have unlimited access to the time-share during the months of June through December, every year. You would like to represent this as a Temporal Expression (TE) in Dart.

Fortunately the dartemporal library provides an easy way to represent this.

// Months when the timeshare was available
TEInRange availableMonths = new TEInRange.Month(DateTime.JUNE, DateTime.DECEMBER);

You being the proud programmer that you are, drag your SO to your terminal so he/she can see your master wizardry. Unfortunately, SO quickly reminds you that your work schedule never allows you to be absent on a Monday or Tuesday. If only there were a way to model this more complex situation as well. Not to fear, dartemporal to the rescue!

// Months when the timeshare was available
TEInRange availableMonths = new TEInRange.Month(DateTime.JUNE, DateTime.DECEMBER);

// Days when you are able to leave work
TEInRange yourAvailability = new TEInRange.DayOfWeek(DateTime.WEDNESDAY, DateTime.SUNDAY);

Now, if only there were a way to combine these together so we only have one thing to work with. Again, dartemporal does not disappoint and provides you an easy way to combine them together using TEIntersect (Logical AND.)

// Months when the timeshare was available
TEInRange availableMonths = new TEInRange.Month(DateTime.JUNE, DateTime.DECEMBER);

// Days when you are able to leave work
TEInRange yourAvailability = new TEInRange.DayOfWeek(DateTime.WEDNESDAY, DateTime.SUNDAY);

// Combine these together to make my life easy
TEIntersect condoSchedule = new TEIntersect([availableMonths, yourAvailability]);

With this taken care of, you excitedly drag SO back to your computer, only to be dejected again when SO reminds you that his/her schedule will not allow participation after the 15th of the month. You guessed it dartemporal can again help.

// Months when the timeshare was available
TEInRange availableMonths = new TEInRange.Month(DateTime.JUNE, DateTime.DECEMBER);

// Days when you are able to leave work
TEInRange yourAvailability = new TEInRange.DayOfWeek(DateTime.WEDNESDAY, DateTime.SUNDAY);

// Days when SO is able to leave work
TEBefore soAvailability = new TEBefore.DayOfMonth(15));

// Combine these together to make my life easy 
// (This is now June-December, on Wed-Sun before the 16th of the month.
TEIntersect condoSchedule = new TEIntersect([availableMonths, yourAvailability, soAvailability]);

So what?

SO being the trouble maker that SO is, then asks, so that is pretty abstract, how will that help us figure out when we can go on vacation? You being the genius you are quickly add the following line to your code:

// These can be inline, but are broken out for clarity in the example code
DateTime baseDate = new DateTime(2013, 4, 1, 0, 0, 0, 0);
Duration interval = new Duration(days:1);

condoSchedule.dates(baseDate, interval);
// RETURNS: [(Jun-05-2013), (Jun-06-2013), (Jun-07-2013), (Jun-08-2013), (Jun-09-2013),
//           (Jun-12-2013), (Jun-13-2013), (Jun-14-2013), (Jun-15-2013), (Jul-03-2013)]
// Dates are actually returned as DateTime objects, but shown this way for illustrative purposes

Notice in the result above that even though we asked the TE for dates starting in April, our first result is not until June as per our requirements. Also note that all dates fall on a Wed, Thurs, Fri, Sat, or Sun. Finally note the last entry is not until July because of the requirement that your SO is only available until the 15th of each month.

It seems that the TE representing your Condo availability is working swimmingly.

What else can we do with it?