RangeDictionary<TKey, TValue> Class

Definition

Namespace

Bodu.Collections.Generic

Assembly

Bodu.Collections.dll

Package

Bodu.Collections 1.0.0

Source

RangeDictionary{T,T}.Enumerator.cs

Represents a sorted dictionary that maps non-overlapping half-open ranges to values.

public sealed class RangeDictionary<TKey, TValue> : IReadOnlyCollection<ValueRange<TKey, TValue>>, IEnumerable<ValueRange<TKey, TValue>>, IEnumerable where TKey : IComparable<TKey>

Type Parameters

TKey

The comparable endpoint type.

TValue

The value type.

Inheritance

object

RangeDictionary<TKey, TValue>

Implements

IReadOnlyCollection<ValueRange<TKey, TValue>>

IEnumerable<ValueRange<TKey, TValue>>

IEnumerable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Examples

// Tax-bracket lookup: ranges are half-open and must not overlap.
var brackets = new RangeDictionary<decimal, decimal>
{
    {     0m,  18_200m, 0.00m },
    { 18_200m,  45_000m, 0.19m },
    { 45_000m, 135_000m, 0.30m },
};

if (brackets.TryGetValue(50_000m, out decimal rate))
    Console.WriteLine($"Rate: {rate:P0}"); // Rate: 30%

// Adjacent ranges are allowed; an overlapping insertion throws ArgumentException.
brackets.Add(135_000m, 190_000m, 0.37m);

Remarks

Entries are stored in three parallel arrays - one for the inclusive start of each range, one for the exclusive end, and one for the associated value. Lookups use binary search across the start endpoints, followed by a single end-boundary check. Insertions and removals shift the affected suffix of each array.

Ranges use half-open semantics: [startInclusive, endExclusive). Adjacent ranges are allowed; overlapping ranges are rejected with ArgumentException.

This type is not thread-safe.

Constructors

RangeDictionary()

Initializes a new instance of the RangeDictionary<TKey, TValue> class using the default endpoint comparer.

public RangeDictionary()

RangeDictionary(IComparer<TKey>?)

Initializes a new instance of the RangeDictionary<TKey, TValue> class using the specified comparer.

public RangeDictionary(IComparer<TKey>? comparer)

Parameters

comparer IComparer<TKey>

The endpoint comparer, or null to use Default.

Properties

Capacity

Gets the allocated range capacity.

public int Capacity { get; }

Property Value

int

The current allocated capacity of the underlying storage.

Comparer

Gets the comparer used to order range endpoints.

public IComparer<TKey> Comparer { get; }

Property Value

IComparer<TKey>

The active endpoint comparer.

Count

Gets the number of stored ranges.

public int Count { get; }

Property Value

int

The number of ranges currently stored in the dictionary.

this[TKey]

Gets the value associated with the range containing the specified key.

public TValue this[TKey key] { get; }

Parameters

key TKey

The key to locate. Must not be null.

Property Value

TValue

The value associated with the containing range.

Exceptions

ArgumentNullException

key is null.

KeyNotFoundException

No range contains key.

Methods

Add(ValueRange<TKey, TValue>)

Adds the specified range entry.

public void Add(ValueRange<TKey, TValue> entry)

Parameters

entry ValueRange<TKey, TValue>

The entry to add.

Exceptions

ArgumentException

The entry overlaps an existing range.

Add(TKey, TKey, TValue)

Adds a non-overlapping half-open range and its value.

public void Add(TKey startInclusive, TKey endExclusive, TValue value)

Parameters

startInclusive TKey

The inclusive start.

endExclusive TKey

The exclusive end.

value TValue

The value to associate with the range.

Exceptions

ArgumentNullException

startInclusive or endExclusive is null.

ArgumentException

startInclusive is greater than or equal to endExclusive, or the range overlaps an existing range.

Clear()

Removes all ranges from the dictionary.

public void Clear()

ContainsKey(TKey)

Determines whether any stored range contains the specified key.

public bool ContainsKey(TKey key)

Parameters

key TKey

The key to locate. Must not be null.

Returns

bool

true if a range contains the key; otherwise, false.

Exceptions

ArgumentNullException

key is null.

EnsureCapacity(int)

Ensures that the dictionary can hold at least the specified number of ranges without reallocating.

public int EnsureCapacity(int capacity)

Parameters

capacity int

The desired capacity.

Returns

int

The current capacity.

Exceptions

ArgumentOutOfRangeException

capacity is negative.

GetEntryAt(int)

Gets the range entry at the specified sorted index.

public ValueRange<TKey, TValue> GetEntryAt(int index)

Parameters

index int

The zero-based range index.

Returns

ValueRange<TKey, TValue>

The range entry at index.

Exceptions

ArgumentOutOfRangeException

index is negative or greater than or equal to Count.

GetEnumerator()

Returns an enumerator that iterates through the stored range entries in ascending order.

public RangeDictionary<TKey, TValue>.Enumerator GetEnumerator()

Returns

RangeDictionary<TKey, TValue>.Enumerator

An RangeDictionary<TKey, TValue>.Enumerator over the dictionary entries.

Overlaps(TKey, TKey)

Determines whether the specified range overlaps any existing range.

public bool Overlaps(TKey startInclusive, TKey endExclusive)

Parameters

startInclusive TKey

The inclusive start.

endExclusive TKey

The exclusive end.

Returns

bool

true if the range overlaps an existing range; otherwise, false.

Exceptions

ArgumentNullException

startInclusive or endExclusive is null.

ArgumentException

startInclusive is greater than or equal to endExclusive.

Remove(TKey, TKey)

Removes an exact range from the dictionary.

public bool Remove(TKey startInclusive, TKey endExclusive)

Parameters

startInclusive TKey

The inclusive start of the range.

endExclusive TKey

The exclusive end of the range.

Returns

bool

true if the exact range was removed; otherwise, false.

Exceptions

ArgumentNullException

startInclusive or endExclusive is null.

ArgumentException

startInclusive is greater than or equal to endExclusive.

ToArray()

Copies the stored range entries to a new array in ascending sorted order.

public ValueRange<TKey, TValue>[] ToArray()

Returns

ValueRange<TKey, TValue>[]

A new array containing the stored entries.

TryGetEntry(TKey, out ValueRange<TKey, TValue>)

Attempts to get the range entry containing the specified key.

public bool TryGetEntry(TKey key, out ValueRange<TKey, TValue> entry)

Parameters

key TKey

The key to locate. Must not be null.

entry ValueRange<TKey, TValue>

The containing range entry, if found.

Returns

bool

true if a range contains the key; otherwise, false.

Exceptions

ArgumentNullException

key is null.

TryGetValue(TKey, out TValue)

Attempts to get the value associated with the range containing the specified key.

public bool TryGetValue(TKey key, out TValue value)

Parameters

key TKey

The key to locate. Must not be null.

value TValue

The value associated with the containing range, if found.

Returns

bool

true if a range contains the key; otherwise, false.

Exceptions

ArgumentNullException

key is null.

Explicit Interface Implementations

IEnumerable<ValueRange<TKey, TValue>>.GetEnumerator()

Returns an enumerator that iterates through the collection.

IEnumerator<ValueRange<TKey, TValue>> IEnumerable<ValueRange<TKey, TValue>>.GetEnumerator()

Returns

IEnumerator<ValueRange<TKey, TValue>>

An enumerator that can be used to iterate through the collection.

IEnumerable.GetEnumerator()

Returns an enumerator that iterates through a collection.

IEnumerator IEnumerable.GetEnumerator()

Returns

IEnumerator

An IEnumerator object that can be used to iterate through the collection.

Applies to

Product	Versions
.NET	8, 10