Class SwiftSparseSet

Namespace

SwiftCollections

Assembly

SwiftCollections.dll

Represents a high-performance sparse set for externally supplied non-negative integer IDs. Provides O(1) Add, Remove, Contains, and densely packed iteration.

[JsonConverter(typeof(StateJsonConverterFactory))]
[MemoryPackable(GenerateType.Object)]
public sealed class SwiftSparseSet : IStateBacked<SwiftArrayState<int>>, ISwiftCloneable<int>, ISet<int>, ICollection<int>, IReadOnlyCollection<int>, IEnumerable<int>, ICollection, IEnumerable, IMemoryPackable<SwiftSparseSet>, IMemoryPackFormatterRegister

Inheritance

object

SwiftSparseSet

Implements

IStateBacked<SwiftArrayState<int>>

ISwiftCloneable<int>

ISet<int>

ICollection<int>

IReadOnlyCollection<int>

IEnumerable<int>

ICollection

IEnumerable

IMemoryPackable<SwiftSparseSet>

IMemoryPackFormatterRegister

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Extension Methods

SwiftExtensions.FromEnd<T>(IEnumerable<T>, int)

SwiftExtensions.IsPopulatedSafe<T>(IEnumerable<T>)

SwiftExtensions.IsPopulated<T>(IEnumerable<T>)

SwiftExtensions.PopLast<T>(IEnumerable<T>)

SwiftExtensions.SecondToLast<T>(IEnumerable<T>)

SwiftExtensions.Shuffle<T>(IEnumerable<T>, Random)

SwiftExtensions.SkipFromEnd<T>(IEnumerable<T>, int)

Remarks

SwiftSparseSet is intended for membership workloads where the caller already owns compact integer IDs, such as entity handles, body IDs, or slot indices.

Internally, IDs are stored in a dense array for cache-friendly iteration while a sparse lookup table maps each ID directly to its dense position. Removal uses swap-back, so iteration order is not stable.

Memory usage scales with the highest stored ID rather than only the number of IDs. For arbitrary, huge, or widely spaced keys, prefer SwiftHashSet<T> with int keys.

Constructors

SwiftSparseSet()

Initializes a new instance of the SwiftSparseSet class with default sparse and dense capacities.

public SwiftSparseSet()

SwiftSparseSet(SwiftArrayState<int>)

Initializes a new instance of the SwiftSparseSet class using the specified state.

[MemoryPackConstructor]
public SwiftSparseSet(SwiftArrayState<int> state)

Parameters

state SwiftArrayState<int>

The state object that provides the initial IDs. Cannot be null.

SwiftSparseSet(int)

Initializes a new instance of the SwiftSparseSet class with matching sparse and dense capacities.

public SwiftSparseSet(int capacity)

Parameters

capacity int

The initial sparse and dense capacity.

SwiftSparseSet(int, int)

Initializes a new instance of the SwiftSparseSet class with explicit sparse and dense capacities.

public SwiftSparseSet(int sparseCapacity, int denseCapacity)

Parameters

sparseCapacity int

Initial sparse lookup capacity. This should track the highest expected ID plus one, not just the number of stored IDs.

denseCapacity int

Initial dense storage capacity for IDs.

Fields

DefaultDenseCapacity

Represents the default initial capacity for dense ID storage.

public const int DefaultDenseCapacity = 8

Field Value

int

DefaultSparseCapacity

Represents the default initial capacity for sparse ID lookup.

public const int DefaultSparseCapacity = 8

Field Value

int

Properties

Count

Gets the number of IDs contained in the set.

[JsonIgnore]
[MemoryPackIgnore]
public int Count { get; }

Property Value

int

DenseCapacity

Capacity of the dense ID storage.

[JsonIgnore]
[MemoryPackIgnore]
public int DenseCapacity { get; }

Property Value

int

DenseKeys

Returns the dense ID array. Only the range [0..Count) is populated.

[JsonIgnore]
[MemoryPackIgnore]
public int[] DenseKeys { get; }

Property Value

int[]

Remarks

Prefer collection APIs. Direct key mutation must preserve the dense/sparse lookup invariants; invalid edits may fail fast.

IsReadOnly

[JsonIgnore]
[MemoryPackIgnore]
public bool IsReadOnly { get; }

Property Value

bool

IsSynchronized

Gets a value indicating whether access to the collection is synchronized.

[JsonIgnore]
[MemoryPackIgnore]
public bool IsSynchronized { get; }

Property Value

bool

Keys

Gets a span containing the current IDs in dense iteration order.

[JsonIgnore]
[MemoryPackIgnore]
public Span<int> Keys { get; }

Property Value

Span<int>

Remarks

Prefer collection APIs. Direct key mutation must preserve the dense/sparse lookup invariants; invalid edits may fail fast.

SparseCapacity

Capacity of the sparse lookup table.

[JsonIgnore]
[MemoryPackIgnore]
public int SparseCapacity { get; }

Property Value

int

State

Gets or sets the current state of the sparse set.

[JsonInclude]
[MemoryPackInclude]
public SwiftArrayState<int> State { get; }

Property Value

SwiftArrayState<int>

SyncRoot

Gets an object that can be used to synchronize access to the collection.

[JsonIgnore]
[MemoryPackIgnore]
public object SyncRoot { get; }

Property Value

object

Methods

Add(int)

Adds the specified ID if it is not already present.

public bool Add(int item)

Parameters

item int

Returns

bool

true if the ID was added; false if it was already present.

AsReadOnlySpan()

Returns a read-only span over the populated dense ID range.

public ReadOnlySpan<int> AsReadOnlySpan()

Returns

ReadOnlySpan<int>

Clear()

Removes all IDs from the set without reducing capacity.

public void Clear()

CloneTo(ICollection<int>)

Clones the entire ISwiftCloneable<T> into a new target ICollection<T>, ensuring that the target list is an exact copy. Clears the target list first to match the structure and state of the source list exactly.

public void CloneTo(ICollection<int> output)

Parameters

output ICollection<int>

Contains(int)

Determines whether the set contains the specified ID.

public bool Contains(int item)

Parameters

item int

Returns

bool

ContainsKey(int)

Determines whether the set contains the specified key. Alias for Contains(int).

public bool ContainsKey(int key)

Parameters

key int

Returns

bool

CopyKeysTo(SwiftList<int>)

Replaces the destination list contents with this set's keys in dense iteration order.

public void CopyKeysTo(SwiftList<int> destination)

Parameters

destination SwiftList<int>

The caller-owned list that receives the keys.

Remarks

The destination list is reused and only grows when its current capacity is smaller than Count. Use CopySortedKeysTo(SwiftList<int>) when stable ascending key order is required.

CopySortedKeysTo(SwiftList<int>)

Replaces the destination list contents with this set's keys sorted in ascending order.

public void CopySortedKeysTo(SwiftList<int> destination)

Parameters

destination SwiftList<int>

The caller-owned list that receives the sorted keys.

Remarks

This method is intended for reusable hot-path scratch buffers that need deterministic key order without constructing a persistent sorted collection.

CopyTo(int[], int)

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

Parameters

array int[]

arrayIndex int

EnsureDenseCapacity(int)

Ensures that dense storage can hold at least the specified number of IDs.

public void EnsureDenseCapacity(int capacity)

Parameters

capacity int

EnsureSparseCapacity(int)

Ensures that the sparse lookup table has at least the specified capacity.

public void EnsureSparseCapacity(int capacity)

Parameters

capacity int

ExceptWith(IEnumerable<int>)

public void ExceptWith(IEnumerable<int> other)

Parameters

other IEnumerable<int>

GetDense(out int[], out int)

Retrieves the backing dense ID array and current count.

public void GetDense(out int[] keys, out int count)

Parameters

keys int[]

count int

GetEnumerator()

public SwiftSparseSet.SwiftSparseSetEnumerator GetEnumerator()

Returns

SwiftSparseSet.SwiftSparseSetEnumerator

IntersectWith(IEnumerable<int>)

public void IntersectWith(IEnumerable<int> other)

Parameters

other IEnumerable<int>

IsProperSubsetOf(IEnumerable<int>)

public bool IsProperSubsetOf(IEnumerable<int> other)

Parameters

other IEnumerable<int>

Returns

bool

IsProperSupersetOf(IEnumerable<int>)

public bool IsProperSupersetOf(IEnumerable<int> other)

Parameters

other IEnumerable<int>

Returns

bool

IsSubsetOf(IEnumerable<int>)

public bool IsSubsetOf(IEnumerable<int> other)

Parameters

other IEnumerable<int>

Returns

bool

IsSupersetOf(IEnumerable<int>)

public bool IsSupersetOf(IEnumerable<int> other)

Parameters

other IEnumerable<int>

Returns

bool

Overlaps(IEnumerable<int>)

public bool Overlaps(IEnumerable<int> other)

Parameters

other IEnumerable<int>

Returns

bool

Remove(int)

Removes the specified ID from the set.

public bool Remove(int item)

Parameters

item int

Returns

bool

true if the ID was found and removed; otherwise, false.

SetEquals(IEnumerable<int>)

public bool SetEquals(IEnumerable<int> other)

Parameters

other IEnumerable<int>

Returns

bool

SymmetricExceptWith(IEnumerable<int>)

public void SymmetricExceptWith(IEnumerable<int> other)

Parameters

other IEnumerable<int>

TrimExcess()

Reduces unused dense and sparse capacity while preserving all IDs.

public void TrimExcess()

TryAdd(int)

Adds the specified ID if it is not already present.

public bool TryAdd(int item)

Parameters

item int

Returns

bool

UnionWith(IEnumerable<int>)

public void UnionWith(IEnumerable<int> other)

Parameters

other IEnumerable<int>