OrderedSet<T> Class

Definition

Namespace

Bodu.Collections.Generic

Assembly

Bodu.Collections.dll

Package

Bodu.Collections 1.0.0

Source

OrderedSet{T}.Enumerator.cs

Represents an insertion-ordered set - a ISet<T> that preserves the order in which elements were first added and exposes that order through IReadOnlyList<T>.

public sealed class OrderedSet<T> : ISet<T>, ICollection<T>, IReadOnlyList<T>, IReadOnlyCollection<T>, IEnumerable<T>, IEnumerable where T : notnull

Type Parameters

T

The type of elements in the set. Elements must not be null.

Inheritance

object

OrderedSet<T>

Implements

ISet<T>

ICollection<T>

IReadOnlyList<T>

IReadOnlyCollection<T>

IEnumerable<T>

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

// De-duplicate a stream of tags while keeping the order in which each was first seen.
var tags = new OrderedSet<string>(StringComparer.OrdinalIgnoreCase);
tags.Add("alpha");
tags.Add("beta");
tags.Add("ALPHA"); // ignored - already present under the case-insensitive comparer
tags.Add("gamma");

Console.WriteLine(string.Join(", ", tags)); // alpha, beta, gamma
Console.WriteLine(tags[0]);                 // "alpha" - positional read via IReadOnlyList<T>

// Set algebra returns a new OrderedSet preserving the left operand's order.
var diff = new OrderedSet<string>(tags);
diff.ExceptWith(new[] { "beta" });

Remarks

OrderedSet<T> shares its backing storage with IndexedSet<T> via the internal Bodu.Collections.Generic.OrderedSetStorage<T> engine: a contiguous element array for deterministic insertion order plus an open-addressing hash table for O(1) Contains(T). No BCL collection types are used as backing storage.

The contract is strictly set-shaped: ISet<T> for mutation and set algebra, IReadOnlyList<T> for ordered iteration and positional read access. Positional mutation (Insert , RemoveAt, Move, indexer setter) is intentionally not exposed - use IndexedSet<T> when those operations are required.

This type is not thread-safe.

Constructors

OrderedSet()

Initializes a new instance of the OrderedSet<T> class using the default capacity and comparer.

public OrderedSet()

OrderedSet(IEnumerable<T>)

Initializes a new instance of the OrderedSet<T> class containing the unique elements from collection.

public OrderedSet(IEnumerable<T> collection)

Parameters

collection IEnumerable<T>

The source collection. Must not be null.

Exceptions

ArgumentNullException

collection is null.

OrderedSet(IEnumerable<T>, IEqualityComparer<T>?)

Initializes a new instance of the OrderedSet<T> class containing the unique elements from collection.

public OrderedSet(IEnumerable<T> collection, IEqualityComparer<T>? comparer)

Parameters

collection IEnumerable<T>

The source collection. Must not be null.

comparer IEqualityComparer<T>

The equality comparer, or null to use the default comparer.

Exceptions

ArgumentNullException

collection is null.

OrderedSet(IEqualityComparer<T>?)

Initializes a new instance of the OrderedSet<T> class using the specified comparer.

public OrderedSet(IEqualityComparer<T>? comparer)

Parameters

comparer IEqualityComparer<T>

The equality comparer, or null to use the default comparer.

OrderedSet(int)

Initializes a new instance of the OrderedSet<T> class with the specified initial capacity.

public OrderedSet(int capacity)

Parameters

capacity int

The initial element capacity.

Exceptions

ArgumentOutOfRangeException

capacity is negative.

OrderedSet(int, IEqualityComparer<T>?)

Initializes a new instance of the OrderedSet<T> class with the specified initial capacity and comparer.

public OrderedSet(int capacity, IEqualityComparer<T>? comparer)

Parameters

capacity int

The initial element capacity.

comparer IEqualityComparer<T>

The equality comparer, or null to use the default comparer.

Exceptions

ArgumentOutOfRangeException

capacity is negative.

Properties

Capacity

Gets the allocated element capacity.

public int Capacity { get; }

Property Value

int

The current allocated capacity of the underlying element storage.

Comparer

Gets the equality comparer used to compare elements.

public IEqualityComparer<T> Comparer { get; }

Property Value

IEqualityComparer<T>

The active equality comparer.

Count

Gets the number of elements in the set.

public int Count { get; }

Property Value

int

The number of elements currently stored in the set.

IsReadOnly

Gets a value indicating whether the set is read-only.

public bool IsReadOnly { get; }

Property Value

bool

Always false.

this[int]

Gets the element at the specified zero-based index in insertion order.

public T this[int index] { get; }

Parameters

index int

The zero-based index of the element to access.

Property Value

T

The element at index.

Exceptions

ArgumentOutOfRangeException

index is negative or greater than or equal to Count.

Methods

Add(T)

Adds the specified item to the set.

public bool Add(T item)

Parameters

item T

The item to add. Must not be null.

Returns

bool

true if the item was added; otherwise, false when the set already contained it.

Exceptions

ArgumentNullException

item is null.

AddRange(IEnumerable<T>)

Adds each unique item from collection.

public int AddRange(IEnumerable<T> collection)

Parameters

collection IEnumerable<T>

The source collection. Must not be null.

Returns

int

The number of items added.

Exceptions

ArgumentNullException

collection is null.

Clear()

Removes all elements from the set.

public void Clear()

Contains(T)

Determines whether the set contains the specified item.

public bool Contains(T item)

Parameters

item T

The item to locate. Must not be null.

Returns

bool

true if the item exists; otherwise, false.

Exceptions

ArgumentNullException

item is null.

CopyTo(T[], int)

Copies the elements to the specified array starting at arrayIndex.

public void CopyTo(T[] array, int arrayIndex)

Parameters

array T[]

The destination array. Must not be null.

arrayIndex int

The destination start index.

Exceptions

ArgumentNullException

array is null.

ArgumentOutOfRangeException

arrayIndex is negative.

ArgumentException

array does not have enough space starting at arrayIndex.

EnsureCapacity(int)

Ensures that the set can hold at least the specified number of items without reallocating storage.

public int EnsureCapacity(int capacity)

Parameters

capacity int

The desired item capacity.

Returns

int

The resulting item capacity.

Exceptions

ArgumentOutOfRangeException

capacity is negative.

ExceptWith(IEnumerable<T>)

Modifies the current set so that it contains only elements that are not present in other.

public void ExceptWith(IEnumerable<T> other)

Parameters

other IEnumerable<T>

The collection to subtract. Must not be null.

Exceptions

ArgumentNullException

other is null.

GetEnumerator()

Returns an enumerator that iterates through the set in insertion order.

public OrderedSet<T>.Enumerator GetEnumerator()

Returns

OrderedSet<T>.Enumerator

An OrderedSet<T>.Enumerator over the set elements.

IndexOf(T)

Returns the zero-based index of item in insertion order.

public int IndexOf(T item)

Parameters

item T

The item to locate. Must not be null.

Returns

int

The zero-based index of the item, or -1 if it is not present.

Exceptions

ArgumentNullException

item is null.

IntersectWith(IEnumerable<T>)

Modifies the current set so that it contains only elements that are also present in other.

public void IntersectWith(IEnumerable<T> other)

Parameters

other IEnumerable<T>

The collection to intersect with. Must not be null.

Exceptions

ArgumentNullException

other is null.

IsProperSubsetOf(IEnumerable<T>)

Determines whether the current set is a proper (strict) subset of other.

public bool IsProperSubsetOf(IEnumerable<T> other)

Parameters

other IEnumerable<T>

The collection to test against. Must not be null.

Returns

bool

true if the current set is a subset of other and the two are not equal; otherwise, false.

Exceptions

ArgumentNullException

other is null.

IsProperSupersetOf(IEnumerable<T>)

Determines whether the current set is a proper (strict) superset of other.

public bool IsProperSupersetOf(IEnumerable<T> other)

Parameters

other IEnumerable<T>

The collection to test against. Must not be null.

Returns

bool

true if the current set is a superset of other and the two are not equal; otherwise, false.

Exceptions

ArgumentNullException

other is null.

IsSubsetOf(IEnumerable<T>)

Determines whether the current set is a subset of other.

public bool IsSubsetOf(IEnumerable<T> other)

Parameters

other IEnumerable<T>

The collection to test against. Must not be null.

Returns

bool

true if every element of the current set is also in other; otherwise, false.

Exceptions

ArgumentNullException

other is null.

IsSupersetOf(IEnumerable<T>)

Determines whether the current set is a superset of other.

public bool IsSupersetOf(IEnumerable<T> other)

Parameters

other IEnumerable<T>

The collection to test against. Must not be null.

Returns

bool

true if every element of other is also in the current set; otherwise, false.

Exceptions

ArgumentNullException

other is null.

Overlaps(IEnumerable<T>)

Determines whether the current set and other share any elements.

public bool Overlaps(IEnumerable<T> other)

Parameters

other IEnumerable<T>

The collection to test against. Must not be null.

Returns

bool

true if the two collections share at least one element; otherwise, false.

Exceptions

ArgumentNullException

other is null.

Remove(T)

Removes the specified item from the set.

public bool Remove(T item)

Parameters

item T

The item to remove. Must not be null.

Returns

bool

true if the item was removed; otherwise, false.

Exceptions

ArgumentNullException

item is null.

SetEquals(IEnumerable<T>)

Determines whether the current set contains exactly the same elements as other.

public bool SetEquals(IEnumerable<T> other)

Parameters

other IEnumerable<T>

The collection to compare against. Must not be null.

Returns

bool

true if the two collections contain the same elements (ignoring duplicates and order); otherwise, false.

Exceptions

ArgumentNullException

other is null.

SymmetricExceptWith(IEnumerable<T>)

Modifies the current set so that it contains only elements that are present either in the current set or in other, but not in both.

public void SymmetricExceptWith(IEnumerable<T> other)

Parameters

other IEnumerable<T>

The collection to apply symmetric difference with. Must not be null.

Exceptions

ArgumentNullException

other is null.

ToArray()

Copies the elements to a new array in insertion order.

public T[] ToArray()

Returns

T[]

A new array containing the set elements.

TrimExcess()

Shrinks the underlying storage to the current element count.

public void TrimExcess()

UnionWith(IEnumerable<T>)

Modifies the current set so that it contains every element that is present in either this set or other.

public void UnionWith(IEnumerable<T> other)

Parameters

other IEnumerable<T>

The collection to union with. Must not be null.

Exceptions

ArgumentNullException

other is null.

Explicit Interface Implementations

ICollection<T>.Add(T)

Adds item via the Add(T) contract.

void ICollection<T>.Add(T item)

Parameters

item T

The item to add.

Remarks

Discards the boolean result of Add(T); callers that need to detect a duplicate-add should invoke the typed Add(T) overload directly.

IEnumerable<T>.GetEnumerator()

Returns an enumerator that iterates through the collection.

IEnumerator<T> IEnumerable<T>.GetEnumerator()

Returns

IEnumerator<T>

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