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 TimeSpan
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)
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)
Depending on the day on which you execute these statements, they will print something like the following in the Output window:
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).
The TimeSpan type exposes the properties described in the following sections. Most of these properties are shared.
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
|Empty||An empty TimeSpan object|
|MaxValue||The largest interval you can represent with a TimeSpan object|
|MinValue||The smallest interval you can represent with a TimeSpan object|
|TicksPerDay||The number of ticks in a day|
|TicksPerHour||The number of ticks in an hour|
|TicksPerMillisecond||The number of ticks in a millisecond|
|TicksPerMinute||The number of ticks in one minute|
|TicksPerSecond||The number of ticks in one second|
|Zero||A TimeSpan object of zero duration|
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
|Days||The number of whole days in the current TimeSpan.|
|Hours||The number of whole hours in the current TimeSpan.|
|Milliseconds||The number of whole milliseconds in the current TimeSpan. The largest value of this property is 999.|
|Minutes||The number of whole minutes in the current TimeSpan. The largest value of this property is 59.|
|Seconds||The number of whole seconds in the current TimeSpan. The largest value of this property is 59.|
|Ticks||The number of whole ticks in the current TimeSpan.|
Table 9.5: The Total Intervals of a TimeSpan Value
|TotalDays||The number of days in the current TimeSpan|
|TotalHours||The number of hours in the current TimeSpan|
|TotalMilliseconds||The number of whole milliseconds in the current TimeSpan|
|TotalMinutes||The number of whole minutes in the current TimeSpan|
|TotalSeconds||The number of whole seconds in the current TimeSpan|
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.
Similar Method Names, Different Results
Be very careful when choosing the property to express the duration of a TimeSpan in a specific interval. The Seconds property is totally different from the TotalSeconds property. Because both properties will return a value, you may not notice that you’re using the wrong property for the task at hand.
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)
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.
There are various methods for creating and manipulating instances of the TimeSpan class, and they’re described in the following sections.
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).
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")
Table 9.6: Interval Methods of the TimeSpan Object
|Method||Creates a New TimeSpan of This Length|
|FromDays||Number of days specified by the argument|
|FromHours||Number of hours specified by the argument|
|FromMinutes||Number of minutes specified by the argument|
|FromSeconds||Number of seconds specified by the argument|
|FromMilliseconds||Number of milliseconds specified by the argument|
|FromTicks||Number of ticks specified by the argument|
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)
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))
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)
The last three statements printed the following values in the Output window:
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.
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).