Date and TimeSpan Operations

The Date data type is fundamentally different from other data types. When you perform an operation on most data types, you get a result that has the same data type or that is at least of some compatible data type. For example, if you subtract two Integer variables, the result is an Integer. If you divide two Integers using the / operator, the result is a Double. That’s not another Integer, but it is a compatible numeric data type used because an Integer cannot always hold the result of a division.

If you subtract two Date variables, however, the result is not a Date. For example, what’s August 7 minus July 20? It doesn’t make sense to think of the result as a Date. Instead, Visual Basic defines the difference between two Dates as a TimeSpan. A TimeSpan measures the elapsed time between two Dates. In this example, August 7 minus July 20 is 18 days.

The following equations define the arithmetic of Dates and TimeSpans.

• Date – Date = TimeSpan

• Date + TimeSpan = Date

• TimeSpan + TimeSpan = TimeSpan

• TimeSpan – TimeSpan = TimeSpan

The TimeSpan class also defines unary negation (ts2 = -ts1), but other operations (such as multiplying a TimeSpan by a number) are not defined. However, in some cases, you can still perform the calculation if you must. For example, the following statement makes the TimeSpan ts2 equal to 12 times the duration of TimeSpan ts1.

  ts2 = New TimeSpan(ts1.Ticks * 12) 

Tip 

A unary operator takes a single operand. For example, A = +B(unary plus), C = -D(unary negation), and E = Not F (logical unary negation) all use unary operators.

In Visual Basic 2005, the +, -, <, >, <=, >=, <>, and = operators are defined for Dates and TimeSpans. Previous versions did not define these operators, but the Date class did provide equivalent operator methods. For example, the Date class’s op_Subtraction method subtracts two Dates and returns a TimeSpan.

These operator methods are still available and you may want to use them if you find using the normal operator symbols less clear. The following table lists the Date operator methods. Note that the Common Language Runtime name for the Date data type is DateTime, so you need to look for DateTime in the online help for more information on these methods.

Open table as spreadsheet

Syntax	Meaning
result_date = Date.op_Addition(date1, timespan1)	Returns date1 plus timespan1
result_boolean = Date.op_Equality(date1, date2)	True if date1 > date2
result_boolean = Date.op_GreaterThan(date1, date2)	True if date1 > date2
result_boolean = Date.op_GreaterThanOrEqual (date1, date2)	True if date1 >= date2
result_boolean = Date.op_Inequality(date1, date2)	True if date1 <> date2
result_boolean = Date.op_LessThan(date1, date2)	True if date1 < date2
result_boolean = Date.op_LessThanOrEqual (date1, date2)	True if date1 <= date2
result_timespan = Date.op_Subtraction (date1, date2)	Returns the TimeSpan between date1 and date2
result = Date.Compare(date1, date2)	Returns a value indicating whether date1 is greater than, less than, or equal to date2

The Compare method is a bit different from the others, returning an Integer rather than a Boolean or Date. Its value is less than zero if date1 < date2, greater than zero if date1 > date2, and equal to zero if date1 = date2.

These are shared methods, so you do not need to use a specific instance of the Date data type to use them. For example, the following code displays the number of days between July 20 and August 7:

  Dim date1 As Date = #7/20/04# Dim date2 As Date = #8/7/04# Dim elapsed_time As TimeSpan     elapsed_time = Date.op_Subtraction(date2, date1)     Debug.WriteLine(elapsed_time.Days) 

These operators are a bit cumbersome. To make these kinds of calculations easier, the Date data type provides other methods for performing common operations that are a bit easier to read. Whereas the operator methods take both operands as parameters, these methods take a single operand as one parameter and use the current object as the other. For example, a Date object’s Add method adds a TimeSpan to the date and returns the resulting date. The following table summaries these methods.

Open table as spreadsheet

Syntax	Meaning
result_date = date1.Add(timespan1)	Returns date1 plus timespan1
result_date = date1.AddYears(num_years)	Returns the date plus the indicated number of years
result_date = date1.AddMonths(num_months)	Returns the date plus the indicated number of months
result_date = date1.AddDays(num_days)	Returns the date plus the indicated number of days
result_date = date1.AddHours(num_hours)	Returns the date plus the indicated number of hours
result_date = date1.AddMinutes(num_minutes)	Returns the date plus the indicated number of minutes
result_date = date1.AddSeconds(num_seconds)	Returns the date plus the indicated number of seconds
result_date = date1.AddMilliseconds (num_milliseconds)	Returns the date plus the indicated number of milliseconds
result_date = date1.AddTicks(num_ticks)	Returns the date plus the indicated number of ticks (100-nanosecond units)
result_timespan = date1.Subtract(date2)	Returns the time span between date2 and date1
result_integer = date1.CompareTo(date2)	Returns a value indicating whether date1 is greater than, less than, or equal to date2
result_boolean = date1.Equals(date2)	Returns True if date1 equals date2

The CompareTo method returns a value less than zero if date1 < date2, greater than zero if date1 > date2, and equal to zero if date1 = date2.