C# KeyValuePair Collection Hints

You need to store two values together in a single collection with the C# programming language. The KeyValuePair struct in System.Collections.Generic is ideal for this purpose, as it is simple and always available. Here we see ways you can use the KeyValueCollection struct in Lists, in methods, and in some algorithms.

Using KeyValuePair

First, this example shows how you can use KeyValuePair in a List, which is also in System.Collections.Generic. This is useful for storing pairs of values in a single List. Alternatively, you could use two separate Lists, but that can complicate matters.

=== Example code that uses KeyValuePair (C#) ===

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        //
        // Shows a List of KeyValuePairs.
        //
        var list = new List<KeyValuePair<string, int>>();
        list.Add(new KeyValuePair<string, int>("Cat", 1));
        list.Add(new KeyValuePair<string, int>("Dog", 2));
        list.Add(new KeyValuePair<string, int>("Rabbit", 4));

        foreach (var element in list)
        {
            Console.WriteLine(element);
        }
    }
}

=== Output of the example ===

[Cat, 1]
[Dog, 2]
[Rabbit, 4]

Hints for the example. This code example shows how you can initialize a new List of type KeyValuePair. Inside the brackets in the KeyValuePair, there are two types separated by a comma. This examples shows KeyValuePairs of one string and one int each.

How to create new KeyValuePairs. Here we see that you can create a new KeyValuePair with its constructor. The constructor is shown in the List.Add calls. The KeyValuePair's constructor returns the new KeyValuePair, and that instance is added.

Note on arrays. Instead of a List, you could use an array here. You can simply specify the KeyValuePair<string, int> as the type of the array. This would improve performance in many situations.

Returning two values

Often, you need to return two separate values from a method. You can do this very easily with KeyValuePair. You must specify the exact type in the return value, and then return the new KeyValuePair in the method body. This is clearer than a two-element array. Consider out or ref parameters instead.

~~~ Program that returns two values (C#) ~~~

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        Console.WriteLine(GetNames());
    }

    static KeyValuePair<string, string> GetNames()
    {
        //
        // Gets collection of first and last name.
        //
        string firstName = "William";
        string lastName = "Gates";
        return new KeyValuePair<string, string>(firstName, lastName);
    }
}

~~~ Output of the program ~~~

[William, Gates]

Read-only compilation error

When using KeyValuePair in your program, you will likely get this error at some point. The C# compiler doesn't allow you to assign the Key and Value properties. This must be assigned in the constructor.

Property or indexer 'System.Collections.Generic.KeyValuePair<int,int>.Key'
cannot be assigned to -- it is read only

Looping over Dictionary

Probably the most popular usage of KeyValuePair is in a loop over a Dictionary. The Dictionary collection in C# has an enumerator that returns each key and value in a KeyValuePair, one at a time. Examples are available.

(See Dictionary Examples, Keys and Values.)

Using KeyValuePair with var. An improved syntax could be to use the var keyword with the foreach loop over your Dictionary. This replaces the lengthy KeyValuePair type declaration with three letters.

(See Foreach Var Loop.)

Shuffling array

As shown in the first example, you may use KeyValuePair in a List to create two parallel Lists. These are very easily sorted, keeping both values together. This site has an example of an accurate shuffle algorithm with KeyValuePair and List.

(See Shuffle Array.)

Implementation

You should know what the basic layout of the KeyValuePair struct is. Here, we see the internal code using Reflector. The KeyValuePair has two private fields, and two public properties that retrieve the values of those fields. The constructor is also shown.

[Serializable, StructLayout(LayoutKind.Sequential)]
public struct KeyValuePair<TKey, TValue>
{
    private TKey key;
    private TValue value;
    public KeyValuePair(TKey key, TValue value);
    public TKey Key { get; }
    public TValue Value { get; }
    public override string ToString();
}

ToString method

The ToString method is very useful in KeyValuePair. In fact, when you want to display the values, simply call ToString() or pass the KeyValuePair to Console.Write or Console.WriteLine. This will implicitly call ToString(). Internally, ToString() uses a StringBuilder. This article is based on .NET 3.5 SP1.

Should I use KeyValuePair in my program?

Sometimes. In many cases, such as with internal method code, using KeyValuePair is very convenient and simple. However, using a class or struct you define yourself can definitely enhance the object-orientation of your program. The author suggests you prefer classes when the usage is non-trivial.

Summary

Here we saw examples of using KeyValuePair in the C# language, and also looked into its internals in the .NET framework. Lists and Dictionaries are ideal companions for KeyValuePairs. We also saw how you can return the collection from methods.

(Do not copy this page.)