Class SwiftGenerationalBucket<T>

Namespace

SwiftCollections

Assembly

SwiftCollections.dll

Represents a high-performance generational bucket that assigns stable handles to stored items.

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

Type Parameters

T

Specifies the type of elements stored in the bucket.

Inheritance

object

SwiftGenerationalBucket<T>

Implements

IStateBacked<SwiftGenerationalBucketState<T>>

ISwiftCloneable<T>

IEnumerable<T>

IEnumerable

IMemoryPackable<SwiftGenerationalBucket<T>>

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

SwiftGenerationalBucket<T> is similar to SwiftBucket<T> but adds generation tracking to prevent stale references from accessing reused slots.

When an item is added, a SwiftHandle containing both an index and generation is returned. If the item is removed and the slot reused later, the generation value changes, causing older handles to automatically become invalid.

This pattern is widely used to safely reference objects without risking accidental access to recycled memory slots.

Key characteristics:

• O(1) insertion and removal.
• Stable handles for the lifetime of stored items.
• Automatic invalidation of stale handles via generation counters.
• Cache-friendly contiguous storage.

Use SwiftBucket<T> when raw indices are acceptable. Use SwiftGenerationalBucket<T> when handle safety is required.

Constructors

SwiftGenerationalBucket()

Initializes a new instance of the SwiftGenerationalBucket class with the default capacity.

public SwiftGenerationalBucket()

SwiftGenerationalBucket(SwiftGenerationalBucketState<T>)

Initializes a new instance of the SwiftGenerationalBucket<T> class with the specified SwiftBucketState<T>.

[MemoryPackConstructor]
public SwiftGenerationalBucket(SwiftGenerationalBucketState<T> state)

Parameters

state SwiftGenerationalBucketState<T>

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

SwiftGenerationalBucket(int)

Initializes a new instance of the SwiftGenerationalBucket class with the specified initial capacity.

public SwiftGenerationalBucket(int capacity)

Parameters

capacity int

The initial number of elements that the bucket can contain. If less than or equal to the default capacity, the default capacity is used. Must be a non-negative integer.

Remarks

The actual capacity will be set to the next power of two greater than or equal to the specified capacity, or to the default capacity if the specified value is too small. This ensures efficient internal storage and lookup performance.

Fields

DefaultCapacity

Represents the default initial capacity for the collection.

public const int DefaultCapacity = 8

Field Value

int

Remarks

Use this constant when initializing the collection to its default size. The value is typically used to optimize memory allocation for small collections.

Properties

Capacity

Gets the total number of elements that the internal data structure can hold without resizing.

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

Property Value

int

Remarks

This value represents the allocated size of the underlying storage, which may be greater than the actual number of elements contained. Capacity is always greater than or equal to the current count of elements.

Count

Gets the number of elements contained in the collection.

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

Property Value

int

State

Gets or sets the current state of the generational bucket.

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

Property Value

SwiftGenerationalBucketState<T>

Remarks

This property provides a snapshot of the bucket's internal state, which can be used for serialization, diagnostics, or restoring the bucket to a previous state. Setting this property replaces the entire state of the bucket, including its contents and allocation metadata.

Methods

Add(T)

Adds the specified value to the collection and returns a handle that can be used to reference it.

public SwiftHandle Add(T value)

Parameters

value T

The value to add to the collection.

Returns

SwiftHandle

A SwiftHandle that uniquely identifies the added value within the collection.

Remarks

The returned handle can be used to access or remove the value later. Handles are only valid as long as the value remains in the collection.

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>

EnsureCapacity(int)

Ensures that the underlying 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 storage should be able to hold. Must be a non-negative integer.

Remarks

If the current capacity is less than the specified value, the storage is resized to accommodate at least that many elements. The actual capacity may be rounded up to the next power of two for performance reasons.

Exists(Predicate<T>)

Determines whether the SwiftGenerationalBucket<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 SwiftGenerationalBucket<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()

public SwiftGenerationalBucket<T>.SwiftGenerationalBucketEnumerator GetEnumerator()

Returns

SwiftGenerationalBucket<T>.SwiftGenerationalBucketEnumerator

GetRef(SwiftHandle)

Returns a reference to the value associated with the specified handle.

public ref T GetRef(SwiftHandle handle)

Parameters

handle SwiftHandle

A handle that identifies the entry whose value is to be accessed. The handle must be valid and refer to an existing entry.

Returns

T

A reference to the value of type T associated with the specified handle.

Exceptions

InvalidOperationException

Thrown if the handle does not refer to a valid or currently used entry.

IsValid(SwiftHandle)

Determines whether the specified handle refers to a valid and currently used entry.

public bool IsValid(SwiftHandle handle)

Parameters

handle SwiftHandle

The handle to validate. The handle must have been obtained from this collection; otherwise, the result is undefined.

Returns

bool

true if the handle is valid and refers to an active entry; otherwise, false.

Remarks

A handle may become invalid if the referenced entry has been removed or replaced. Use this method to check handle validity before accessing the associated entry.

Remove(SwiftHandle)

Removes the entry associated with the specified handle from the collection.

public bool Remove(SwiftHandle handle)

Parameters

handle SwiftHandle

The handle identifying the entry to remove. The handle must refer to a valid, currently used entry.

Returns

bool

true if the entry was successfully removed; otherwise, false.

Remarks

If the handle does not refer to a valid or currently used entry, the method returns false and no action is taken. Removing an entry invalidates the handle for future operations.

TryGet(SwiftHandle, out T)

Attempts to retrieve the value associated with the specified handle.

public bool TryGet(SwiftHandle handle, out T value)

Parameters

handle SwiftHandle

The handle used to identify the entry to retrieve.

value T

When this method returns, contains the value associated with the specified handle if the handle is valid and the entry is in use; otherwise, the default value for the type of the value parameter. This parameter is passed uninitialized.

Returns

bool

true if the value was found and retrieved successfully; otherwise, false.

Remarks

Use this method to safely attempt retrieval without throwing an exception if the handle is invalid or the entry is not in use.