DateTime, DateTimeOffset and TimeSpan
Three types cover time. DateTime is a date and a time with a Kind that says whether it is UTC, local or unspecified; DateTimeOffset is a moment with the offset from UTC it was written in; TimeSpan is a duration. The lesson measures all three, always with fixed values, because a page cannot print the current time twice and stay reproducible.
DateTime and its Kind
A DateTime stores ticks since year 1 and one of three kinds. AddHours returns a new value; a subtraction of two values gives a TimeSpan:
var start = new DateTime(2024, 3, 10, 9, 30, 0, DateTimeKind.Utc);
var end = start.AddHours(2).AddMinutes(15);
var span = end - start;
Console.WriteLine(start.ToString("yyyy-MM-dd HH:mm"));
Console.WriteLine(end.ToString("yyyy-MM-dd HH:mm"));
Console.WriteLine($"span {span}");
Console.WriteLine($"minutes {span.TotalMinutes}");
Console.WriteLine($"kind {start.Kind}");
Console.WriteLine($"ticks {TimeSpan.FromSeconds(90).Ticks}");
Console.WriteLine($"from {TimeSpan.FromMinutes(1.5)}");
dotnet run
2024-03-10 09:30
2024-03-10 11:45
span 02:15:00
minutes 135
kind Utc
ticks 900000000
from 00:01:30
The two additions gave a value two hours and fifteen minutes later, and the subtraction gave the duration back. One tick is one hundred nanoseconds, so ninety seconds is 900 000 000 ticks, and FromMinutes(1.5) is one minute and thirty seconds. The Kind is metadata: it does not change the numbers, and it is what tells the conversion code how to read them.
Arithmetic and TimeSpan
Month arithmetic knows the length of the month, and a parsed duration is a TimeSpan with the same properties as a computed one:
var local = new DateTime(2024, 3, 10, 9, 30, 0, DateTimeKind.Unspecified);
var utc = TimeZoneInfo.ConvertTimeToUtc(local, TimeZoneInfo.Utc);
Console.WriteLine($"utc {utc:yyyy-MM-dd HH:mm} {utc.Kind}");
Console.WriteLine($"day {local.DayOfWeek}");
Console.WriteLine($"leap {DateTime.IsLeapYear(2024)}");
Console.WriteLine($"next {new DateTime(2024, 2, 29).AddDays(1):yyyy-MM-dd}");
var duration = TimeSpan.Parse("01:02:03");
Console.WriteLine($"parsed {duration}");
Console.WriteLine($"total seconds {duration.TotalSeconds}");
Console.WriteLine($"negative {TimeSpan.FromMinutes(-30)}");
Console.WriteLine($"days {TimeSpan.FromHours(50).Days}");
dotnet run
utc 2024-03-10 09:30 Utc
day Sunday
leap True
next 2024-03-01
parsed 01:02:03
total seconds 3723
negative -00:30:00
days 2
The conversion to UTC used the UTC zone, so the wall clock stayed the same and the kind became Utc. One day after 29 February of a leap year is 1 March. The parsed duration is one hour, two minutes and three seconds, which is 3723 seconds; a negative duration prints with a minus sign, and Days is the whole-day component, which is 2 for fifty hours.
DateTimeOffset
DateTimeOffset keeps the offset, so it prints the wall clock of the place the value came from and still compares by instant:
var offset = new DateTimeOffset(2024, 3, 10, 9, 30, 0, TimeSpan.FromHours(3));
Console.WriteLine($"offset {offset}");
Console.WriteLine($"utc {offset.UtcDateTime:yyyy-MM-dd HH:mm}");
Console.WriteLine($"offset hours {offset.Offset.TotalHours}");
var first = new DateTimeOffset(2024, 1, 1, 0, 0, 0, TimeSpan.Zero);
var second = first.ToOffset(TimeSpan.FromHours(5));
Console.WriteLine($"same instant {first == second}");
Console.WriteLine($"first {first:HH:mm} second {second:HH:mm}");
Console.WriteLine($"month {second.Month} year {second.Year}");
dotnet run
offset 03/10/2024 09:30:00 +03:00
utc 2024-03-10 06:30
offset hours 3
same instant True
first 00:00 second 05:00
month 1 year 2024
Nine thirty at offset +03:00 is six thirty UTC, and the default format of the type shows both the local time and the offset. ToOffset changed the wall clock to 05:00 and kept the instant, which is why the two values compare equal. The same instant at +05:00 is still in January, so the month and the year did not change; a value close to midnight would have moved to the next day.
Time zones and conversion
TimeZoneInfo knows the named zones of the system, and TimeZoneInfo.Local is the one of the process. This container reports UTC, which the first section measured as the kind of the date it built. The offset of a zone changes with daylight saving, so a conversion takes the date as well as the zone: the same local time in Berlin is +01:00 in January and +02:00 in July. DateTimeOffset is the type to store and to send; a DateTime with an unspecified kind is a wall clock with no place, and a program that treats it as UTC eventually shifts it twice.
Exercises
- Print the value of TimeZoneInfo.Local.Id on this machine.
- Add one month to 31 January of a non-leap year and print the result.
- Compare a DateTimeOffset at +03:00 with a DateTime and explain the compiler error.
- Parse a duration written as 1.02:03:04 and print its total hours.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which type carries the offset from UTC?
Answer
DateTimeOffset
DateTimeOffset is a moment plus the offset it was written in.
-
What does the Kind property of a DateTime say?
Answer
Whether the value is UTC, local or unspecified
Kind is metadata about how to read the numbers, not a zone.
-
What does this program print?
Console.WriteLine(new DateTime(2024, 1, 31).AddMonths(1).ToString("yyyy-MM-dd"));Answer
2024-02-29
February 2024 is a leap month and AddMonths clamps to its last day.
-
What does a TimeSpan represent?
Answer
A duration
The subtraction of two dates gives one, and FromMinutes builds one.
-
What does this program print?
Console.WriteLine(TimeSpan.FromMinutes(90));Answer
01:30:00
Ninety minutes is one hour and thirty minutes.
-
Does a DateTime store a time zone?
Answer
No, only a Kind and the ticks
The zone is applied at conversion time; the value keeps ticks and a Kind.
-
What does this program print?
Console.WriteLine(new DateTime(2024, 3, 10).DayOfWeek);Answer
Sunday
10 March 2024 was a Sunday.
-
What is DateTime.UtcNow?
Answer
The current time in UTC, with Kind Utc
It reads the system clock and marks the value as UTC.
-
What does ToOffset do on a DateTimeOffset?
Answer
Changes the offset and keeps the instant
The measured pair compared equal while the wall clock moved from 00:00 to 05:00.
-
What does this program print?
Console.WriteLine(TimeSpan.FromHours(50).Days);Answer
2
Days is the whole-day component of the duration.
The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev