James Michael Hare

C#/.NET Little Wonders–The List<T> Range Methods

James Michael Hare — Fri, 24 Feb 2012 00:01:35 GMT

Once again, in this series of posts I look at the parts of the .NET Framework that may seem trivial, but can help improve your code by making it easier to write and maintain. The index of all my past little wonders posts can be found here.

LINQ has added so many goodies that can be used to query IEnumerable<T> sequences that it can be easy to lose sight of some of the methods that are unique to each of the collection classes. This week, we will look at the range series of methods in the List<T> collection, which are useful for getting, adding, inserting, and deleting ranges to/from a List<T>.

AddRange() – Appends a sequence to end

Sometimes, you may have a list of items and need to append another sequence of items to the end of a List<T>. The AddRange() method can be used for this very purpose:

AddRange(IEnumerable<T> sequence)
- Adds the elements of the sequence of type T to the end of the List<T>.

The elements of the sequence are added to the end of the existing list. If the list is empty, the elements from the sequence will be the only thing in the list. If the sequence itself is empty, the list will be unchanged.

   1: var primes = new[] {2, 3, 5, 7, 11 };   2: var list = new List<int>();   3:     4: // list was empty, now contains 2, 3, 5, 7, 11   5: list.AddRange(primes);   6:     7: // list still contains 2, 3, 5, 7, 11 since seqeunce empty   8: list.AddRange(Enumerable.Empty<int>());   9:    10: // list now contains 2, 3, 5, 7, 11, 13, 17  11: list.AddRange(new[] { 13, 17 });

This method can be very handy if you are looking to consolidate the results from several methods that return sequences into one List<T>, you could construct a List<T> and then use AddRange() to add each subsequent result sequence at the end of the list:

   1: var allSymbols = new List<string>();    2:     3: foreach (var securityType in availableTypes)   4: {           5:     IEnumerable<string> symbolsForType = GetSymbols(securityType);        6:        7:     // AddRange() adds sequence to end of list       8:     allSymbols.AddRange(symbolsForType);   9: }   10:    11: // allSymbols now contains all of the results  12: return allSymbols;

While AddRange() does not cause any elements of the existing List<T> to need to shift, it may cause a re-allocation if the new size of the list would exceed it’s current capacity.

Also, we could accomplish something similar with Linq’s Enumerable.Concat() extension method, but since the LINQ extension methods tend to be query-only and not mutate the sequence, we would have to create a new List<T> containing the combined sequences and then assign it back to the original, which is not as efficient:

   1: var list = new List<int> { 2, 3, 5, 7 };   2: var more = new[] { 9, 11 };   3:     4: // This is logically identical to list.AddRange(more),   5: // but less efficient   6: list = list.Concat(more).ToList();

InsertRange() – Inserts a sequence of items at a given position

The InsertRange() method is very similar to AddRange(), except that InsertRange() allows you to specify an index of between 0 and the list’s Count where the sequence should be inserted. It’s format is:

InsertRange(int index, IEnumerable<T> sequence)
- Inserts the sequence of type T into the List<T> at the index specified. All elements currently at the specified index and beyond will be moved after the inserted sequence.

If the index is 0, then the sequence will be inserted before everything else in the list, and if the index is equal to the list’s Count, then the new sequence will be appended to the end of the list (exactly as if AddRange() was called).

That is, the following two calls are identical:

   1: // AddRange() adds to end      2: someList.AddRange(aSequence);       3:     4: // same as InsertRange() with index == Count      5: someList.InsertRange(someList.Count, aSequence);

Thus, given various indexes, you can insert items at any valid position, moving all items at that index and beyond down to make room for the new items from the sequence:

   1: var primes = new List<int>();    2:     3: // when list is empty, can only insert at 0 (the Count)   4: primes.InsertRange(0, new[] { 2, 3 });    5:     6: // inserting at position 2 in a list of size 2 appends to end   7: // list is now 2, 3, 11, 13   8: primes.InsertRange(2, new[] { 11, 13 });    9:    10: // inserting again at position 2 moves the 11 and 13 down  11: // list is now 2, 3, 5, 7, 11, 13  12: primes.InsertRange(2, new[] { 5, 7 });

This is a good general purpose method for inserting sequences anywhere in a List<T>, though obviously if you just want to append the sequence to the end, AddRange() is more readable.

Because InsertRange() adds a sequence, possibly in the middle or beginning of the list, this can cause the rest of the elements to need to be shifted down to make room for the new sequence, which may in turn cause a reallocation to occur if the resulting size exceeds the list’s current capacity.

RemoveRange() – Removes elements at given position

Just as AddRange() and InsertRange() can be used to add elements from a sequence into a List<T>, the RemoveRange() method can be used to remove elements from the List<T>. The basic format of the RemoveRange() method is:

RemoveRange(int index, int count)
- Removes the specified count of items from the List<T> starting at the specified index. The index and count must specify a valid range.

Note the last part about the index and count needing to specify a valid range. That is, you cannot specify a range beyond the bounds of the List<T>. This means that the index can go from 0 to the list’s Count property, and the count can go from 0 to the list’s Count – index.

So, in short, if you are removing items from the list at position index, then you may remove up to but not over a count of the list’s Count – index. For example, assume that list1, list2, list3, and list4 all contain exactly four items. In that case, you could remove any of the following:

   1: // remove four items starting at index 0   2: list1.RemoveRange(0, 4);   3:     4: // remove three items starting at index 1   5: list2.RemoveRange(1, 3);   6:     7: // remove two items starting at index 2   8: list3.RemoveRange(2, 2);   9:    10: // remove one item starting at index 3  11: list4.RemoveRange(3, 1);   12:    13: // remove no items starting at index 4  14: list5.RemoveRange(4, 0);

So, this is useful for removing items from the middle of a List<T>, but be aware that this causes the remainder of the list to need to shift down to fill the gap, which can be non-trivial. However, it will not require a reallocation of the list because the size is potentially shrinking, not growing.

GetRange() – Retrieve elements from a given position

So, we’ve seen how to manipulate a List<T> to add and remove ranges of elements, but another useful thing is to be able to get a “sub-list” of a list (much like a substring of a string). While RemoveRange() can be used to remove a range, it doesn’t return them, it simply removes them. If we want to query a range of elements, we need to use the GetRange():

GetRange(int index, int count)
- Returns a new List<T> containing the sequence of elements designated by the range specified. The range must be a valid range in the list.

Notice that just like RemoveRange(), the index and count specified must be valid. So again, the index can go from 0 to the list’s Count property, and the count can go from 0 to the list’s Count – index.

The results are returned in a List<T> of the appropriate length. Even if you ask for a range of zero elements, you will just get back an empty List<T>, not a null.

   1: var list = new List<int> { 2, 3, 5, 7, 9 };   2:     3: // range1 contains 2, 3, 5, 7, 9   4: var range1 = list.GetRange(0, 5);   5:     6: // range2 contains 7, 9   7: var range2 = list.GetRange(3, 2);   8:     9: // range3 contains nothing  10: var range3 = list.GetRange(5, 0);

Since GetRange() doesn’t modify the original list, there are no concerns about reallocating or shifting items and it performs very well. We could also accomplish this with LINQ’s Enumerable.Skip() and Enumerable.Take() of course, though it wouldn’t be quite as efficient:

   1: var list = new List<int> { 2, 3, 5, 7, 9 };   2:     3: // Roughly equivalent to list.GetRange(2, 3)   4: var subList = list.Skip(2).Take(3).ToList();

So GetRange() is very handy for creating a sub-list of a List<T>, which can be useful for partitioning work and other such tasks.

Summary

While LINQ gives a lot of power to query IEnumerable<T> sequences in general, many of the collections themselves have specialized methods that allow manipulation and efficient queries. In particular, the List<T> class contains four methods to query and manipulate ranges of items: AddRange(), InsertRange(), RemoveRange(), and GetRange().

Technorati Tags: C#, CSharp, .NET, Little Wonders, List<T>, ranges, AddRange, InsertRange, RemoveRange, GetRange

C#/.NET Little Wonders: The SequenceEqual() Method

James Michael Hare — Fri, 17 Feb 2012 01:14:56 GMT

First of all, thanks for all the well-wishers for me and my family, things are starting to settle down a bit, so I hope to be able to continue to blog at least on a bi-weekly basis – and I’m hoping to sprinkle in some C++ blog entries as well.

But for today, we’re going to look at a handy extension method defined in the Enumerable class that let’s us check two sequences for equality.

Introduction - Comparing Sequences

There are times, we want to check to sequences to see if they are equal. The basic definition of two equal sequences is if they have:

The same number of elements, and
The same values at each position in both sequences.

That is, two sequences are equal if the count of items are the same and the first elements have the same value, the second elements have the same value, etc.

So, for example, if we were comparing two arrays to see if they were equal, we could do something like this:

        1: public static bool EqualArrays<T>(T[] first, T[] second)

       2: {

       3:     // first check to make sure length same

       4:     if (first.Length != second.Length)

       5:     {

       6:         return false;

       7:     }

       8:  

       9:     // then examine item by item, stopping at the point not equal

      10:     for (int i = 0; i < first.Length; i++)

      11:     {

      12:         if (!Equals(first[i], second[i]))

      13:         {

      14:             return false;

      15:         }

      16:     }

      17:  

      18:     return true;

      19: }

But that only works for arrays, what if we wanted to make it more generic to cover any IEnumerable<T> sequences? Well, we can use the GetEnumerator() and modify the method to take IEnumerable<T> instance instead, like:

       1: public static bool EqualEnumerables<T>(IEnumerable<T> first, IEnumerable<T> second)

       2: {

       3:     // get enumerators

       4:     using (var firstPos = first.GetEnumerator())

       5:     using (var secondPos = second.GetEnumerator())

       6:     {

       7:         // move to next item

       8:         var hasFirst = firstPos.MoveNext();

       9:         var hasSecond = secondPos.MoveNext();

      10:  

      11:         // as long as both have an item

      12:         while (hasFirst && hasSecond)

      13:         {

      14:             // compare em

      15:             if(!Equals(firstPos.Current, secondPos.Current))

      16:             {

      17:                 return false;

      18:             }

      19:  

      20:             // advance to next items

      21:             hasFirst = firstPos.MoveNext();

      22:             hasSecond = secondPos.MoveNext();

      23:         }

      24:  

      25:         // if we are done, at least one sequence has run out, so they are equal

      26:         // if both are empty

      27:         return !hasFirst && !hasSecond;

      28:     }

      29: }

Fortunately, you don’t have to do any of this work, LINQ has already done this for you in an extension method called SequenceEqual().

SequenceEqual() – Compare two sequences for value equality

The Enumerable.SequenceEqual() extension method is a very general algorithm that compares any two sequences to make sure they have the same count of items, and the same value in each corresponding position.

It can determine the count much like my second code example above, where it will iterate through the sequences together, and the moment one of them runs out of elements it can simply make sure the other has no elements as well.

Now, on equality of the values, it will use the default comparer unless you specify an alternate comparer. Thus the two forms of SequenceEqual() extension method are as follows:

first.SequenceEqual(second)
- Compares the first sequence to the second using the EqualityComparer<T>.Default comparer for the their type.
first.SequenceEqual(second, comparer)
- Compares the first sequence to the second using the specified IEqualityComparer<T> comparer.

Since both of these are based solely on IEnumerable<T>, this means we can compare any two sequences of values as long as the type of value in the sequence is the same. That is, we can use this method to compare an int[] to a List<int> if we wish.

       1: var evens = new int[] { 2, 4, 6, 8, 10 };

       2: var odds = new List<int> { 1, 3, 5, 7, 9 };

       3:  

       4: // false, not same values

       5: Console.WriteLine("Evens and odds are same: " + 

       6:     evens.SequenceEqual(odds));

       7:  

       8: var evensAsList = evens.ToList();

       9:  

      10: // true, different containers, but same values

      11: Console.WriteLine("Evens array and evens list are same: " +

      12:     evens.SequenceEqual(evensAsList));

      13:  

      14: var evensBelowSeven = evens.TakeWhile(e => e < 7);

      15:  

      16: // false, same starting values but one sequence longer

      17: Console.WriteLine("Evens array and evens < 7 are same: " +

      18:     evens.SequenceEqual(evensBelowSeven));

Keep in mind with these methods that the order of the elements is the order the elements are iterated over, which may not be the original order added, based on whether the container is ordered, un-ordered, sorted, etc.

       1: var orderedNumbers = new int[] { 1, 200, 13, 57, 132 };

       2: var sortedNumbers = new SortedSet<int> { 1, 200, 13, 57, 132 };

       3:  

       4: // false, sortedNumbers will actually iterate as { 1, 13, 57, 132, 200 }

       5: Console.WriteLine("Ordered same as sorted: " +

       6:     orderedNumbers.SequenceEqual(sortedNumbers));

These methods can come in handy for comparing two sequences to make sure the number and order of the items is correct, which can be handy for a variety of needs.

Unit Testing - Using SequenceEqual() to test expected results

So what if you are wanting to verify a method returns a particular sequence of values in a unit test? For example, say we have a utility method which is a generator (returns a theoretically infinite sequence) of Fibonacci numbers (yes, this has overflow/safety concerns, but hey! It’s fun!):

       1: // A utility class that holds math utility functions.

       2: public static class MathUtility

       3: {

       4:     // This method returns the fibonacci sequence: 0, 1, 1, 2, 3, 5, 8, ... 

       5:     public static IEnumerable<int> GetFibonacciSequence()

       6:     {

       7:         int first = 0;

       8:         int second = 1;

       9:  

      10:         // first and second result are 0 and 1.

      11:         yield return first;

      12:         yield return second;

      13:  

      14:         // this enumerable sequence is bounded by the caller.

      15:         while(true)

      16:         {

      17:             // each subsequent number sum of previous two

      18:             int current = first + second;

      19:             yield return current;

      20:  

      21:             // wind up for next number if we're requesting one

      22:             first = second;

      23:             second = current;

      24:         }

      25:     }

      26: }

Remember that yield return creates an iterator which only returns the next value when it’s called for. Thus while the above looks like an infinite loop, in reality it depends how it’s being called. If we use a method to pull it such as Take(10), the method above will only yield 10 numbers and then halt. This is part of the magic of iterators and deferred execution!

But I digress, we can now use SequenceEqual() to easily check to see whether we get the results we expect for the first 10 values:

       1: [TestClass]

       2: public class FibonacciTest

       3: {

       4:     [TestMethod]

       5:     public void TestFirstTen()

       6:     {

       7:         var results = MathUtility.GetFibonacciSequence();

       8:  

       9:         Assert.IsTrue(results.Take(10).SequenceEqual(

      10:             new[] { 0, 1, 1, 2, 3, 5, 8, 13, 21, 34 }));

      11:     }

      12: }

And if we compile and run this test class in a unit test project, we will indeed see the Fibonacci method is indeed working as we expected!

So aside from everyday uses, the SequenceEqual() method is also very handy for checking expected results in unit tests as well.

Summary

LINQ adds many wonderful extension methods that can be called off of any implementation of IEnumerable<T>, one of these is the SequenceEqual() method that checks two sequences to see if they contain the same number of values, and the same value in each position of the sequence.

Technorati Tags: C#, CSharp, .NET, LINQ, Enumerable, IEnumerable<T>, SequenceEqual

Just slowing down a bit...

James Michael Hare — Thu, 02 Feb 2012 20:11:29 GMT

Given recent changes in my personal life with my son's diagnosis I will probably be blogging more on a bi-weekly basis instead of weekly for a while. I'm hoping this will be a temporary change until we get things all in order.

Also, I may be sprinkling in a few C++ posts as well to keep things fresh. I've been working on a C++ project as of late and though it is no longer my primary language, I still feel it has a lot of power and is worth knowing well.

Thanks for your understanding!

C#/.NET Little Pitfalls: Implicit Zero To Enum Conversion

James Michael Hare — Fri, 27 Jan 2012 00:31:44 GMT

C# is a wonderful language for modern programming. While everything in C# has a reason and a place, occasionally there are things that can be confusing for a developer who isn’t aware of what is happening behind the scenes. This is another post in the Little Pitfalls series where I explore these issues; an index of the Little Wonders and Little Pitfalls posts is here .

Many times, we create overloaded methods or constructors to allow them to accept different kinds of data. Further, there are times that we may accept object when any value will do. This works well (aside from boxing/unboxing concerns for value types), but if you have an overload that accepts object and one that takes an enum, and you pass a constant expression of 0, where does it go?

The Pitfall: Constant zero-value expressions are special

Let’s use a contrived example of a messaging framework where you can either construct messages with a specific payload, or construct a “basic” message which will have one of an enumerated set of “standard” payloads. For example, let’s say we allow these basic messages:

        1: public enum BasicMessage

       2: {

       3:     Ack,

       4:     Heartbeat,

       5: }

And we allow for a Message to be constructed either using an object, or from a BasicMessage:

       1: public class Message

       2: {

       3:     public string Detail { get; private set; }

       4:  

       5:     public Message(object messageDetail)

       6:     {

       7:         Detail = messageDetail.ToString();

       8:     }

       9:  

      10:     public Message(BasicMessage messageType)

      11:     {

      12:         switch (messageType)

      13:         {

      14:             case BasicMessage.Ack:

      15:                 Detail = "Acknowledgement";

      16:                 break;

      17:  

      18:             case BasicMessage.Heartbeat:

      19:                 Detail = "Heartbeat";

      20:                 break;

      21:  

      22:             default:

      23:                 Detail = "Unknown";

      24:                 break;

      25:         }

      26:     }

      27: }

Seems fine, right? So if we had something like:

       1: // Detail will be "This is a test message."

       2: var m1 = new Message("This is a test message.");

       3:  

       4: // Detail will be "3.1415927"

       5: var m2 = new Message(3.1415927);

       6:  

       7: // Detail will be "Acknowledgement"

       8: var m3 = new Message(BasicMessage.Ack);

       9:  

      10: Console.WriteLine(m1.Detail);

      11: Console.WriteLine(m2.Detail);

      12: Console.WriteLine(m3.Detail);

Everything looks fine and dandy. We see the output:

       1: This is a test message

       2: 3.1415927

       3: Acknowledgement

So it seems that our overloads work and we are able to handle both our special BasicMessage enumeration, and any other object, which will use the ToString() result on that object for the message details. It all sounds straightforward, but what if we had this:

       1: // We'd expect Detail to be "0"

       2: var m4 = new Message(0);

       3:  

       4: Console.WriteLine(m4.Detail);

We’d expect to get a “0”, but we don’t, we get “Acknowledgement” instead. What happened?

Well, it happens that any (well, nearly any – depending on .NET version) constant zero expression has an implicit conversion to any enum. In short, this means that .NET prefers to implicitly convert the 0 above into BasicMessage instead of an object. This is all according to the language specs which state:

An implicit enumeration conversion permits the decimal-integer-literal 0 to be converted to any enum-type and to any nullable-type whose underlying type is an enum-type. In the latter case the conversion is evaluated by converting to the underlying enum-type and wrapping the result.

For this to occur, it must be a constant zero expression. That is, it must involve literals or compile-time constants and no variables. In truth, depending on your .NET version, there are some const zero expressions that don’t qualify, but we won’t get too far in the weeds on which do or don’t (See Eric Lippert’s blog posts referenced in the summary for more details). The main point is to be prepared for the possibility of it happening. So, consider the following:

       1: // 0 is a constant literal, converts to the enum

       2: var m4 = new Message(0);

       3:  

       4: // still a const zero expression, converts to the enum

       5: var m5 = new Message(0 * 13);

       6:  

       7: const double IHaveNothing = 0.0;

       8:  

       9: // STILL a const zero value (double at that...), converts to the enum

      10: var m6 = new Message(IHaveNothing * 13);

      11:  

      12: // not a const zero expression, because involves a non-const variable, goes to object

      13: int x = 0;

      14: var m7 = new Message(x);

Curious, eh? Nearly any constant zero value will prefer to implicitly convert to an enum rather than an object if no other choice exists. This is true even if you attempt to force a cast to int, however casting to object would force it to the “correct” side:

       1: // The cast to int does nothing here, still const zero expression

       2: var m4 = new Message((int)0);

       3:  

       4: // This works, because it will box and then prefer object

       5: var m5 = new Message((object)0);

This also means that you can assign an enum a const zero expression as well:

       1: // complies, implicit conversion from const zero expression to enum

       2: BasicMessage b1 = 0;

       3:  

       4: // does not compile, must cast if non-zero or non-const

       5: BasicMessage b2 = 13;

In truth, the situations in which this happens seem to be contrived, yet you’d be surprised how many times this question comes up on sites like Stack Overflow. So how do we keep us from biting us?

The Solution: Make explicit overloads

First of all, this behavior is as designed, this is not a bug, so if this is ever not our desired behavior we should provide overloads for int and the other appropriate numeric value types (double, short, long, etc.) to prevent the issue.

In this way it won’t need to choose between object and an enum, but can directly match the appropriate numeric parameter. Just making an int overload isn’t always enough, this would not catch larger-than-int types like double, long, etc., and it would create an ambiguous overload error for smaller-than-int types like short, byte, etc. since now it can’t decide between the enum or the widening of the value type, as both are simple implicit conversions.

Thus, to really bullet-proof, we either need to have overloads for all the valid numeric value types:

       1: public Message(object messageDetail) { ... }

       2:  

       3: public Message(int messageDetail) { ... }

       4:  

       5: public Message(short messageDetail) { ... }

       6:  

       7: public Message(long messageDetail) { ... }

       8:  

       9: public Message(float messageDetail) { ... }

      10:  

      11: public Message(double messageDetail) { ... }

      12:  

      13: // etc for sbyte, byte, char, ushort, uint, ulong, and decimal

Or instead have a method with a generic type parameter. Note that this won’t work on overloading a constructor where the generic type parameter is not a generic type parameter of the class itself (can’t add generic type parameters to a constructor), but it will work on other methods where you may have a similar issue with overloads.

Summary

In short, when you are supplying overloads to handle many different values types, be aware that a constant zero expression can silently and implicitly convert to an enum instead of going to an object.

As such, if this is not the behavior you desire, make sure you have overloads for the primitive numeric types (or use a generic if possible), which also has the added benefit of avoiding boxing costs.

See Eric Lippert’s excellent blog entries “The Root of All Evil, Part One” and “The Root Of All Evil, Part Two” for more details on when and why this happens.

Technorati Tags: C#, CSharp, .NET, Little Pitfalls, enum, Enumeration

C#/.NET Little Pitfalls: Stopwatch Ticks are not TimeSpan Ticks

James Michael Hare — Fri, 13 Jan 2012 00:22:14 GMT

This week will be a short post since I’m travelling to Denver for design meetings, and otherwise spending most of my free time celebrating a birthday with friends and family. But I had a quick item to share that I’ve seen come up more than once on SO, so we’ll add it to the Little Pitfalls.

The System.Diagnostics.Stopwatch class is very useful for elapsed time measurements in .NET applications. Today we’ll look at the ElapsedTicks member of the Stopwatch class, and some of the confusion of what this quantity represents, especially compared to TimeSpan or DateTime Ticks.

The Stopwatch Class

While DateTime is fine for getting the current value of the date and time, it is not exactly precise or lightweight. Thus, when timing a process, a better way to go about this is to use the Stopwatch class from the System.Diagnostics namespace.

The Stopwatch was one of my first “Little Wonders” segments (here). I won’t repeat all of that information here, but as a quick refresher let’s take a look at a small example:

        1: // we could also create with new and then call Start(), 

       2: // but StartNew() does it all in one step

       3: var sw = Stopwatch.StartNew();

       4:  

       5: // Do some work here, for now, let's just sleep

       6: Thread.Sleep(5000);

       7:  

       8: sw.Stop();

       9:  

      10: Console.WriteLine("We slept for {0} ms", sw.ElapsedMilliseconds);

So, we create and start a Stopwatch instance by calling the factory method StartNew(), then perform the work we want to measure (in this case, just sleeping), and then Stop() our Stopwatch and see how many ElapsedMilliseconds have gone by. The results will vary somewhat (since Thread.Sleep() is not precise), but you would expect something like:

       1: The work took 4999 ms

So far, so good! There’s actually a few properties we can use to see how much time has passed between Start() – or StartNew() – and Stop():

Elapsed – Returns a TimeSpan with the elapsed time.
ElapsedMilliseconds – Returns a long with the number of elapsed milliseconds.
ElapsedTicks – Returns a long with the number of Stopwatch elapsed ticks.

The first two are self explanatory, the last needs a bit more explanation as it can be a source of confusion.

Pitfall - Stopwatch Ticks are machine/OS dependent

The thing to remember with ElapsedTicks is that the ticks represented in Stopwatch are based on a combination of the hardware of the machine and the operating system. Contrast this to DateTime and TimeSpan where Ticks are defined as 100 nanosecond intervals -- which is obviously machine/OS independent.

In short, that means that the following output values are (most likely) not going to be identical:

       1: var sw = Stopwatch.StartNew();

       2:  

       3: Thread.Sleep(5000);

       4:  

       5: sw.Stop();

       6:  

       7: // This one is the raw ticks of the Stopwatch and is machine dependent

       8: Console.WriteLine("ElapsedTicks is:  " + sw.ElapsedTicks);

       9:  

      10: // This one goes to a TimeSpan, which normalizes the Ticks

      11: // to 100 nanosecond intervals and is machine independent

      12: Console.WriteLine("Elapsed.Ticks is: " + sw.Elapsed.Ticks);

For example, if I run this on my current machine, I see the following output:

       1: ElapsedTicks are:  9973892461

       2: Elapsed.Ticks are: 49993947

Notice in my results that there are a lot more ElapsedTicks than Elapsed.Ticks! And, as I said, if you ran this on a different machine/OS combination, you could get a totally different magnitude of difference. This can be an issue when people think that the ElapsedTicks of the Stopwatch can be directly used to construct a TimeSpan (or DateTime):

       1: // Wrong!  The ticks are most likely completely different!

       2: var elapsedTime = new TimeSpan(sw.ElapsedTicks);

       3:  

       4: Console.WriteLine("Was it {0} or was it {1}",

       5:     sw.Elapsed, elapsedTime);

So if we tried to create a TimeSpan from ElapsedTicks instead DateTime/TimeSpan ticks, or instead of just using Elapsed (which returns an appropriate TimeSpan), we can get totally different values:

       1: Was it 00:00:04.9994341 or was it 00:16:37.3971203

There’s a big difference between four seconds and sixteen minutes! I’ve seen code like the above where the person using Stopwatch didn’t know its ticks were machine/OS dependent and thus made the mistake of using them to construct a TimeSpan instead of simply calling Elapsed to get one.

Sidebar: What’s the Frequency?

For those interested, you can convert from Stopwatch ticks to seconds by using the Stopwatch.Frequency static property, which tells you the ration of Stopwatch ticks per second. Thus these two are (roughly, due to precision differences) the same:

       1: // take the ElapsedTicks, then divide by Frequency to get seconds

       2: Console.WriteLine("ElapsedTicks to sec:  {0}", 

       3:     sw.ElapsedTicks / (double)Stopwatch.Frequency);

       4:  

       5: // take the Elapsed property, and query total number of seconds it represents

       6: Console.WriteLine("Elapsed.TotalSeconds: {0}", sw.Elapsed.TotalSeconds);

Which gives us results (on my machine) like:

       1: ElapsedTicks to sec:  4.9998583024032

       2: Elapsed.TotalSeconds: 4.9998583

Sidebar: Stopwatch is more efficient than DateTime.Now math

You may look at the Stopwatch and think why not just subtract two instances of DateTime.Now, like:

       1: var start = DateTime.Now;

       2:  

       3: // Do some work here, for now, let's just sleep

       4: Thread.Sleep(5000);

       5:  

       6: var stop = DateTime.Now;

       7:  

       8: Console.WriteLine("The code took: {0} ms", (stop - start).TotalMilliseconds);

There’s two reasons not to do this, though. First of all, the Stopwatch is generally more precise, and secondly, it’s more lightweight.

For example, running the same code using Stopwatch vs DateTime.Now math, the differences in computational speed for 1 million iterations are:

       1: DateTime math took: 1534 ms, 0.001534 ms/iteration.

       2: Stopwatch took: 70 ms, 7E-05 ms/iteration.

That’s a huge difference between the two! So when you want to measure elapsed time of a process running on a machine, strongly consider the Stopwatch.

Summary

In short, remember that the ticks in Stopwatch are machine/OS dependent, thus you should never count on the ration of Stopwatch ticks to seconds to be the same between two systems, and possibly even on the same system after a reboot. Thus, you can never count on Stopwatch ticks to be the same interval as DateTime/TimeSpan ticks.

To get system-independent time, make sure to use the Stopwatch’s Elapsed or ElapsedMilliseconds properties, which already take the Stopwatch.Frequency (ticks per second) into account.

Technorati Tags: C#, CSharp, .NET, Little Pitfalls, Stopwatch, TimeSpan, DateTime