Operators for System.DateTime, continued from Part 3

In this article I shall continue to deal with operators, but those specifically which will allow assignment of System.DateTime values and System.Data.SqlTypes.SqlDateTime values to the DateTimeNull object or vice-versa.

#Region "Operators for System.DateTime"

    ''' <summary>
    ''' Converts a System.DateTime structure to a DateTimeNull object.
    ''' </summary>
    ''' <param name="value">A DateTime structure. </param>
    ''' <returns>A DateTimeNull object whose Value is equal to the combined Date and TimeOfDay properties of the supplied System.DateTime structure.</returns>
    Public Shared Widening Operator CType(ByVal value As System.DateTime) As DateTimeNull
        Return New DateTimeNull(value)
    End Operator

    ''' <summary>
    ''' Converts a DateTimeNull object to a System.DateTime structure.
    ''' </summary>
    ''' <param name="value">a DateTimeNull</param>
    ''' <returns>A System.DateTime structure whose Value is equal to the combined Date and TimeOfDay properties of the supplied DateTimeNull object.</returns>
    Public Shared Widening Operator CType(ByVal value As DateTimeNull) As System.DateTime
        If value.HasValue Then
            Return value.InternalDate
        Else
            Throw New InvalidCastException("Cannot convert Null DateTimeNull to System.DatetTime.")
        End If
    End Operator

#End Region

These two widening operators allow us to write the following code without compile errors:

Dim nullableDate As DateTimeNull = Nothing
Dim systemDate As System.DateTime

nullableDate = systemDate
systemDate = nullableDate

The first widening operator lets us cast from a System.DateTime to our DateTimeNull object, and the second one back again. Even with these two operators we cant yet do comparison checks between the two types. The code below will not compile.

If nullableDate = systemDate Then
End If
If systemDate = nullableDate Then
End If

For that to happen we need to add an equality operators. The code below will allow the first equality check to compile. Please note for every "equals" operator, you must provide a "not equals" operator too.

    ''' <summary>
    ''' Determines whether one specified DateTimeNull is equal to another specified DateTime.
    ''' </summary>
    ''' <param name="d1">A DateTimeNull.</param>
    ''' <param name="d2">A System.DateTime.</param>
    ''' <returns><c>true</c> if d1 is not null and d1 is equal to d2; otherwise, false.</returns>
    Public Shared Operator =(ByVal d1 As DateTimeNull, ByVal d2 As System.DateTime) As Boolean
        If d1.HasValue Then
            Return (d1.InternalDate = d2)
        Else
            Return False
        End If
    End Operator

    ''' <summary>
    ''' Determines whether one specified DateTimeNull is not equal to another specified DateTime.
    ''' </summary>
    ''' <param name="d1">A DateTimeNull.</param>
    ''' <param name="d2">A System.DateTime.</param>
    ''' <returns><c>true</c> if d1 is not null and d1 is not equal to d2; otherwise, false.</returns>
    Public Shared Operator <>(ByVal d1 As DateTimeNull, ByVal d2 As System.DateTime) As Boolean
        If d1.HasValue Then
            Return Not (d1.InternalDate = d2)
        Else
            Return False
        End If
    End Operator

We now need another pair of operators for the second condition.

    ''' <summary>
    ''' Determines whether one specified System.DateTime is equal to another specified DateTimeNull.
    ''' </summary>
    ''' <param name="d1">A System.DateTime.</param>
    ''' <param name="d2">A DateTimeNull.</param>
    ''' <returns><c>true</c> if d1 is not null and d1 is equal to d2; otherwise, false.</returns>
    Public Shared Operator =(ByVal d1 As System.DateTime, ByVal d2 As DateTimeNull) As Boolean
        If d2.HasValue Then
            Return (d1 = d2.InternalDate)
        Else
            Return False
        End If
    End Operator

    ''' <summary>
    ''' Determines whether one specified System.DateTime is not equal to another specified DateTimeNull.
    ''' </summary>
    ''' <param name="d1">A System.DateTime.</param>
    ''' <param name="d2">A DateTimeNull.</param>
    ''' <returns><c>true</c> if d1 is not null and d1 is not equal to d2; otherwise, false.</returns>
    Public Shared Operator <>(ByVal d1 As System.DateTime, ByVal d2 As .DateTimeNull) As Boolean
        If d2.HasValue Then
            Return Not (d1 = d2.InternalDate)
        Else
            Return False
        End If
    End Operator

We may now wish to take the time to add in some "greater-than-or-equal-to" and "less-than-or-equal-to" operators for these two data types.

    ''' <summary>
    ''' Determines whether one specified DateTimeNull is less than or equal to another specified System.DateTime.
    ''' </summary>
    ''' <param name="d1">A DateTimeNull.</param>
    ''' <param name="d2">A System.DateTime.</param>
    ''' <returns><c>true</c> if d1 is not null and d1 is less than or equal to d2; otherwise, false.</returns>
    Public Shared Operator <=(ByVal d1 As DateTimeNull, ByVal d2 As System.DateTime) As Boolean
        If d1.HasValue Then
            Return (d1.InternalDate <= d2)
        Else
            Return False
        End If
    End Operator

    ''' <summary>
    ''' Determines whether one specified DateTimeNull is greater than or equal to another specified System.DateTime.
    ''' </summary>
    ''' <param name="d1">A DateTimeNull.</param>
    ''' <param name="d2">A System.DateTime.</param>
    ''' <returns><c>true</c> if d1 is not null and d1 is greater than or equal to d2; otherwise, false.</returns>
    Public Shared Operator >=(ByVal d1 As DateTimeNull, ByVal d2 As System.DateTime) As Boolean
        If d1.HasValue Then
            Return (d1.InternalDate >= d2)
        Else
            Return False
        End If
    End Operator

Remember to provide operators for both left and right evaluation of the DateTimeNull object.

Casting to and from System.Data.SqlTypes.SqlDateTime

To allow cross casting between our DateTimeNull object and the System.Data.SqlTypes.SqlDateTime we just follow the same process and add in the widening and comparison operators as we did for the System.DateTime, but we do need to keep in mind the upper and lower date limits of the System.Data.SqlTypes.SqlDateTime structure or an out of range error could happen at run-time. So evaluate the value and throw an appropriate exception as necessary in the operator.

In Part 5, we will look at some of the methods we may need to implement

Operators for DBNull.Value, continues from Part 2

In this article I shall deal with operators, specifically the ones which will allow assignment of a value to the DateTimeNull object or vice-versa. For example I want to be able to run this code:

Dim nullableDate As DateTimeNull = Nothing
nullableDate = DBNull.Value

To do this I need to create a couple of shared (non-instance) 'Widening Operator' for DBNull which will allow the compiler to cast the values.

#Region "Operators for DBNull"

    ''' <summary>
    ''' Converts a System.DBNull object to a DateTimeNull object.
    ''' </summary>
    ''' <param name="value"></param>
    ''' <returns>Returns a DateTimeNull with a Null value.</returns>
    ''' <remarks></remarks>
    Public Shared Widening Operator CType(ByVal value As System.DBNull) As DateTimeNull
        Return New DateTimeNull(value)
    End Operator

    ''' <summary>
    ''' Converts a DateTimeNull object to a System.DBNull object.
    ''' </summary>
    ''' <param name="value"></param>
    ''' <returns></returns>
    ''' <exception cref="InvalidCastException">Thrown if the DateTimeNull is not null.</exception>
    Public Shared Widening Operator CType(ByVal value As DateTimeNull) As System.DBNull
        If value.IsNull Then
            Return System.DBNull.Value
        End If
        Throw New InvalidCastException("A non null DateTimeNull cannot be cast to DBNull.")
    End Operator

#End Region

The first operator will return a DBNull.Value to be asigned to the DateTimeNull object, like so

nullableDate = DBNull.Value

The second widening operator is required when we want to do some comparisions of the DateTimeNull to DBNull.Value. To see what I mean, we first need to add an equality operator.

    ''' <summary>
    ''' Performs a logical comparison between a DateTimeNull object 
    ''' and a System.DBNull object to determine whether they are equal.
    ''' </summary>
    ''' <param name="d1">A DateTimeNull object.</param>
    ''' <param name="d2">A System.DBNull object.</param>
    ''' <returns>Returns <c>true</c> if d1 is null.</returns>
    Public Shared Operator =(ByVal d1 As DateTimeNull, ByVal d2 As System.DBNull) As Boolean
        Return d1.IsNull
    End Operator

This will allow us to as this question...

    If (nullableDate = DBNull.Value) Then
        ' Do something...
    End If

But without the second Widening operator, we can not ask this question, without the compiler complaining...

    If (DBNull.Value = nullableDate) Then
        ' Do something...
    End If

Try it and see. If you comment out the second widening operator, then the equality test with DBNull.Value as the left hand value will not compile. Uncomment it and all is well!

Finaly, we'll add in a not equal operator.

    ''' <summary>
    ''' Performs a logical comparison between a DateTimeNull object 
    ''' and a System.DBNull object to determine whether they are not equal.
    ''' </summary>
    ''' <param name="d1">A DateTimeNull object.</param>
    ''' <param name="d2">A System.DBNull object.</param>
    ''' <returns>Returns <c>true</c> if d1 is not null.</returns>
    Public Shared Operator <>(ByVal d1 As DateTimeNull, ByVal d2 As System.DBNull) As Boolean
        Return Not d1.IsNull
    End Operator

In the next artical we'll cover using widening operators for casting to and from System.Datetime and SqlDateTime. (TBC)...

Constructors Continued from Part 1...

We will need a series of constructors which will be used when we create Widening Operators, later. The first we aill use will accept a parameter value for ticks as an Int64. We will set the date using our InternalDate property as this will handle setting the inherited _isNull field for us.

    ''' <summary>
    ''' Initializes a new instance of the <see cref="DateTimeNull" /> class to a specified number of ticks.
    ''' </summary>
    ''' <param name="ticks">The ticks.</param>
    Public Sub New(ByVal ticks As Long)
        MyBase.New()
        Me.InternalDate = New System.DateTime(ticks)
    End Sub

The next constructor will take a System.DateTime parameter to construct our object.

    ''' <summary>
    ''' Initializes a new instance of the <see cref="DateTimeNull" /> class using the specified System.DateTime value.
    ''' </summary>
    ''' <param name="value">The value.</param>
    Public Sub New(ByVal value As System.DateTime)
        Me.New(value.Ticks)
    End Sub

The following constructor will take a System.Data.SqlTypes.SqlDateTime parameter to construct our object.

    ''' <summary>
    ''' Initializes a new instance of the <see cref="DateTimeNull" /> class using the specified System.Data.SqlTypes.SqlDateTime value.
    ''' </summary>
    ''' <param name="value">The value.</param>
    Public Sub New(ByVal value As System.Data.SqlTypes.SqlDateTime)
        MyBase.New()
        Dim dt As System.DateTime
        dt = Convert.ToDateTime(value)
        Me.InternalDate = dt
    End Sub

The last constructor will take a System.DBNull to construct or object.

    ''' <summary>
    ''' Initializes a new instance of the <see cref="DateTimeNull" /> class using a system.DBNull object.
    ''' </summary>
    ''' <param name="value">The value.</param>
    Public Sub New(ByVal value As System.DBNull)
        Me.New(System.DateTime.MinValue)
        If Not Me.IsNull Then
            Me.SetIsNull(True)
        End If
    End Sub

With our constructors done we will take a quick look at some of the properties which may be useful. Each property will reflect one of the properties that the .Net System.Datetime object has. Reflector is a useful tool for investigating these. Each property will expose the underlying InternalDate's properties, but first it must check if our object is in the NULL state. I have included just a few properties so you can see the pattern used.

    ''' <summary>
    ''' Gets the date component of this instance.
    ''' </summary>
    ''' <value>A new DateTime with the same date as this instance, and the time value set to 12:00:00 midnight (00:00:00).</value>
    ''' <exception cref="ArgumentNullException">Thrown</exception>
    Public ReadOnly Property [Date]() As DateTimeNull
        Get
            If Me.HasValue Then
                Return New DateTimeNull(Me.InternalDate.Date)
            Else
                Throw New ArgumentNullException("Date cannot be returned for a null DateTimeNull")
            End If
        End Get
    End Property

    ''' <summary>
    ''' Gets the day of the month represented by this instance.
    ''' </summary>
    ''' <remarks>The day component, expressed as a value between 1 and 31.</remarks>
    Public ReadOnly Property Day() As System.Int32
        Get
            If Me.HasValue Then
                Return Me.InternalDate.Day
            Else
                Throw New NullReferenceException("Day cannot be expressed for a null DateTimeNull object. ")
            End If
        End Get
    End Property

    ''' <summary>
    ''' Gets the hour component of the date represented by this instance.
    ''' </summary>
    ''' <returns>The hour component, expressed as a value between 0 and 23, inclusive.</returns>
    Public ReadOnly Property Hour() As System.Int32
        Get
            If Me.HasValue Then
                Return Me.InternalDate.Hour
            Else
                Throw New NullReferenceException("Hour cannot be expressed for a null DateTimeNull object. ")
            End If
        End Get
    End Property

    ''' <summary>
    ''' Gets a System.DateTime object that is set to the current date and time on this computer, expressed as the local time.
    ''' </summary>
    ''' <returns>A DateTime whose value is the current local date and time.</returns>
    Public Shared ReadOnly Property Now() As DateTime
        Get
            Return DateTime.UtcNow.ToLocalTime
        End Get
    End Property

    ''' <summary>
    ''' Gets the current date.
    ''' </summary>
    '''<returns>A DateTime set to today's date, with the time component set to 00:00:00.</returns>
    Public Shared ReadOnly Property Today() As DateTime
        Get
            Return DateTime.Now.Date
        End Get
    End Property

Over time I will add more properties to my DateTimeNull object, as they are required. Next however, it is time to look at Operators. This will be in Part 3.