One of C#'s more confusing data types is DateTime
. A DateTime
represents a date, a time, or both. For example, a DateTime
variable might represent Thursday April 1, 2020 at 9:15 AM.
In this lesson, you learn how to work with dates and times. You learn how to create DateTime
variables, find the current date and time, and calculate elapsed time.
C# doesn't have DateTime
literal values so you can't simply set a DateTime
variable equal to a value as you can with some other data types. Instead you can use the new
keyword to initialize a new DateTime
variable, supplying arguments to define the date and time.
For example, the following code creates a DateTime
variable named aprilFools
and initializes it to the date April 1, 2020. It then displays the date using the short date format described in Lesson 14 and by calling the variable's ToShortDateString
method:
DateTime aprilFools = new DateTime(2020, 4, 1);
MessageBox.Show(aprilFools.ToString("d"));
MessageBox.Show(aprilFools.ToShortDateString());
The preceding code uses a year, month, and day to initialize its DateTime
variable, but the DateTime
type lets you use many different kinds of values. The three most useful combinations of arguments specify (all as integers):
You can also add a kind
parameter to the end of the second and third of these combinations to indicate whether the value represents local time or UTC time. (Local and UTC times are explained in the next section.) For example, the following code creates a DateTime
representing 12 noon on March 15, 2020 in the local time zone:
DateTime idesOfMarch =
new DateTime(2020, 3, 15, 12, 0, 0, DateTimeKind.Local);
Windows has several different notions of dates and times. Two of the most important of these are local time and Coordinated Universal Time (UTC).
Local time is the time on your computer as it is configured for a particular locale. It's what you and a program's user typically think of as time.
UTC time is basically the same as Greenwich Mean Time (GMT), the time at the Royal Academy in Greenwich, London.
For most everyday tasks, local time is fine. If you need to compare data on computers running in different time zones, however, UTC time can make coordination easier. For example, if you want to know whether a customer in New York created an order before another customer created an order in San Salvador, UTC lets you compare the times without worrying about the customers' time zones.
A DateTime
object has a Kind
property that indicates whether the object represents local time, UTC time, or an unspecified time. When you create a DateTime
, you can indicate whether you are creating a local or UTC time. If you do not specify the kind of time, C# assumes you are making an unspecified time.
After you create a DateTime
, its ToLocalTime
and ToUniversalTime
methods convert between local and UTC times.
The DateTime
type provides many useful properties and methods for manipulating dates and times. Table 15.1 summarizes some of DateTime
's most useful methods. Static methods are indicated with an asterisk. You invoke static methods by using the type name rather than a variable name, as in DateTime.IsLeapYear(2020)
.
Method | Purpose |
Add |
Adds a TimeSpan to the DateTime . The following section describes TimeSpan . |
AddDays |
Adds a specified number of days to the DateTime . |
AddHours |
Adds a specified number of hours to the DateTime . |
AddMinutes |
Adds a specified number of minutes to the DateTime . |
AddMonths |
Adds a specified number of months to the DateTime . |
AddSeconds |
Adds a specified number of seconds to the DateTime . |
AddYears |
Adds a specified number of years to the DateTime . |
IsDaylightSavingsTime |
Returns true if the date and time is within the Daylight Savings Time period for the local time zone. |
IsLeapYear * |
Returns true if the indicated year is a leap year. |
Parse * |
Parses a string and returns the corresponding DateTime . |
Subtract |
Subtracts another DateTime from this one and returns a TimeSpan . The following section says more about TimeSpan . |
ToLocalTime |
Converts the DateTime to a local value. |
ToLongDateString |
Returns the DateTime in long date format. |
ToLongTimeString |
Returns the DateTime in long time format. |
ToShortDateString |
Returns the DateTime in short date format. |
ToShortTimeString |
Returns the DateTime in short time format. |
ToString |
Returns the DateTime in general format. |
ToUniversalTime |
Converts the DateTime to a UTC value. |
Table 15.2 summarizes the DateTime
's most useful properties.
Property | Purpose |
Date |
Gets the DateTime 's date without the time. |
Day |
Gets the DateTime 's day of the month between 1 and 31. |
DayOfWeek |
Gets the DateTime 's day of the week, as in Monday. |
DayOfYear |
Gets the DateTime 's day of the year between 1 and 366. (Leap years have 366 days.) |
Hour |
Gets the DateTime 's hour between 0 and 23. |
Kind |
Returns the DateTime 's kind: Local , Utc , or Unspecified . |
Millisecond |
Gets the DateTime 's time's millisecond. |
Minute |
Gets the DateTime 's minute between 0 and 59. |
Month |
Gets the DateTime 's month between 1 and 12. |
Now * |
Gets the current date and time. |
Second |
Gets the DateTime 's second between 0 and 59. |
TimeOfDay |
Gets the DateTime 's time without the date. |
Today * |
Gets the current date without a time. |
UtcNow * |
Gets the current UTC date and time. |
Year |
Gets the DateTime 's year. |
A DateTime
represents a point in time (July 20, 1969 at 20:17:40). A TimeSpan
represents an elapsed period of time (1 day, 17 hours, 27 minutes, and 12 seconds).
One of the more useful ways to make a TimeSpan
is to subtract one DateTime
from another to find the amount of time between them. For example, the following code calculates the time that elapsed between the first and last manned moon landings:
DateTime firstLanding = new DateTime(1969, 7, 20, 20, 17, 40);
DateTime lastLanding = new DateTime(1972, 12, 11, 19, 54, 57);
TimeSpan elapsed = lastLanding - firstLanding;
Console.WriteLine(elapsed.ToString());
The code creates DateTime
values to represent the times of the two landings. It then subtracts the last date from the first to get the elapsed time and uses the resulting TimeSpan
's ToString
method to display the duration. The following text shows the result in the format days.hours:minutes:seconds
:
1239.23:37:17
Table 15.3 summarizes the TimeSpan
's most useful properties and methods.
Property | Meaning |
Days |
The number of days. |
Hours |
The number of hours. |
Milliseconds |
The number of milliseconds. |
Minutes |
The number of minutes. |
Seconds |
The number of seconds. |
ToString |
Converts the TimeSpan into a string in the format days.hours:minutes:seconds.fractionalSeconds . |
TotalDays |
The entire TimeSpan represented as days. For a 36-hour duration, this would be 1.5. |
TotalHours |
The entire TimeSpan represented as hours. For a 45-minute duration, this would be 0.75. |
TotalMilliseconds |
The entire TimeSpan represented as milliseconds. For a 1-second duration, this would be 1,000. |
TotalMinutes |
The entire TimeSpan represented as minutes. For a 1-hour duration, this would be 60. |
TotalSeconds |
The entire TimeSpan represented as seconds. For a 1-minute TimeSpan , this would be 60. |
Note that you can use the + and – operators to add and subtract TimeSpan
s, getting a new TimeSpan
as a result. This works in a fairly obvious way. For example, a 90-minute TimeSpan
minus a 30-minute TimeSpan
gives a 60-minute TimeSpan
.
In this Try It, you use DateTime
and TimeSpan
variables to build the stopwatch application shown in Figure 15.1. When the user clicks the Start Button
, the program starts its counter. When the user clicks the Stop Button
, the program stops the counter.
Normally the TimeSpan
's ToString
method displays a value in the format d.hh:mm:ss.fffffff
. In this example, you use string.Format
to display the elapsed time in the format hh:mm:ss.ff
.
In this lesson, you:
Timer
with Interval = 10
. Initially disable the Stop button.Timer
, disable the Start button, and enable the Stop button.Timer
, enable the Start button, and disable the Stop button.Timer
's Tick
event fires, display the elapsed time in the format hh:mm:ss.ff
.TimeSpan
doesn't use the same formatting characters as a DateTime
, so, for example, you can't simply use a format string such as hh:mm:ss.ff
. Instead use the TimeSpan
properties to get the elapsed hours, minutes, seconds, and milliseconds and then format those values.Timer
with Interval = 10
. Initially disable the Stop button.
Label
to the form as shown in Figure 15.1. Set the Stop button's Enabled
property to False
.Timer
and set its Interval
property to 10 milliseconds.Timer
, disable the Start button, and enable the Stop button.
DateTime
field named StartTime
:// The time when the user clicked Start.
private DateTime StartTime;
Click
event handler:// Start the Timer.
private void startButton_Click(object sender, EventArgs e)
{
StartTime = DateTime.Now;
startButton.Enabled = false;
stopButton.Enabled = true;
updateLabelTimer.Enabled = true;
}
Timer
, enable the Start button, and disable the Stop button.
Click
event handler:// Stop the Timer.
private void stopButton_Click(object sender, EventArgs e)
{
startButton.Enabled = true;
stopButton.Enabled = false;
updateLabelTimer.Enabled = false;
}
Timer
's Tick
event fires, display the elapsed time in the format hh:mm:ss.ff
.
// Display the elapsed time.
private void updateLabelTimer_Tick(object sender, EventArgs e)
{
// Subtract the start time from the current time
// to get elapsed time.
TimeSpan elapsed = DateTime.Now - StartTime;
// Display the result.
elapsedTimeLabel.Text = string.Format(
"{0:00}:{1:00}:{2:00}.{3:00}",
elapsed.Hours,
elapsed.Minutes,
elapsed.Seconds,
elapsed.Milliseconds / 10);
}
System.Diagnostics.Stopwatch
class acts like a stopwatch. It provides methods to start, reset, and stop timing. Copy the program you built for the Try It and modify it so it uses the Stopwatch
class instead of a DateTime
. Hints:
Stopwatch
's Elapsed
property to see how long it's been since the watch was started.Start
method.Reset
method to stop timing and reset the watch's elapsed time to 0.TextBox
and a Calculate Button
. When the user enters a birth date and clicks the Button
, calculate the person's current age and add items to a ListBox
that display the age converted into each of days, hours, minutes, and seconds. Format all of the values with thousands separators and two digits after the decimal place.DateTime
class doesn't have TotalYears
or TotalMonths
properties (probably because Microsoft didn't want to figure out how to handle leap years). Calculate the number of years by dividing the number of days by 365.2425. Calculate the number of months by multiplying the number of years by 12.TextBox
es for dates and a Button
. When the user clicks the Button
, the program should display the time between the dates.DateTimePicker
controls instead of TextBox
es. To keep things simple, just display the total number of days between the dates using the N0 format specifier. Use the controls' Value
properties to get the selected dates. (This control prevents users from entering invalid dates such as April 45.)