The TimeSpan Class

The last class discussed in this chapter is the TimeSpan class, which represents a time interval and can be expressed in many different units — from ticks and milliseconds to days. The TimeSpan is usually the difference between two date/time values, but you can also create a TimeSpan for a specific interval and use it in your calculations.

To use the TimeSpan variable in your code, just declare it with a statement such as the following:

Dim TS As New TimeSpanCode language: PHP (php)

To initialize the TimeSpan object, you can provide the number of days, hours, minutes, seconds, and milliseconds that make up the time interval. The following statement initializes a TimeSpan object to a duration of 9 days, 12 hours, 1 minute, and 59 seconds:

Dim TS As TimeSpan = New TimeSpan(9, 12, 1, 59)Code language: PHP (php)

As you have seen, the difference between two dates calculated by the Date.Subtract method returns a TimeSpan value. You can initialize an instance of the TimeSpan object by creating two date/time values and getting their difference, as in the following statements:

Dim TS As New TimeSpan
Dim date1 As Date = #4/11/1985#
Dim date2 As Date = Now()
TS = date2.Subtract(date1)
Debug.WriteLine(TS)Code language: PHP (php)

Depending on the day on which you execute these statements, they will print something like the following in the Output window:

8086.15:37:01.6336000Code language: CSS (css)

The days are separated from the rest of the string with a period, whereas the time parts are separated with colons. Notice that a TimeSpan object might represent an interval of many years, but it doesn’t provide members to report months or years. The difference represented by this value is 8,086 days, 15 hours, 37 minutes, 1 second, and 633,600 nanoseconds (or 633.6 milliseconds).

Properties

The TimeSpan type exposes the properties described in the following sections. Most of these properties are shared.

Field Properties

TimeSpan exposes the simple properties shown in Table 13.3, which are known as fields and are all shared.

Table 9.3: The Fields of the TimeSpan Object

Interval Properties

In addition to the fields, the TimeSpan class exposes two more groups of properties that return the various intervals in a TimeSpan value (shown in Tables 13.4 and 13.5). The members of the first group of properties return the number of specific intervals (days, hours, and so on) in a TimeSpan value. The second group of properties returns the entire TimeSpan’s duration in one of the intervals recognized by the TimeSpan method.

Table 9.4: The Intervals of a TimeSpan Value

Table 9.5: The Total Intervals of a TimeSpan Value

If a TimeSpan value represents 2 minutes and 10 seconds, the Seconds property will return the value 10. The TotalSeconds property, however, will return the value 130, which is the total duration of the TimeSpan in seconds.

Duration

This property returns the duration of the current instance of the TimeSpan class. The duration is expressed as the number of days followed by the number of hours, minutes, seconds, and milliseconds. The following statements create a TimeSpan object of a few seconds (or minutes, if you don’t mind waiting) and print its duration in the Output window. The first few statements initialize a new instance of the DateTime type, the T1 variable, to the current date and time. Then a message box is displayed that prompts to click the OK button to continue. Wait for several seconds before closing the message box. The last group of statements subtracts the T1 variable from the current time and displays the duration (how long you kept the message box open on your screen):

Dim T1, T2 As DateTime
T1 = Now
MsgBox("Click OK to continue")
T2 = Now
Dim TS As TimeSpan
TS = T2.Subtract(T1)
Debug.WriteLine("Total duration = " & TS.Duration.ToString)
Debug.WriteLine("Minutes = " & TS.Minutes.ToString)
Debug.WriteLine("Seconds = " & TS.Seconds.ToString)
Debug.WriteLine("Ticks = " & TS.Ticks.ToString)
Debug.WriteLine("Milliseconds = " & TS.TotalMilliseconds.ToString)
Debug.WriteLine("Total seconds = " & TS.TotalSeconds.ToString)Code language: PHP (php)

If you place these statements in a button’s Click event handler and execute them, you’ll see a series of values like the following in the Immediate window:

Total duration = 00:01:34.2154752
Minutes = 1
Seconds = 34
Ticks = 942154752
Milliseconds = 94215,4752
Total seconds = 94,2154752

The duration of the TS TimeSpan is 1 minute and 34 seconds. Its total duration in milliseconds is 94,215.4752, or 94.2154752 seconds.

Methods

There are various methods for creating and manipulating instances of the TimeSpan class, and they’re described in the following sections.

Interval Methods

The methods in Table 13.6 create a new TimeSpan object of a specific duration. The TimeSpan’s duration is specified as a number of intervals, accurate to the nearest millisecond.

All methods accept a single argument, which is a Double value that represents the number of the corresponding intervals (days, hours, and so on).

Parse(string)

This method creates a new TimeSpan object from a string with the TimeSpan format (days;followed by a period; followed by the hours, minutes, and seconds separated by colons). The following statements create a new TimeSpan variable with a duration of 3 days, 12 hours, 20 minutes, 30 seconds, and 500 milliseconds:

Dim SP As New TimeSpan()
SP = TimeSpan.Parse("3.12:20:30.500")
Debug.WriteLine(SP)
3.12:20:30.5000000Code language: PHP (php)

Table 9.6: Interval Methods of the TimeSpan Object

Add

This method adds a TimeSpan object to the current instance of the class; its syntax is the following, where TS, TS1, and newTS are all TimeSpan variables:

newTS = TS.Add(TS1)

The following statements create two TimeSpan objects and then add them:

Dim TS1 As New TimeSpan = "1:00:01"
Dim TS2 As New TimeSpan = "2:01:09"
Dim TS As New TimeSpan
TS = TS1.Add(TS2)Code language: PHP (php)

The duration of the new TimeSpan variable is 3 hours, 1 minute, and 10 seconds. A more practical example is the following, which constructs a TimeSpan object by using the From xxx methods described in the preceding section. The following statements create a TimeSpan object with a duration of 3 hours, 2 minutes, 16 seconds, and 500 milliseconds:

Dim TS As New system.TimeSpan()
TS = System.TimeSpan.FromHours(3)
TS = TS.Add(System.TimeSpan.FromMinutes(2))
TS = TS.Add(TimeSpan.FromSeconds(16))
TS = TS.Add(TimeSpan.FromMilliseconds(500))Code language: PHP (php)

Subtract

The Subtract method subtracts a TimeSpan object from the current instance of the TimeSpan class. The following statements create two TimeSpan objects with different durations. Then, the two time spans are subtracted and their difference is printed in three different ways:

Dim T1, T2 As TimeSpan
T1 = New TimeSpan(3, 9, 10, 12)
T2 = New TimeSpan(0, 1, 0, 59, 3)
Dim TS As TimeSpan = T2.Subtract(T1)
Debug.WriteLine(TS.Duration())
Debug.WriteLine(TS.Days)
Debug.WriteLine(TS.TotalDays)Code language: PHP (php)

The last three statements printed the following values in the Output window:

3.08:09:12.9970000
-3
-3.33973376157407Code language: CSS (css)

The duration of the span is 3 days, 8 hours, 9 minutes, 12 seconds, and 997 milliseconds. The Days method returns the number of days in the TimeSpan as a whole number. The TotalDays method returns the TimeSpan’s duration as a number of days with a fractional part. You have already seen how tomanipulate fractional parts of a time interval in the section ‘‘Dates as Numeric Values,’’ earlier in this chapter.

Negate

This method negates the current TimeSpan instance. A positive TimeSpan (which will yield a future date when added to the current date) becomes negative (which will yield a past date when added to the current date).