C# Indexers Explained — Syntax, Real-World Use Cases and Pitfalls

using System;
using System.Collections.Generic;

/// <summary>
/// Stores hourly temperature readings for a single day.
/// Demonstrates the most fundamental indexer pattern.
/// </summary>
public class TemperatureLog
{
    // Internal storage — callers never touch this directly
    private readonly double[] _hourlyReadings = new double[24];

    // --- THE INDEXER ---
    // 'this[int hour]' is the syntax. 'hour' is the index parameter.
    // It behaves exactly like a property but accepts an argument.
    public double this[int hour]
    {
        get
        {
            // Validate before blindly returning data
            if (hour < 0 || hour > 23)
                throw new ArgumentOutOfRangeException(nameof(hour),
                    "Hour must be between 0 and 23.");

            return _hourlyReadings[hour];
        }
        set
        {
            if (hour < 0 || hour > 23)
                throw new ArgumentOutOfRangeException(nameof(hour),
                    "Hour must be between 0 and 23.");

            // 'value' is the implicit keyword, just like in a regular property setter
            _hourlyReadings[hour] = value;
        }
    }
}

class Program
{
    static void Main()
    {
        var todayLog = new TemperatureLog();

        // SET via indexer — reads just like array assignment
        todayLog[9]  = 18.5;   // 9 AM reading
        todayLog[12] = 22.1;   // noon reading
        todayLog[18] = 19.8;   // 6 PM reading

        // GET via indexer
        Console.WriteLine($"9 AM  : {todayLog[9]} °C");
        Console.WriteLine($"Noon  : {todayLog[12]} °C");
        Console.WriteLine($"6 PM  : {todayLog[18]} °C");

        // This will throw ArgumentOutOfRangeException — hour 25 is invalid
        try
        {
            double bad = todayLog[25];
        }
        catch (ArgumentOutOfRangeException ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}

using System;
using System.Collections.Generic;

/// <summary>
/// A simple key-value settings store with a string indexer.
/// Models the same access pattern as IConfiguration in ASP.NET Core.
/// </summary>
public class AppSettings
{
    // Backing store — private so callers can't manipulate it directly
    private readonly Dictionary<string, string> _settings
        = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);

    // String indexer — key is case-insensitive thanks to the comparer above
    public string? this[string key]
    {
        get
        {
            // Return null for missing keys instead of throwing —
            // lets callers use the null-coalescing operator cleanly
            return _settings.TryGetValue(key, out string? found) ? found : null;
        }
        set
        {
            if (string.IsNullOrWhiteSpace(key))
                throw new ArgumentException("Setting key cannot be empty.", nameof(key));

            if (value is null)
                // Treat assigning null as 'remove this setting'
                _settings.Remove(key);
            else
                _settings[key] = value;
        }
    }

    public int Count => _settings.Count;
}

class Program
{
    static void Main()
    {
        var settings = new AppSettings();

        // Write settings via indexer
        settings["Theme"]           = "Dark";
        settings["MaxRetries"]      = "3";
        settings["DatabaseTimeout"] = "30";

        // Read back — case-insensitive because of our StringComparer
        Console.WriteLine($"Theme: {settings["theme"]}");          // lowercase key still works
        Console.WriteLine($"Max retries: {settings["MaxRetries"]}");

        // Null-coalescing works great with a null-returning getter
        string timeout = settings["CacheTimeout"] ?? "60";  // key doesn't exist, use default
        Console.WriteLine($"Cache timeout (default): {timeout}s");

        // Remove a setting by assigning null
        settings["Theme"] = null;
        Console.WriteLine($"Theme after removal: {settings["Theme"] ?? "(not set)"}");

        Console.WriteLine($"Total settings remaining: {settings.Count}");
    }
}

using System;

/// <summary>
/// A simple 2D grid that supports both positional and Excel-style cell access.
/// Demonstrates multi-parameter indexers AND indexer overloading.
/// </summary>
public class SpreadsheetGrid
{
    private readonly string[,] _cells;
    public int Rows { get; }
    public int Columns { get; }

    public SpreadsheetGrid(int rows, int columns)
    {
        Rows    = rows;
        Columns = columns;
        _cells  = new string[rows, columns];
    }

    // OVERLOAD 1: Positional access — grid[row, col]
    // Multi-parameter indexers use a comma-separated list, just like multi-dim arrays
    public string this[int row, int col]
    {
        get
        {
            ValidateBounds(row, col);
            return _cells[row, col] ?? string.Empty;
        }
        set
        {
            ValidateBounds(row, col);
            _cells[row, col] = value;
        }
    }

    // OVERLOAD 2: Excel-style access — grid["B3"] means column B (index 1), row 3 (index 2)
    // This overload has a DIFFERENT parameter type (string vs int, int)
    // so the compiler knows which one to call
    public string this[string cellAddress]
    {
        get
        {
            (int row, int col) = ParseAddress(cellAddress);
            return this[row, col]; // delegate to the positional indexer — no code duplication
        }
        set
        {
            (int row, int col) = ParseAddress(cellAddress);
            this[row, col] = value; // same delegation pattern
        }
    }

    // Parses "B3" into (row: 2, col: 1) — zero-based
    private static (int row, int col) ParseAddress(string address)
    {
        if (string.IsNullOrEmpty(address) || address.Length < 2)
            throw new ArgumentException($"Invalid cell address: '{address}'");

        char columnLetter = char.ToUpper(address[0]);
        int col = columnLetter - 'A';                  // 'A' -> 0, 'B' -> 1, etc.
        int row = int.Parse(address[1..]) - 1;         // "3" -> row index 2 (zero-based)
        return (row, col);
    }

    private void ValidateBounds(int row, int col)
    {
        if (row < 0 || row >= Rows || col < 0 || col >= Columns)
            throw new ArgumentOutOfRangeException(
                $"Cell ({row},{col}) is outside grid bounds ({Rows}x{Columns}).");
    }
}

class Program
{
    static void Main()
    {
        var sheet = new SpreadsheetGrid(rows: 5, columns: 4);

        // Write using positional indexer (row, col) — zero-based
        sheet[0, 0] = "Name";
        sheet[0, 1] = "Score";
        sheet[1, 0] = "Alice";
        sheet[1, 1] = "95";

        // Write using Excel-style indexer — 1-based, column letter
        sheet["C1"] = "Grade";   // row 0, col 2
        sheet["C2"] = "A";       // row 1, col 2

        // Read using both styles — they access the same underlying data
        Console.WriteLine($"Positional [0,0]: {sheet[0, 0]}");
        Console.WriteLine($"Excel-style A1  : {sheet["A1"]}");
        Console.WriteLine();
        Console.WriteLine($"[0,1] = {sheet[0, 1]},  B1 = {sheet["B1"]}");  // same cell
        Console.WriteLine($"[1,0] = {sheet[1, 0]},  A2 = {sheet["A2"]}");  // same cell
        Console.WriteLine($"[1,2] = {sheet[1, 2]},  C2 = {sheet["C2"]}");  // same cell
    }
}

using System;
using System.Collections.Generic;

/// <summary>
/// Interface declares a read-only string indexer.
/// Any class implementing this can be swapped out or mocked in tests.
/// </summary>
public interface ICountryLookup
{
    // Read-only indexer in an interface — only 'get' is declared
    string? this[string isoCode] { get; }
    bool Contains(string isoCode);
}

/// <summary>
/// Concrete implementation — backed by a static dictionary.
/// Could be swapped for a database-backed version without changing callers.
/// </summary>
public class CountryCodeLookup : ICountryLookup
{
    private readonly Dictionary<string, string> _countries;

    public CountryCodeLookup()
    {
        // Pre-populated with a handful of ISO 3166-1 alpha-2 codes
        _countries = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
        {
            ["US"] = "United States",
            ["GB"] = "United Kingdom",
            ["DE"] = "Germany",
            ["JP"] = "Japan",
            ["BR"] = "Brazil"
        };
    }

    // Implements the interface's read-only indexer
    // The class itself only exposes get — there's no way for callers to pollute the data
    public string? this[string isoCode]
        => _countries.TryGetValue(isoCode, out string? name) ? name : null;

    public bool Contains(string isoCode) => _countries.ContainsKey(isoCode);
}

/// <summary>
/// Consumes ICountryLookup — it only knows about the interface,
/// not the concrete class. Fully testable.
/// </summary>
public class CountryReportGenerator
{
    private readonly ICountryLookup _lookup;

    public CountryReportGenerator(ICountryLookup lookup)
    {
        _lookup = lookup;
    }

    public void PrintCountryName(string isoCode)
    {
        // Uses the indexer through the interface reference
        string display = _lookup[isoCode] ?? $"Unknown ({isoCode})";
        Console.WriteLine($"{isoCode.ToUpper()} => {display}");
    }
}

class Program
{
    static void Main()
    {
        ICountryLookup lookup = new CountryCodeLookup();
        var generator = new CountryReportGenerator(lookup);

        generator.PrintCountryName("US");
        generator.PrintCountryName("gb");   // lowercase — case-insensitive
        generator.PrintCountryName("JP");
        generator.PrintCountryName("ZZ");   // not in the lookup

        // Direct interface usage — read-only, clean API
        Console.WriteLine();
        Console.WriteLine($"Contains 'DE': {lookup.Contains("DE")}");
        Console.WriteLine($"DE full name : {lookup["DE"]}");
    }
}