Working with date/time patterns

• Download source - 83.2 KB

Introduction

Everyone knows the * and ? wildcards when working with filenames on the shell. But wildcards could also be very useful when working with date and time quantities. I won't talk about regular expressions matching date or time strings here (but they are used in the Parse method) rather, I will show you a tool class which allows it to specify a pattern for matching existing DateTime instances and for calculating such matching DateTimes from a given start date.

Using the code

If you have ever worked with the Unix Crontab you will know what I'm talking about. For example, you can specify a date/time pattern which matches every 1st of a month in the year 2007 and every full 10 minutes and starting at second 0 this way:

// DatePattern: 2007.**.01 **:10.00

DateTools.DateTimePattern DateTemplate = 
    new DateTools.DateTimePattern( 2007, null, 01, null, 10, 00 );

Setting a part of the pattern (Day, Month etc.) to null means match everything. Now you are able to check a DateTime instance against this pattern to see if it will match:

DateTime d = new DateTime( 2007, 03, 01, 00, 02, 00 ); 
// 2007.03.01 00:02.00

if ( DateTemplate.DateMatchesTemplate ( d ) )
{
    .......

So far this is a nice functionality but nothing very special. The function GetNextPossibleDate of the DateTools assembly is far more interesting. This function allows it to find the next matching date starting from a given date or from DateTime.Now. This sounds like a very simple problem to solve but in fact it is not as simple as it sounds. So given the pattern ****.**.15 **:**.00 which matches every start of a minute, of any minute and hour, of the 15th of any month, year, and a starting date of 1990.02.27 13:42.00. The next matching date could be found with:

// DatePattern: ****.**.15 **:**.00
// StartDate:   1990.02.27 13:42.00
// NextMatch:   1990.03.15 00:00.00

DateTemplate = new DateTools.DateTimePattern(null,null,15,null,null,42);

DateTime d = DateTemplate.GetNextPossibleDate( new DateTime( 1990, 02, 27, 
    13, 42, 00 ) );

The next matching date will be: 1990.03.15 00:00. If there is no possible match after (including the given date) then the last possible matching date will be returned. This function if very handy when implementing Unix Cron-like functionality into your applications.

DatePattern.ToString() returns a string representation of the pattern where each part of the date and time which is null will be represented as *. DateTimePattern.Parse(string) can convert these strings back into a DateTimePattern instance.

Using the code is fairly simple. Just include a reference to the DateTools assembly and a using statement into your project or just include the DateTools.cs source file into your own project.

Building and Testing the demo project

The demo project uses NUnit with some test cases so you need NUint installed. Also when doing a Release build you need Microsoft Sandcastle which creates a chm help file for the DateTools assembly. For a Debug build Sandcastle is not necessary.

Points of Interest

As simple as this project may seem at first it has some interesting aspects:

• Calculating the next date which matches a given template can be quite tricky
• This project can be used as an example on how to use NUnit
• Microsoft's Sandcastle for creating help files can also be a little tricky and so this project may help using it.

History

2007.03.31 First release