Interface IScyllaCollection<T>

Typed extension of IScyllaCollection that adds element-level operations for collections that store items of a specific type T.

Inherited Members
Namespace: Scylla.Core.Structures
Assembly: ScyllaCore.dll
Syntax
public interface IScyllaCollection<T> : IScyllaCollection
Type Parameters
Name Description
T

The element type stored in the collection. May be a value type or a reference type. No constraints are applied; concrete implementations handle null behavior individually.
Remarks

This interface deliberately uses a small, "try"-based surface area so that implementations with fundamentally different shapes - queues (FIFO), stacks (LIFO), ring buffers - can all satisfy the same contract without semantic mismatches or forced allocations.

The meaning of "add", "remove", and "peek" is intentionally abstract:

When a collection supports capacity-bounded growth, TryAdd(T) returns false rather than throwing, enabling callers to handle a full collection without exceptions. Query Capabilities to determine whether a collection has a capacity ceiling (HasCapacity) and whether peeking is supported (SupportsPeek).

Allocation-free enumeration: The two CopyTo overloads provide snapshot-style export to caller-owned buffers. This is the recommended approach for iterating over a collection through the interface, avoiding the heap allocation that IEnumerable<T> would require. Iteration through the concrete type (e.g. using a value-type foreach enumerator) is always preferred in hot paths.

Methods

CopyTo(Span<T>)

Copies up to destination.Length elements from the collection into the provided Span<T> buffer and returns the number of elements actually copied.

Declaration
int CopyTo(Span<T> destination)
Parameters
Type Name Description
Span<T> destination

A caller-owned Span<T> that receives the copied elements. If destination.Length is less than Count, only the first destination.Length elements are copied and the remainder are silently omitted. An empty (length-zero) span results in no copy and a return value of 0.
Returns
Type Description
int

The number of elements copied into destination. This is min(Count, destination.Length). Returns 0 if the collection is empty or destination.Length is 0.
Remarks

Copy order is collection-dependent and mirrors the collection's natural iteration order:

This overload is the preferred allocation-free alternative to interface-based IEnumerable<T> enumeration. Using a stack-allocated or pooled Span<T> avoids any heap allocation.

On synchronized wrappers, this operation is protected by the internal lock. The copied snapshot reflects the collection state at the moment the lock was acquired.

See Also

CopyTo(T[], int)

Copies up to destination.Length - destinationIndex elements from the collection into the provided array starting at destinationIndex, and returns the number of elements actually copied.

Declaration
int CopyTo(T[] destination, int destinationIndex)
Parameters
Type Name Description
T[] destination

A caller-owned array that receives the copied elements. Must not be null. If the available space (destination.Length - destinationIndex) is less than Count, only as many elements as will fit are copied.
int destinationIndex

The zero-based index in destination at which copying begins. Must be in the range [0, destination.Length]. An index equal to destination.Length results in zero elements being copied.
Returns
Type Description
int

The number of elements copied. This is min(Count, destination.Length - destinationIndex). Returns 0 if the collection is empty or there is no available space in destination.
Remarks

Copy order is collection-dependent and mirrors the collection's natural iteration order:

This overload is provided for scenarios where a Span<T> cannot be used (e.g. across async boundaries or when targeting APIs that expect arrays). Prefer CopyTo(Span<T>) in synchronous hot paths.

On synchronized wrappers, this operation is protected by the internal lock. The copied snapshot reflects the collection state at the moment the lock was acquired.

Exceptions
Type Condition
ArgumentNullException

Thrown when destination is null.
ArgumentOutOfRangeException

Thrown when destinationIndex is negative or greater than destination.Length.
See Also

TryAdd(T)

Attempts to add an item to the collection using the collection's natural insertion semantics.

Declaration
bool TryAdd(T item)
Parameters
Type Name Description
T item

The item to add. The interpretation of item depends on the concrete collection: it is enqueued in a queue, pushed onto a stack, or written to a ring buffer. For reference types, null is permitted unless the concrete implementation documents otherwise.
Returns
Type Description
bool

true if the item was successfully added; false if the operation could not be performed - for example, because the collection has a fixed capacity and is currently full. A false result does not indicate an error; callers should treat it as a back-pressure signal and decide how to respond (retry, drop, or block externally).
Remarks

This method never throws due to a full collection. It may still throw for programmer errors such as an internal overflow beyond maximum array size, but those cases are documented on the concrete implementation.

When the collection is unsynchronized and TryAdd is called concurrently from multiple threads, the behavior is undefined. Use a synchronized wrapper (see ThreadSafety) or supply external locking.

TryPeek(out T)

Attempts to inspect the "next" item that would be returned by TryRemove(out T) without actually removing it from the collection.

Declaration
bool TryPeek(out T item)
Parameters
Type Name Description
T item

When this method returns true, contains the peeked item. When this method returns false, contains default(T). The item returned is the same item that would be removed by the next call to TryRemove(out T), provided no modifications occur in between.
Returns
Type Description
bool

true if an item was available and peeked successfully; false if the collection is empty, or if peeking is not supported by this collection instance.
Remarks

Not all collections support peeking. Before calling this method through the interface, check Capabilities for the SupportsPeek flag. If the flag is absent, the method will always return false.

On unsynchronized collections, the item returned by TryPeek may be removed or replaced by a concurrent thread before the caller acts on it. Wrap the peek-and-act pattern inside a lock on SyncRoot when using a synchronized collection.

See Also

TryRemove(out T)

Attempts to remove the "next" item from the collection using the collection's natural removal semantics, and returns it via an out parameter.

Declaration
bool TryRemove(out T item)
Parameters
Type Name Description
T item

When this method returns true, contains the removed item. When this method returns false, contains default(T). The item returned is the front element of a queue (FIFO), the top element of a stack (LIFO), or the oldest element of a ring buffer.
Returns
Type Description
bool

true if an item was successfully removed; false if the collection is empty or the operation could not be performed for another reason specific to the implementation.
Remarks

For reference-type collections, implementations should null out the internal slot after removal to release the reference and allow garbage collection.

This method never throws due to an empty collection. It is safe to call on an empty collection and simply check the return value.

Extension Methods

See Also