C# TimeSpan Examples

TimeSpan represents a length of time.

We can create or manipulate TimeSpan instances in a C# program. The TimeSpan type provides many helper properties and methods. It is implemented as a struct type.

Constructor. First we use the TimeSpan instance constructor to create new TimeSpan structs. The TimeSpan constructor has several parameters and overloaded versions. You can use the IntelliSense feature in Visual Studio to choose the best one.

Visual StudioOverload

Next: This example calls the TimeSpan constructor with five int arguments. It creates a TimeSpan with 1 day, 2 hours, and 30 seconds.

C# program that uses TimeSpan constructor

using System;

class Program
{
    static void Main()
    {
	// Use TimeSpan constructor to specify:
	// ... Days, hours, minutes, seconds, milliseconds.
	// ... The TimeSpan returned has those values.
	TimeSpan span = new TimeSpan(1, 2, 0, 30, 0);
	Console.WriteLine(span);
    }
}

Output

1.02:00:30

From methods. The TimeSpan type has several public static methods that start with the word From. These include FromDays, FromHours, FromMinutes, FromSeconds, and FromMilliseconds. These convert a number of double type into a TimeSpan struct instance.

The TimeSpan result will allow you to use the figure in a more natural way in C# programs and other methods. It is useful to pass a number that has a decimal place to the From methods.

Convert TimeSpan, Long

C# program that uses TimeSpan.From methods

using System;

class Program
{
    static void Main()
    {
	// Get time spans from a specific double unit of time.
	// ... These allow easier manipulation of the time.
	TimeSpan span1 = TimeSpan.FromDays(1);
	TimeSpan span2 = TimeSpan.FromHours(1);
	TimeSpan span3 = TimeSpan.FromMinutes(1);
	TimeSpan span4 = TimeSpan.FromSeconds(1);
	TimeSpan span5 = TimeSpan.FromMilliseconds(1);

	Console.WriteLine(span1);
	Console.WriteLine(span2);
	Console.WriteLine(span3);
	Console.WriteLine(span4);
	Console.WriteLine(span5);
    }
}

Output

1.00:00:00
01:00:00
00:01:00
00:00:01
00:00:00.0010000

Add. Here we use the Add instance method. The TimeSpan.Add method receives one parameter of type TimeSpan. Structs such as TimeSpan are immutable and you can assign the result of the Add method to another TimeSpan variable.

Struct

Note: This program shows that when you add one minute to two minutes, you get three minutes.

C# program that uses TimeSpan.Add method

using System;

class Program
{
    static void Main()
    {
	// Adds a TimeSpan of one minute to a TimeSpan of two minutes.
	// ... Then we get three minutes in a TimeSpan.
	TimeSpan span1 = TimeSpan.FromMinutes(1);
	TimeSpan span2 = TimeSpan.FromMinutes(2);
	TimeSpan span3 = span1.Add(span2);
	Console.WriteLine(span3);
    }
}

Output

00:03:00

Subtract. The Subtract method receives one argument of type TimeSpan. The argument is the TimeSpan you want to subtract. Typically, you will subtract the smaller TimeSpan from the larger TimeSpan.

Next: This program shows that when you subtract one second from one minute, you receive 59 seconds.

C# program that uses TimeSpan.Subtract method

using System;

class Program
{
    static void Main()
    {
	// Subtract TimeSpan of one second from one minute.
	// ... The result is 59 seconds.
	TimeSpan span1 = TimeSpan.FromMinutes(1);
	TimeSpan span2 = TimeSpan.FromSeconds(1);
	TimeSpan span3 = span1.Subtract(span2);
	Console.WriteLine(span3);
    }
}

Output

00:00:59

MaxValue, MinValue. We see the value returned when you access the MaxValue and MinValue fields, which are public static readonly fields. The MaxValue is equal to over ten million days. The MinValue is equal to negative ten million days.

Public Static Readonly

C# program that uses MaxValue and MinValue

using System;

class Program
{
    static void Main()
    {
	// Write the maximum, minimum and zero values for TimeSpan.
	Console.WriteLine(TimeSpan.MaxValue);
	Console.WriteLine(TimeSpan.MinValue);
	Console.WriteLine(TimeSpan.Zero);
    }
}

Output

10675199.02:48:05.4775807
-10675199.02:48:05.4775808
00:00:00

TicksPer constants. We look at the values of the TicksPerDay, TicksPerHour, TicksPerMinute, TicksPerSecond, and TicksPerMillisecond constants. These are constants and can be accessed with the composite name of the TimeSpan type.

Const

Tip: The constants show how many ticks occur in each of these normal time units. There are 10,000 ticks in one millisecond.

C# program that uses TicksPer constants

using System;

class Program
{
    static void Main()
    {
	// Write the values for these Ticks Per constants.
	Console.WriteLine(TimeSpan.TicksPerDay);
	Console.WriteLine(TimeSpan.TicksPerHour);
	Console.WriteLine(TimeSpan.TicksPerMinute);
	Console.WriteLine(TimeSpan.TicksPerSecond);
	Console.WriteLine(TimeSpan.TicksPerMillisecond);
    }
}

Output

864000000000
36000000000
600000000
10000000
10000

Duration. You can use the Duration static method on the TimeSpan type. This method takes the TimeSpan instance and converts it to the absolute value of itself. If you have a negative TimeSpan, this method will make the TimeSpan positive.

Static

C# that uses Duration parameterless method

using System;

class Program
{
    static void Main()
    {
	// Use the TimeSpan Duration method.
	// ... This converts negative TimeSpans into positive TimeSpans.
	// ... Same as absolute value of the time.
	TimeSpan span = new TimeSpan(-1, -1, -1);
	TimeSpan duration = span.Duration();
	Console.WriteLine(duration);
    }
}

Output

01:01:01

Hours vs. TotalHours. Here we demonstrate the difference between the Hours instance property on TimeSpan, and the TotalHours instance property. This also applies to other properties such as Seconds and TotalSeconds, and Days and TotalDays.

Note: The Hours property returns the component of the TimeSpan that indicates hours. This is only a part of the entire time represented.

Note 2: The TotalHours property returns the entire time represented converted to a value represented in hours.

C# that uses Hours and TotalHours

using System;

class Program
{
    static void Main()
    {
	// Shows the TimeSpan constructor, Hours and TotalHours.
	// ... Hours is only a part of the time.
	// ... TotalHours converts the entire time to hours.
	TimeSpan span = new TimeSpan(0, 500, 0, 0, 0);
	Console.WriteLine(span.Hours);
	Console.WriteLine(span.TotalHours);
    }
}

Output

20
500

Zero. The TimeSpan.Zero field is a public static field and it provides the exact representation of no time. The Zero field is useful because you cannot directly change the internal representation of the TimeSpan.

C# that uses TimeSpan.Zero value

using System;

class Program
{
    static void Main()
    {
	// Demonstrate TimeSpan zero.
	TimeSpan span = TimeSpan.Zero;
	Console.WriteLine(span);
	Console.WriteLine(span.TotalMilliseconds);
    }
}

Output

00:00:00
0

When you access the TimeSpan.Zero field, the "load static field" intermediate language instruction is executed. This pushes the value onto the evaluation stack. Then, further instructions can use the value of the field.

Internally, the TimeSpan.Zero field is initialized in a static constructor in the TimeSpan type. It uses the TimeSpan constructor where the only argument is a long value of ticks. The argument 0L is used. This is zero in long format.

Note: In the TimeSpan(long) constructor, the field of name "_ticks" is assigned to the parameter. TimeSpan.Zero equals "new TimeSpan(0)".

TimeSpan constructor: C#

static TimeSpan()
{
    Zero = new TimeSpan(0L);
    MaxValue = new TimeSpan(9223372036854775807L);
    MinValue = new TimeSpan(-9223372036854775808L);
}

Parse, TryParse. Next, the Parse and TryParse methods are useful when reading in TimeSpans that may have been persisted as strings to files. The Parse and TryParse methods have similar internal logic.

But: TryParse is safer and faster for when you may encounter errors in the data, and it is usually better to use for this case.

C# that uses Parse and TryParse on TimeSpan

using System;

class Program
{
    static void Main()
    {
	// Use TimeSpan.Parse method to parse in span string.
	// ... Write it to the console.
	TimeSpan span = TimeSpan.Parse("0:00:01");
	Console.WriteLine(span);

	// Use TimeSpan.TryParse to try to parse an invalid span.
	// ... The result is TimeSpan.Zero.
	TimeSpan span2;
	TimeSpan.TryParse("X:00:01", out span2);
	Console.WriteLine(span2);
    }
}

Output

00:00:01
00:00:00

This program first parses an entirely valid time span string. It specifies a span with zero hours, zero minutes, and one second. The program prints out the corresponding TimeSpan struct.

Console.WriteLine

Also, the program uses TryParse on an invalid time span string. This causes no exception to be thrown. If you were to use Parse on an invalid string, an exception would be thrown.

Performance. Usually TimeSpan instances are not a performance concern, but in many programs TimeSpans are used on hot paths. For the benchmark, I compared creating a new TimeSpan with its FromHours method to the TimeSpan constructor.

C# that benchmarks TimeSpan

using System;
using System.Diagnostics;

class Program
{
    static void Main()
    {
	const int m = 100000000;
	Stopwatch s1 = Stopwatch.StartNew();
	for (int i = 0; i < m; i++)
	{
	    TimeSpan span = TimeSpan.FromHours(1);
	}
	s1.Stop();
	Stopwatch s2 = Stopwatch.StartNew();
	for (int i = 0; i < m; i++)
	{
	    TimeSpan span = new TimeSpan(1, 0, 0);
	}
	s2.Stop();
	Stopwatch s3 = Stopwatch.StartNew();
	TimeSpan cache = new TimeSpan(1, 0, 0);
	for (int i = 0; i < m; i++)
	{
	    TimeSpan span = cache;
	}
	s3.Stop();
	Console.WriteLine("{0},{1},{2}", s1.ElapsedMilliseconds,
	    s2.ElapsedMilliseconds, s3.ElapsedMilliseconds);
	Console.Read();
    }
}

What I found. The code that uses TimeSpan.FromHours is far slower than the other two examples. Using the TimeSpan constructor with three parameters [new TimeSpan(1, 0, 0)] was over two times faster.

TimeSpan performance test

TimeSpan.FromHours(1): 1788 ms
new TimeSpan(1, 0, 0):  989 ms
Cache:                   31 ms

I discovered this when looking into the implementation of TimeSpan.FromHours. I saw some complicated logic. TimeSpan.FromHours has these instructions: 1 check, 1 multiply, 1 add, 1 check, 2 checks, 1 multiply, 1 cast, 1 constructor.

Avoid these TimeSpan methods

TimeSpan.FromDays
TimeSpan.FromHours
TimeSpan.FromMilliseconds
TimeSpan.FromMinutes
TimeSpan.FromSeconds

Prefer these TimeSpan constructors

new TimeSpan(long)
new TimeSpan(int, int int)

Tip: You can improve performance when using TimeSpan instances. When using dates and times, cache TimeSpans you will need repeatedly.

Summary. We looked at many aspects of the TimeSpan struct type in the C# language. This type is a useful representation of periods of time in your programs. It provides many helper methods and properties to improve time calculations.

Also: Certain other types, such as Stopwatch, use TimeSpans for their representations.

Stopwatch

Related Links