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

  1. Print the value of TimeZoneInfo.Local.Id on this machine.
  2. Add one month to 31 January of a non-leap year and print the result.
  3. Compare a DateTimeOffset at +03:00 with a DateTime and explain the compiler error.
  4. 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.

  1. Which type carries the offset from UTC?

    Answer

    DateTimeOffset

    DateTimeOffset is a moment plus the offset it was written in.

  2. 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.

  3. 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.

  4. What does a TimeSpan represent?

    Answer

    A duration

    The subtraction of two dates gives one, and FromMinutes builds one.

  5. What does this program print? Console.WriteLine(TimeSpan.FromMinutes(90));

    Answer

    01:30:00

    Ninety minutes is one hour and thirty minutes.

  6. 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.

  7. What does this program print? Console.WriteLine(new DateTime(2024, 3, 10).DayOfWeek);

    Answer

    Sunday

    10 March 2024 was a Sunday.

  8. What is DateTime.UtcNow?

    Answer

    The current time in UTC, with Kind Utc

    It reads the system clock and marks the value as UTC.

  9. 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.

  10. 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

Banner image