C# Dictionary

The `Dictionary<TKey, TValue>` class in C# is a part of the `System.Collections.Generic` namespace and represents a collection of key-value pairs that are organized based on the key. It provides fast lookups, additions, and deletions of elements based on the key. Understanding `Dictionary<TKey, TValue>` is essential for efficient data management, especially when quick retrieval of data is required.

Table of Contents

1. Introduction to Dictionary<TKey, TValue>
- What is Dictionary<TKey, TValue>?
- Benefits of Using Dictionary<TKey, TValue>

2. Declaring and Initializing Dictionary<TKey, TValue>
- Declaration Syntax
- Initialization Methods
- Collection Initializers

3. Adding and Removing Elements
- Adding Elements
- Adding Range of Elements
- Removing Elements
- Clearing the Dictionary

4. Accessing Elements
- By Key
- Using TryGetValue
- Using ContainsKey and ContainsValue
- Iterating over Keys and Values

5. Iterating Through Dictionary<TKey, TValue>
- Using foreach Loop
- Iterating over Keys and Values Separately

6. Searching and Sorting
- Searching for Keys or Values
- Sorting Dictionaries

7. Capacity and Performance
- Understanding Capacity vs. Count
- Managing Capacity
- Performance Considerations

8. Common Methods and Properties
- Key Methods
- Important Properties

9. Best Practices
- Choosing the Right Key Type
- Avoiding Duplicate Keys
- Handling KeyNotFoundException
- Using ReadOnly Dictionaries
- Initializing with Capacity
- Using Appropriate Equality Comparers

10. Common Mistakes with Dictionary<TKey, TValue>
- Duplicate Keys
- Not Checking for Key Existence
- Modifying During Iteration
- Using Mutable Types as Keys

11. Advanced Topics
- Custom Comparers
- Thread Safety
- Serialization
- Enumerating in Different Ways
- ConcurrentDictionary and Thread-Safe Operations
- Using Immutable Dictionaries

12. Real-World Example
13. Summary

1. Introduction to Dictionary<TKey, TValue>

What is Dictionary<TKey, TValue>?

using System.Collections.Generic;

Dictionary<TKey, TValue> dictionary = new Dictionary<TKey, TValue>();

Benefits of Using Dictionary<TKey, TValue>

2. Declaring and Initializing Dictionary<TKey, TValue>

2.1 Declaration Syntax

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        Dictionary<int, string> studentGrades = new Dictionary<int, string>();
    }
}

2.2 Initialization Methods

Dictionary<string, int> wordCounts = new Dictionary<string, int>();

Dictionary<string, int> wordCounts = new Dictionary<string, int>(100);

2.3 Collection Initializers

Dictionary<int, string> employeeMap = new Dictionary<int, string>
{
    { 101, "Alice" },
    { 102, "Bob" },
    { 103, "Charlie" }
};

3. Adding and Removing Elements

3.1 Adding Elements

employeeMap.Add(104, "David");

employeeMap[105] = "Eve"; // Adds if key 105 doesn't exist, updates if it does

3.2 Adding Range of Elements

var newEmployees = new Dictionary<int, string>
{
    { 106, "Frank" },
    { 107, "Grace" }
};

foreach(var kvp in newEmployees)
{
    employeeMap.Add(kvp.Key, kvp.Value);
}

3.3 Removing Elements

employeeMap.Remove(102); // Removes the key-value pair with key 102

employeeMap.Clear();

3.4 Clearing the Dictionary

employeeMap.Clear();

4. Accessing Elements

4.1 By Key

string employeeName = employeeMap[101]; // Retrieves "Alice"

4.2 Using TryGetValue

if(employeeMap.TryGetValue(102, out string name))
{
    Console.WriteLine($"Employee 102: {name}");
}
else
{
    Console.WriteLine("Employee 102 not found.");
}

4.3 Using ContainsKey and ContainsValue

bool hasKey = employeeMap.ContainsKey(103); // true or false

bool hasValue = employeeMap.ContainsValue("Eve"); // true or false

4.4 Iterating over Keys and Values

foreach(int key in employeeMap.Keys)
{
    Console.WriteLine(key);
}

foreach(string value in employeeMap.Values)
{
    Console.WriteLine(value);
}

5. Iterating Through Dictionary<TKey, TValue>

5.1 Using foreach Loop

foreach(KeyValuePair<int, string> kvp in employeeMap)
{
    Console.WriteLine($"ID: {kvp.Key}, Name: {kvp.Value}");
}

5.2 Iterating over Keys and Values Separately

foreach(int key in employeeMap.Keys)
{
    Console.WriteLine($"Key: {key}");
}

foreach(string name in employeeMap.Values)
{
    Console.WriteLine($"Name: {name}");
}

6. Searching and Sorting

6.1 Searching for Keys or Values

bool exists = employeeMap.ContainsKey(104); // true or false

bool exists = employeeMap.ContainsValue("Bob"); // true or false

6.2 Sorting Dictionaries

var sortedByKey = employeeMap.OrderBy(kvp => kvp.Key);

Console.WriteLine("Sorted by Key:");
foreach(var kvp in sortedByKey)
{
    Console.WriteLine($"ID: {kvp.Key}, Name: {kvp.Value}");
}

var sortedByValue = employeeMap.OrderBy(kvp => kvp.Value);

Console.WriteLine("Sorted by Value:");
foreach(var kvp in sortedByValue)
{
    Console.WriteLine($"ID: {kvp.Key}, Name: {kvp.Value}");
}

7. Capacity and Performance

7.1 Understanding Capacity vs. Count

Dictionary<int, string> dict = new Dictionary<int, string>();
Console.WriteLine($"Initial Capacity: {dict.Count}"); // Output: 0

dict.Add(1, "One");
Console.WriteLine($"Count after adding one element: {dict.Count}"); // Output: 1

dict.Add(2, "Two");
Console.WriteLine($"Count after adding two elements: {dict.Count}"); // Output: 2

7.2 Managing Capacity

employeeMap.EnsureCapacity(200);

employeeMap.TrimExcess();

7.3 Performance Considerations

8. Common Methods and Properties

8.1 Key Methods

8.2 Important Properties

9. Best Practices

9.1 Choosing the Right Key Type

Dictionary<Guid, string> guidMap = new Dictionary<Guid, string>();
Guid key = Guid.NewGuid();
guidMap.Add(key, "UniqueValue");

9.2 Avoiding Duplicate Keys

bool added = employeeMap.TryAdd(108, "Hannah");
if(!added)
{
    Console.WriteLine("Key already exists.");
}

9.3 Handling KeyNotFoundException

if(employeeMap.TryGetValue(109, out string name))
{
    Console.WriteLine($"Employee 109: {name}");
}
else
{
    Console.WriteLine("Employee 109 not found.");
}

9.4 Using ReadOnly Dictionaries

using System.Collections.ObjectModel;

ReadOnlyDictionary<int, string> readOnlyDict = new ReadOnlyDictionary<int, string>(employeeMap);

9.5 Initializing with Capacity

Dictionary<int, string> largeDict = new Dictionary<int, string>(1000);

9.6 Using Appropriate Equality Comparers

public class CaseInsensitiveComparer : IEqualityComparer
{
    public bool Equals(string x, string y)
    {
        return string.Equals(x, y, StringComparison.OrdinalIgnoreCase);
    }

    public int GetHashCode(string obj)
    {
        return obj.ToLower().GetHashCode();
    }
}

// Usage
Dictionary<string, int> caseInsensitiveDict = new Dictionary<string, int>(new CaseInsensitiveComparer());
caseInsensitiveDict.Add("Key", 1);
bool exists = caseInsensitiveDict.ContainsKey("key"); // true

10. Common Mistakes with Dictionary<TKey, TValue>

10.1 Duplicate Keys

employeeMap.Add(101, "Alice"); // Throws ArgumentException if key 101 exists

10.2 Not Checking for Key Existence

string name = employeeMap[110]; // Throws exception if key 110 doesn't exist

10.3 Modifying the Dictionary During Iteration

foreach(var kvp in employeeMap)
{
    if(kvp.Key == 101)
    {
        employeeMap.Remove(kvp.Key); // InvalidOperationException
    }
}

foreach(var key in employeeMap.Keys.ToList())
{
    if(key == 101)
    {
        employeeMap.Remove(key);
    }
}

10.4 Using Mutable Types as Keys

public class Person
{
    public string Name { get; set; }
    // Mutable property affecting hash code
}

Dictionary<Person, int> personDict = new Dictionary<Person, int>();
Person p = new Person { Name = "Alice" };
personDict.Add(p, 1);

// Modifying the key after adding
p.Name = "Alicia"; // Alters the hash code

11. Advanced Topics

11.1 Custom Comparers

public class CaseInsensitiveStringComparer : IEqualityComparer
{
    public bool Equals(string x, string y)
    {
        return string.Equals(x, y, StringComparison.OrdinalIgnoreCase);
    }

    public int GetHashCode(string obj)
    {
        return obj.ToLower().GetHashCode();
    }
}

// Usage
Dictionary<string, int> ciDict = new Dictionary<string, int>(new CaseInsensitiveStringComparer());
ciDict.Add("Key", 1);
bool exists = ciDict.ContainsKey("key"); // true

11.2 Thread Safety

using System;
using System.Collections.Generic;
using System.Threading.Tasks;

class Program
{
    static Dictionary<int, string> employeeMap = new Dictionary<int, string>();
    static object lockObj = new object();

    static void Main()
    {
        Parallel.For(0, 1000, i =>
        {
            lock(lockObj)
            {
                employeeMap[i] = $"Employee{i}";
            }
        });

        Console.WriteLine($"Total Employees: {employeeMap.Count}"); // Output: 1000
    }
}

11.3 Serialization

using System;
using System.Collections.Generic;
using System.Text.Json;

class Program
{
    static void Main()
    {
        Dictionary<int, string> employeeMap = new Dictionary<int, string>
        {
            { 101, "Alice" },
            { 102, "Bob" }
        };

        string json = JsonSerializer.Serialize(employeeMap);
        Console.WriteLine(json); // Output: {"101":"Alice","102":"Bob"}
    }
}

11.4 Enumerating in Different Ways

foreach(int key in employeeMap.Keys)
{
    Console.WriteLine(key);
}

foreach(string value in employeeMap.Values)
{
    Console.WriteLine(value);
}

foreach(var kvp in employeeMap)
{
    Console.WriteLine($"Key: {kvp.Key}, Value: {kvp.Value}");
}

11.5 ConcurrentDictionary and Thread-Safe Operations

using System;
using System.Collections.Concurrent;
using System.Threading.Tasks;

class Program
{
    static ConcurrentDictionary<int, string> concurrentDict = new ConcurrentDictionary<int, string>();

    static void Main()
    {
        Parallel.For(0, 1000, i =>
        {
            concurrentDict.TryAdd(i, $"Employee{i}");
        });

        Console.WriteLine($"Total Employees: {concurrentDict.Count}"); // Output: 1000
    }
}

11.6 Using Immutable Dictionaries

using System;
using System.Collections.Immutable;

class Program
{
    static void Main()
    {
        var builder = ImmutableDictionary.CreateBuilder<int, string>();
        builder.Add(101, "Alice");
        builder.Add(102, "Bob");
        ImmutableDictionary<int, string> immutableDict = builder.ToImmutable();

        Console.WriteLine("Immutable Dictionary:");
        foreach(var kvp in immutableDict)
        {
            Console.WriteLine($"ID: {kvp.Key}, Name: {kvp.Value}");
        }
    }
}

12. Real-World Example

Example: Employee Directory Management Using Dictionary<TKey, TValue>

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        EmployeeDirectory directory = new EmployeeDirectory();

        // Adding employees
        directory.AddEmployee(new Employee { Id = 101, Name = "Alice", Position = "Developer" });
        directory.AddEmployee(new Employee { Id = 102, Name = "Bob", Position = "Designer" });
        directory.AddEmployee(new Employee { Id = 103, Name = "Charlie", Position = "Manager" });

        // Display all employees
        Console.WriteLine("All Employees:");
        directory.DisplayAllEmployees();

        // Search for an employee
        Console.WriteLine("\nSearching for Employee with ID 102:");
        var employee = directory.GetEmployeeById(102);
        if(employee != null)
        {
            Console.WriteLine(employee);
        }
        else
        {
            Console.WriteLine("Employee not found.");
        }

        // Update an employee's position
        Console.WriteLine("\nUpdating Employee with ID 103:");
        directory.UpdateEmployeePosition(103, "Senior Manager");
        directory.DisplayAllEmployees();

        // Remove an employee
        Console.WriteLine("\nRemoving Employee with ID 101:");
        directory.RemoveEmployee(101);
        directory.DisplayAllEmployees();

        // Attempt to add a duplicate employee
        Console.WriteLine("\nAttempting to Add Employee with Duplicate ID 102:");
        directory.AddEmployee(new Employee { Id = 102, Name = "David", Position = "Intern" });
    }
}

public class Employee
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Position { get; set; }

    public override string ToString()
    {
        return $"ID: {Id}, Name: {Name}, Position: {Position}";
    }
}

public class EmployeeDirectory
{
    private Dictionary<int, Employee> employees = new Dictionary<int, Employee>();

    public void AddEmployee(Employee employee)
    {
        if(employees.ContainsKey(employee.Id))
        {
            Console.WriteLine($"Error: Employee with ID {employee.Id} already exists.");
            return;
        }
        employees.Add(employee.Id, employee);
        Console.WriteLine($"Added Employee: {employee.Name}");
    }

    public Employee GetEmployeeById(int id)
    {
        if(employees.TryGetValue(id, out Employee employee))
        {
            return employee;
        }
        return null;
    }

    public void UpdateEmployeePosition(int id, string newPosition)
    {
        if(employees.TryGetValue(id, out Employee employee))
        {
            employee.Position = newPosition;
            Console.WriteLine($"Updated Position for Employee ID {id} to {newPosition}.");
        }
        else
        {
            Console.WriteLine($"Error: Employee with ID {id} not found.");
        }
    }

    public void RemoveEmployee(int id)
    {
        if(employees.Remove(id))
        {
            Console.WriteLine($"Removed Employee with ID {id}.");
        }
        else
        {
            Console.WriteLine($"Error: Employee with ID {id} not found.");
        }
    }

    public void DisplayAllEmployees()
    {
        foreach(var kvp in employees)
        {
            Console.WriteLine(kvp.Value);
        }
    }
}

Sample Output:
Added Employee: Alice
Added Employee: Bob
Added Employee: Charlie
All Employees:
ID: 101, Name: Alice, Position: Developer
ID: 102, Name: Bob, Position: Designer
ID: 103, Name: Charlie, Position: Manager
Searching for Employee with ID 102:
ID: 102, Name: Bob, Position: Designer
Updating Employee with ID 103:
Updated Position for Employee ID 103 to Senior Manager.
All Employees:
ID: 101, Name: Alice, Position: Developer
ID: 102, Name: Bob, Position: Designer
ID: 103, Name: Charlie, Position: Senior Manager
Removing Employee with ID 101:
Removed Employee with ID 101.
All Employees:
ID: 102, Name: Bob, Position: Designer
ID: 103, Name: Charlie, Position: Senior Manager
Attempting to Add Employee with Duplicate ID 102:
Error: Employee with ID 102 already exists.

13. Summary