Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Date, Time and Globalization

The TimeOnly struct

Reference for System.TimeOnly in C# (.NET 6+): a time of day without a date, wrapping arithmetic, IsBetween, conversion to TimeSpan, parsing and formatting.

TimeOnly represents a time of day from 00:00:00.0000000 to 23:59:59.9999999, with no date and no time zone. Use it for opening hours, alarms, schedules and any value that repeats every day.

Unlike TimeSpan, which measures a length of time and can be negative or longer than a day, a TimeOnly is a point on a 24-hour clock. Adding hours to it wraps around midnight, and the type can tell you how many days it wrapped.

C#
var opens = new TimeOnly(9, 0);
var closes = new TimeOnly(17, 30);
Console.WriteLine(closes - opens);   // 08:30:00

Try it

C# Clock arithmetic and ranges

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

C# Conversions, parsing and limits

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Syntax

C#
public readonly struct TimeOnly : IComparable<TimeOnly>, IEquatable<TimeOnly>, IFormattable, IParsable<TimeOnly>
C#
new TimeOnly(int hour, int minute)
new TimeOnly(int hour, int minute, int second)
new TimeOnly(int hour, int minute, int second, int millisecond)
new TimeOnly(int hour, int minute, int second, int millisecond, int microsecond)
new TimeOnly(long ticks)
Member Description
Hour, Minute, Second, Millisecond, Microsecond, Nanosecond Components.
Ticks 100 ns units since midnight.
Add(TimeSpan), Add(TimeSpan, out int wrappedDays) Add a duration, wrapping at midnight; the second form reports whole days wrapped.
AddHours(double), AddMinutes(double) Add a number of hours or minutes (also with out wrappedDays overloads).
IsBetween(TimeOnly start, TimeOnly end) Start inclusive, end exclusive; handles ranges that cross midnight.
operator -(TimeOnly, TimeOnly) The TimeSpan from the right operand to the left, wrapping around midnight.
FromTimeSpan, FromDateTime, ToTimeSpan() Conversions.
Parse, TryParse, ParseExact, TryParseExact Text to time.
MinValue, MaxValue 00:00:00 and 23:59:59.9999999.

Errors: the constructors throw ArgumentOutOfRangeException for hour 24 or more, minute or second 60 or more. FromTimeSpan throws it when the span is negative or 24 hours or longer. Parsing failures throw FormatException.

Usage notes

  • Wrapping is silent. new TimeOnly(23, 30).AddMinutes(90) is 01:00 with no indication that a day passed. Use the out int wrappedDays overloads when the day matters.
  • Subtraction wraps too. a - b is always between zero and 24 hours: 01:00 minus 23:00 is 2 hours, not -22. Compare first if you need a signed difference.
  • IsBetween is half-open (start <= value < end). If start is later than end, the range is assumed to cross midnight. A range from 09:00 to 09:00 contains nothing.
  • Do not store durations in TimeOnly. "Takes 26 hours" is a TimeSpan. A shift that starts at 22:00 and lasts 8 hours is a TimeOnly plus a TimeSpan.
  • Format specifiers must be time-only: HH, mm, ss, fff, tt, "t", "T", and "O"/"o" (prints with 7 fraction digits). Date specifiers such as yyyy throw FormatException.
  • Daylight saving does not exist in TimeOnly. 02:30 is always a valid value, even on days when that local time is skipped. Combine with a date and a zone only when you need an instant.
  • Interop. Databases and JSON libraries map TimeOnly to time, but support depends on the version of the provider.
  • Default value. default(TimeOnly) is midnight.