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. (And yes, TimeSpans know all about leap years.)
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.
Example program MultiplyTimeSpan, which is available for download on the book’s website, uses the following statement to make the TimeSpan ts2 equal to 12 times the duration of TimeSpan ts1:
ts2 = New TimeSpan(ts1.Ticks * 12)
Sometimes using operators to combine Date and TimeSpan values can be 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 summarizes these methods.
| 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.