System.TimeSpan Structure

Represents a time interval.

See Also: TimeSpan Members


public struct TimeSpan : IComparable, IComparable<TimeSpan>, IEquatable<TimeSpan>, IFormattable


A TimeSpan object represents a time interval (duration of time or elapsed time) that is measured as a positive or negative number of days, hours, minutes, seconds, and fractions of a second. The TimeSpan structure can also be used to represent the time of day, but only if the time is unrelated to a particular date. Otherwise, the DateTime or DateTimeOffset structure should be used instead. (For more information about using the TimeSpan structure to reflect the time of day, see Choosing Between DateTime, DateTimeOffset, and TimeZoneInfo.)

The largest unit of time that the TimeSpan structure uses to measure duration is a day. Time intervals are measured in days for consistency, because the number of days in larger units of time, such as months and years, varies.

The value of a TimeSpan object is the number of ticks that equal the represented time interval. A tick is equal to 100 nanoseconds, or one ten-millionth of a second. The value of a TimeSpan object can range from TimeSpan.MinValue to TimeSpan.MaxValue.

Instantiating a TimeSpan Value

You can instantiate a TimeSpan value in a number of ways:

Performing Operations on TimeSpan Values

You can add and subtract time durations either by using the TimeSpan.op_Addition(TimeSpan, TimeSpan) and TimeSpan.op_Subtraction(TimeSpan, TimeSpan) operators, or by calling the TimeSpan.Add(TimeSpan) and TimeSpan.Subtract(TimeSpan) methods. You can also compare two time durations by calling the TimeSpan.Compare(TimeSpan, TimeSpan), erload:System.TimeSpan.CompareTo, and erload:System.TimeSpan.Equals methods. The TimeSpan class also includes the TimeSpan.Duration and TimeSpan.Negate methods, which convert time intervals to positive and negative values,

The range of TimeSpan values is TimeSpan.MinValue to TimeSpan.MaxValue.

Formatting a TimeSpan Value

A TimeSpan value can be represented as [-]d.hh:mm:ss.ff, where the optional minus sign indicates a negative time interval, the d component is days, hh is hours as measured on a 24-hour clock, mm is minutes, ss is seconds, and ff is fractions of a second. That is, a time interval consists of a positive or negative number of days without a time of day, or a number of days with a time of day, or only a time of day.

Beginning with the net_v40_long, the TimeSpan structure supports culture-sensitive formatting through the overloads of its TimeSpan.ToString(string, IFormatProvider) method, which converts a TimeSpan value to its string representation. The default TimeSpan.ToString method returns a time interval by using an invariant format that is identical to its return value in previous versions of the .NET Framework. The TimeSpan.ToString(string) overload lets you specify a format string that defines the string representation of the time interval. The TimeSpan.ToString(string, IFormatProvider) overload lets you specify a format string and the culture whose formatting conventions are used to create the string representation of the time interval. TimeSpan supports both standard and custom format strings. (For more information, see Standard TimeSpan Format Strings and Custom TimeSpan Format Strings.) However, only standard format strings are culture-sensitive.

Restoring Legacy TimeSpan Formatting

In some cases, code that successfully formats TimeSpan values in net_v35_short and earlier versions fails in net_v40_short. This is most common in code that calls a composite formatting method to format a TimeSpan value with a format string. The following example successfully formats a TimeSpan value in net_v35_short and earlier versions, but throws an exception in net_v40_short and later versions. Note that it attempts to format a TimeSpan value by using an unsupported format specifier, which is ignored in net_v35_short and earlier versions.

code reference: System.TimeSpan.Class.Legacy#1

If you cannot modify the code, you can restore the legacy formatting of TimeSpan values in one of the following ways:

Thread Safety

All public static members of this type are safe for multithreaded operations. No instance members are guaranteed to be thread safe.


Namespace: System
Assembly: mscorlib (in mscorlib.dll)
Assembly Versions: 1.0.5000.0,,