Table of Contents

Class SwiftBucket<T>

Namespace
SwiftCollections
Assembly
SwiftCollections.dll

Represents a high-performance bucket collection that assigns and manages stable integer indices for stored items. Provides O(1) insertion, removal, and lookup by internally generated index.

[JsonConverter(typeof(StateJsonConverterFactory))]
[MemoryPackable(GenerateType.Object)]
public sealed class SwiftBucket<T> : IStateBacked<SwiftBucketState<T>>, ISwiftCloneable<T>, ICollection<T>, IEnumerable<T>, ICollection, IEnumerable, IMemoryPackable<SwiftBucket<T>>, IMemoryPackFormatterRegister

Type Parameters

T

Specifies the type of elements in the bucket.

Inheritance
SwiftBucket<T>
Implements
IStateBacked<SwiftBucketState<T>>
IMemoryPackable<SwiftBucket<T>>
IMemoryPackFormatterRegister
Inherited Members
Extension Methods

Remarks

Unlike SwiftSparseMap<T>, which requires callers to provide the key used to store values, SwiftBucket<T> internally generates and manages indices for each inserted item.

These indices remain stable for the lifetime of the item unless it is removed.

The container is optimized for scenarios requiring:

  • Stable handles or identifiers.
  • Fast addition and removal.
  • Dense storage and iteration performance.

Efficient Lookups Using Indices: When you add items to the bucket using the Add(T) method, it returns an arrayIndex that you can store externally. You can then use this arrayIndex to access the item directly via the indexer, and check if it's still present using the IsAllocated(int) method. This approach allows for O(1) time complexity for lookups and existence checks, avoiding the need for O(n) searches using methods like IndexOf(T) or Contains(T).

Note: iteration over the collection does not follow any guaranteed order and depends on internal allocation.

Constructors

SwiftBucket()

Initializes a new instance of the SwiftBucket<T> class.

public SwiftBucket()

SwiftBucket(SwiftBucketState<T>)

Initializes a new instance of the SwiftBucket<T> class with the specified SwiftArrayState<T>.

[MemoryPackConstructor]
public SwiftBucket(SwiftBucketState<T> state)

Parameters

state SwiftBucketState<T>

The state containing the internal array, count, offset, and version for initialization.

SwiftBucket(int)

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

public SwiftBucket(int capacity)

Parameters

capacity int

The initial capacity of the bucket.

Fields

DefaultCapacity

Represents the default initial capacity used when no specific capacity is provided.

public const int DefaultCapacity = 8

Field Value

int

Properties

Capacity

Gets the total capacity of the SwiftBucket<T>.

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

Property Value

int

Count

Gets the number of elements contained in the SwiftBucket<T>.

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

Property Value

int

IsReadOnly 

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

Property Value

bool

IsSynchronized 

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

Property Value

bool

this[int]

Gets or sets the element at the specified arrayIndex. Throws InvalidOperationException if the arrayIndex is invalid or unallocated.

[JsonIgnore]
[MemoryPackIgnore]
public T this[int index] { get; set; }

Parameters

index int

The zero-based arrayIndex of the element to get or set.

Property Value

T

PeakCount

Gets the highest value recorded for the count during the lifetime of the object.

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

Property Value

int

State

Gets or sets the current state of the bucket, including all items, allocation status, and free indices.

[JsonInclude]
[MemoryPackInclude]
public SwiftBucketState<T> State { get; }

Property Value

SwiftBucketState<T>

Remarks

Use this property to capture or restore the complete state of the bucket, such as for serialization or checkpointing scenarios. Setting this property replaces the entire internal state, including items and allocation metadata.

SyncRoot 

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

Property Value

object

Methods

Add(T)

Adds an item to the bucket and returns its arrayIndex.

public int Add(T item)

Parameters

item T

The item to add.

Returns

int

The arrayIndex where the item was added.

Clear()

Removes all items from the bucket.

public void Clear()

CloneTo(ICollection<T>)

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<T> output)

Parameters

output ICollection<T>

Contains(T)

Determines whether the bucket contains a specific value.

public bool Contains(T item)

Parameters

item T

The object to locate in the bucket.

Returns

bool

true if item is found; otherwise, false.

Remarks

This method performs a linear search and has a time complexity of O(n). It is recommended to store the indices returned by the Add(T) method for faster lookups using the indexer.

CopyTo(T[], int)

Copies the elements of the bucket to an Array, starting at a particular Array arrayIndex.

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

Parameters

array T[]

The one-dimensional Array that is the destination of the elements copied from bucket.

arrayIndex int

The zero-based arrayIndex in array at which copying begins.

EnsureCapacity(int)

Ensures that the internal storage has at least the specified capacity, expanding it if necessary.

public void EnsureCapacity(int capacity)

Parameters

capacity int

The minimum number of elements that the internal storage should be able to hold. Must be a non-negative value.

Remarks

If the current capacity is less than the specified value, the internal storage is increased to the next power of two greater than or equal to the requested capacity. No action is taken if the current capacity is sufficient.

Exists(Predicate<T>)

Determines whether the SwiftBucket<T> contains an element that matches the conditions defined by the specified predicate.

public bool Exists(Predicate<T> match)

Parameters

match Predicate<T>

The predicate that defines the conditions of the element to search for.

Returns

bool

true if the SwiftBucket<T> contains one or more elements that match the specified predicate; otherwise, false.

Find(Predicate<T>)

Searches for an element that matches the conditions defined by the specified predicate, and returns the first matching element in bucket iteration order.

public T Find(Predicate<T> match)

Parameters

match Predicate<T>

The predicate that defines the conditions of the element to search for.

Returns

T

The first element that matches the conditions defined by the specified predicate, if found; otherwise, the default value for type T.

GetEnumerator()

Returns an enumerator that iterates through the SwiftBucket<T>.

public SwiftBucket<T>.SwiftBucketEnumerator GetEnumerator()

Returns

SwiftBucket<T>.SwiftBucketEnumerator

An enumerator for the bucket.

IndexOf(T)

Searches for the specified object and returns the zero-based arrayIndex of the first occurrence within the bucket.

public int IndexOf(T item)

Parameters

item T

The object to locate in the bucket.

Returns

int

The zero-based arrayIndex of the first occurrence of item within the bucket, if found; otherwise, -1.

Remarks

This method performs a linear search and has a time complexity of O(n). It is recommended to store the indices returned by the Add(T) method for faster lookups using the indexer.

InsertAt(int, T)

Inserts an item at the specified arrayIndex. If an item already exists at that arrayIndex, it will be replaced.

public void InsertAt(int index, T item)

Parameters

index int

The arrayIndex at which to insert the item.

item T

The item to insert.

IsAllocated(int)

Determines whether the element at the specified index is currently allocated.

public bool IsAllocated(int index)

Parameters

index int

The zero-based index of the element to check. Must be greater than or equal to 0 and less than the length of the underlying array.

Returns

bool

true if the element at the specified index is allocated; otherwise, false.

RemoveAt(int)

Removes the item at the specified arrayIndex.

public void RemoveAt(int index)

Parameters

index int

The arrayIndex of the item to remove.

TrimExcessCapacity()

Reduces unused tail capacity while preserving stable handles for all currently allocated entries.

public void TrimExcessCapacity()

TryGetValue(int, out T)

Attempts to get the value at the specified arrayIndex.

public bool TryGetValue(int key, out T value)

Parameters

key int

The arrayIndex of the item to get.

value T

When this method returns, contains the value associated with the specified arrayIndex, if the arrayIndex is found; otherwise, the default value for the type of the value parameter.

Returns

bool

true if the bucket contains an element at the specified arrayIndex; otherwise, false.

TryRemove(T)

Removes the first occurrence of a specific object from the bucket.

public bool TryRemove(T item)

Parameters

item T

The object to remove.

Returns

bool

true if item was successfully removed; otherwise, false.

TryRemoveAt(int)

Removes the item at the specified arrayIndex if it has been allocated.

public bool TryRemoveAt(int index)

Parameters

index int

Returns

bool
Edit this page