Class SwiftTicketMap<T>

Namespace

SwiftCollections

Assembly

SwiftCollections.dll

Represents a high-performance ticket map that assigns stable tickets to stored items.

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

Type Parameters

T

Specifies the type of elements stored in the map.

Inheritance

object

SwiftTicketMap<T>

Implements

IStateBacked<SwiftTicketMapState<T>>

ISwiftCloneable<T>

IEnumerable<T>

IEnumerable

IMemoryPackable<SwiftTicketMap<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

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

When an item is added, a SwiftTicket containing both an index and generation is returned. If the item is removed and the slot reused later, the generation value changes, causing older tickets 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 tickets for the lifetime of stored items.
• Automatic invalidation of stale tickets via generation counters.
• Cache-friendly contiguous storage.

Use SwiftSlotMap<T> when raw indices are acceptable. Use SwiftTicketMap<T> when ticket safety is required.

Constructors

SwiftTicketMap()

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

public SwiftTicketMap()

SwiftTicketMap(SwiftTicketMapState<T>)

Initializes a new instance of the SwiftTicketMap<T> class with the specified SwiftTicketMapState<T>.

[MemoryPackConstructor]
public SwiftTicketMap(SwiftTicketMapState<T> state)

Parameters

state SwiftTicketMapState<T>

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

SwiftTicketMap(int)

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

public SwiftTicketMap(int capacity)

Parameters

capacity int

The initial number of elements that the map 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 ticket map.

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

Property Value

SwiftTicketMapState<T>

Remarks

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

Methods

Add(T)

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

public SwiftTicket Add(T value)

Parameters

value T

The value to add to the collection.

Returns

SwiftTicket

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

Remarks

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

Clear()

Removes all elements and invalidates their tickets without reducing capacity.

public void Clear()

Clear(bool)

Removes all elements, optionally releasing references throughout retained backing storage.

public void Clear(bool clearRetainedReferences)

Parameters

clearRetainedReferences bool

If true, also releases references outside the previously used range.

Remarks

Stored generations survive clearing so old tickets remain invalid on reuse. Capacity is preserved.

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 SwiftTicketMap<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 SwiftTicketMap<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 map 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 SwiftTicketMap<T>.SwiftTicketMapEnumerator GetEnumerator()

Returns

SwiftTicketMap<T>.SwiftTicketMapEnumerator

GetRef(SwiftTicket)

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

public ref T GetRef(SwiftTicket ticket)

Parameters

ticket SwiftTicket

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

Returns

T

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

Exceptions

InvalidOperationException

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

IsValid(SwiftTicket)

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

public bool IsValid(SwiftTicket ticket)

Parameters

ticket SwiftTicket

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

Returns

bool

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

Remarks

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

Remove(SwiftTicket)

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

public bool Remove(SwiftTicket ticket)

Parameters

ticket SwiftTicket

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

Returns

bool

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

Remarks

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

TryGet(SwiftTicket, out T)

Attempts to retrieve the value associated with the specified ticket.

public bool TryGet(SwiftTicket ticket, out T value)

Parameters

ticket SwiftTicket

The ticket used to identify the entry to retrieve.

value T

When this method returns, contains the value associated with the specified ticket if the ticket 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 ticket is invalid or the entry is not in use.