VB.NET Class Library: Date Wizard

• Download demo project (includes three DLLs in the BIN folder*) - 55.7 KB
• Download class library DLL - 11.2 KB
• Download class library source code - 20.2 KB

* There are two DLLs in the demo project's BIN folder: 2gs_datetextbox.dll and 2gs_extendedtextbox.dll. Click here to read about these user controls.

Demo project

Contents

• Introduction
• Background
• Terminology
• Using the Class Library
• Date Wizard Class
  • Constructors
  • Methods
  • Properties
• Methods in the DateFunctions Class
• Points of Interest
  • Fiscal Year
  • Internal Dates
• Conclusion
• Licensing and Limitation of Liability
• History

Introduction

Dates are strange beasts that do not lend themselves well to being handled in code. I'm probably preaching to the choir with that bold statement; however, if your experience is anything like mine, you've had to include dates in your applications often and doing any but the simplest tasks with dates has been challenging. The Date Wizard class library is intended to be a toolkit that simplifies many date-related tasks. The Date Wizard class library (2gs_datewizard.dll) houses three classes.

• C_DateWizard: used to instantiate a date object. This class has nine constructors and exposes thirteen methods and forty three properties.
• C_DateFunctions: exposes eighteen standalone methods.
• C_DateInterval: used to return the calculation results from the C_DateFunctions CalcDateInterval method.

The demo project is designed to illustrate the constructor options, methods and properties in both the date wizard and function classes. In the demo main window (shown above), you instantiate a date object using any of the nine constructor options. With a date object instantiated, you can click on the Properties button to see the values for all of the properties as well as change the first month in the object's fiscal year. The Methods button opens a window in which you can modify the date object's base date using any one of twelve methods. The only method that is not illustrated is ResetTimestamp.

The Date Functions button, which is available with or without a date object instantiated, opens another window that demonstrates the three date function methods that are not used either in the C_DateWizard class or the demo project. In this window, you can calculate the interval between two dates (years, months, weeks, and days), check if two date ranges overlap, and test whether or not a date lies within a date range. If you click on the Overlap and In Range buttons with none or only some of the dates filled in, you can see that these two methods do not require dates for any of their parameters.

Background

I developed my first date wizard class in VB 6, with the intention of simplifying dates. That early date wizard, still available for download from my website, has proven to be popular. The date wizard offered with this article is the .NET successor of my original VB 6 class. This new date wizard has proven to be even more useful because it is locale aware. Dates are formatted as per the region settings in the operating system.

Terminology

An important term you will find in this article is "base date." When a C_DateWizard object is instantiated, the primary property of that object is, of course, the object's date. This is referred to as the base date. Eight of the C_DateWizard property names start with "Base" to differentiate these properties from similar date properties in Visual Studio.

Using the Class Library

Follow these steps to make the 2gs_datewizard class library available in a project:

1. Copy the DLL (2gs_datewizard.dll) to the project's BIN folder.
2. In the VS Solution Explorer, add the DLL to the project's References.

At the top of each class and module in which either the C_DateWizard or C_DateFunctions classes are consumed, add this statement:

Imports _2gs_datewizard

There are a plethora of examples in the demo project for consuming both the C_DateWizard and C_DateFunctions classes. Here is a sample from the Methods form. This is what happens when the Calc button is clicked. In this process, the DateStringOK and CalcDateInterval methods in the C_DateFunctions class are invoked. This code also demonstrates the use of the C_DateInterval class:

Private Sub btnCalc_Click(ByVal sender As System.Object, _
                             ByVal e As System.EventArgs) _
                             Handles btnCalc.Click
    '--------------------------------------------------------------


    '     Date          Developer                      Code Change


    '  ---------- -------------------- ----------------------------


    '  03/21/2006 G Gilbert            Original code


    '--------------------------------------------------------------



    '--------------------------------------------------------------


    ' The From date is required and must be a valid date


    '--------------------------------------------------------------


    Dim df As New C_DateFunctions
    If Not df.DateStringOK(uctlFromDate.TextBox_Text, "From") Then
        uctlFromDate.Focus()
        df = Nothing
        Exit Sub
    End If

    '--------------------------------------------------------------


    ' The Through date is required and must be a valid date


    '--------------------------------------------------------------


    If Not df.DateStringOK(uctlThroughDate.TextBox_Text, "Through") Then
        uctlThroughDate.Focus()
        df = Nothing
        Exit Sub
    End If

    '---------------------------------------------------------------


    ' Calculate the interval


    '---------------------------------------------------------------


    Dim di As New C_DateInterval
    di = df.CalcDateInterval(CType(uctlFromDate.TextBox_Text, Date), _
                             CType(uctlThroughDate.TextBox_Text, Date))
    df = Nothing

    '---------------------------------------------------------------


    ' Display the results and place the focus


    '---------------------------------------------------------------


    With di
        lblYears.Text = .Years.ToString
        lblMonths.Text = .Months.ToString
        lblWeeks.Text = .Weeks.ToString
        lblDays.Text = .Days.ToString
    End With
    di = Nothing
    uctlFromDate.Focus()
End Sub

Date Wizard Class

Constructors

The C_DateWizard class affords nine constructor options. With the exception of the basic constructor which has no parameters, instantiating a date object with invalid parameters results in the base date defaulting to the current system date. You can find out whether or not the base date for a date object defaulted to the current date by querying the UsedDefaultDate property.

Dim dw As New C_DateWizard(1, 3, 2, 2005)
          '                 .  .  .   .


          'January   ........  .  .   .


          '3rd       ...........  .   .


          'Tuesday   ..............   .


          'Year      ..................

Methods

The C_DateWizard class exposes thirteen methods. They are listed here in alphabetical order:

Properties

The C_DateWizard class exposes forty-three properties. They are listed here in alphabetical order:

Methods in the DateFunctions Class

The C_DateFunctions class exposes eighteen stand-alone methods that are not appropriate for including in the C_DateWizard class. Most of these methods are consumed in the C_DateWizard class. All of the methods are listed here alphabetically:

Points of Interest

Fiscal Year

Two of the properties maintained in the C_DateWizard class are the month and year for the twelve months that comprise the fiscal year that contains the base date. When a date object is instantiated, the fiscal year defaults to January through December, with each month being in the same year as the base date. The fiscal year can be changed with the FirstFiscalMonth property. When the first fiscal month is changed to something other than January, the fiscal year is adjusted so that it always contains the base date.

For example, let's say you instantiate a date object with a base date in July, 2006. Then you set FirstFiscalMonth to September. The new fiscal year will be from September, 2005 through August, 2006. If, in this example, the first fiscal month were set to April, the new fiscal year would be from April, 2006 to March, 2007.

You can permanently change the default fiscal year in your copy of the date wizard. In the Members/Variables region of the C_DateWizard class, change the initial value of intDefaultFiscalFirstMonth to the number of whichever month you want to be the first month in the default fiscal year:

#Region " ... Variables "
    Private intDefaultFirstFiscalMonth As Integer = 1
#End Region

Internal Dates

When testing an application that stores dates in text files, I changed the operating system region settings to ensure that all dates would be displayed correctly in the user interface. An exception occurred because the format of the dates being read from the text files no longer agreed with the region date format. This test brought home to me the importance of insuring that dates stored and transmitted between applications in text files (e.g. XML) must be in a format that is independent of the region settings in any recipient's machine. The DateToInternal and InternalToDate methods in the C_DateFunctions class are used to create a storable date string that is independent of the operating system region settings. As per the standard set by Microsoft, this independent, internal date format is #mm/dd/yyyy#.

The intent of the DateToInternal and InternalToDate methods is only the storage and retrieval of date strings in text files. Their use is, therefore, very limited. I use these methods only when building a string to be written to a text file, and when interpreting that string when read from the file. This technique isolates the internally formatted dates from the rest of the program code while ensuring that the dates read from text files will be handled correctly, regardless of the region settings.

Conclusion

My current project depends heavily on dates; ergo, my motivation for putting together this .NET version of my date wizard. I do not yet have a need for all of the methods and properties exposed by the C_DateWizard and C_DateFunctions classes. However, I wanted this date toolkit to be as complete as possible before writing this article. Since much of the functionality in these classes was written without a current need for that functionality, there is a possibility I forgot something. If you see any functionality that I missed, please let me know.

Licensing and Limitation of Liability

You may use all code offered in this article in any way you choose without restriction.

Under no circumstances, and under no legal theory, tort, contract, or otherwise, will George Gilbert (hereafter referred to as "software author") or his licensors, be liable to the user of the Double Text library and all code offered in this article (hereafter referred to collectively as "article code") for any damages, including any lost profits, lost data, or other indirect, special, incidental, or consequential damages, arising out of the use or inability to use the article code, and data or information supplied, even if the software author, his licensors, or authorized dealer have been advised of the possibility of such damages, or for any claim by any other party.

History

• 3/28/2006
  • The return of calculation results from the C_DateFunctions CalcDateInterval method has been converted from by-reference parameters to the C_DateInterval class.

• 4/5/2006
  • The SetLastWeekdayInMonth method has been added to the C_DateWizard class. This new method changes the date wizard object's base date to the last occurrence in the base month of the weekday number passed to the method.
  • The SetOrdinalWeekAndDay method in the C_DateWizard class, in addition to week numbers 1-4, now accepts week number 5. The 5th occurrence of a weekday is interpreted as the last occurrence of the weekday number in the month, regardless of how many times the weekday occurs within the month.

• 8/20/2007
  • Added the BaseWorkdayInMonth property to the C_DateWizard class. This new property returns the number of workdays in the month (excluding Saturday and Sunday) between the 1st and the base date. If the base date is not a workday, -1 is returned.
  • Modified the NthDayInMonth method in the C_DateFunctions class. The method now accepts an ordinal week number in the range 1-5, with 5 interpreted as the last weekday in the month.