Class CollectionUtil

Provides extension methods for List<T> and IList<T> covering element access, removal, reordering, filling, resizing, and index-based sorting that does not disturb the original list.

Inheritance

object

CollectionUtil

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.Core.Util

Assembly: ScyllaCore.dll

Syntax

public static class CollectionUtil

Remarks

All methods that return elements from a null or empty list return default(T) rather than throwing, making them safe for guard-free call sites. Methods that modify the list (e.g. Swap<T>(IList<T>, int, int), Reverse<T>(List<T>), Fill<T>(IList<T>, T), Resize<T>(List<T>, int, T)) throw ArgumentNullException when the list is null, as a modification to a null reference is always a programming error.

For deterministic shuffling of a list, use RandomUtil.Shuffle<T>, which accepts an explicit random source and is reproducible with a given seed.

For array-specific operations such as capacity management, see ArrayUtil.

Methods

CreateSortIndices<T>(IList<T>)

Returns an integer array whose values are the indices into list in ascending sorted order, without modifying the list itself.

Declaration

public static int[] CreateSortIndices<T>(this IList<T> list) where T : IComparable<T>

Parameters

Type	Name	Description
IList<T>	list	The list to generate sort indices for. May be null, in which case null is returned.

Returns

Type	Description
int[]	A new int[] of the same length as list containing the source indices in ascending sorted order, or null if list is null.

Type Parameters

Name	Description
T	The type of elements in the list. Must implement IComparable<T> to provide a natural sort order.

Remarks

The returned indices can be used to read elements from the original list in sorted order while keeping parallel arrays, dictionaries, or other data structures aligned with the original indices. For example, if list = ["banana", "apple", "cherry"], the result would be [1, 0, 2] (indices of the alphabetical order).

null values in the list are sorted before non-null values (treated as less-than all other elements).

CreateSortIndices<T>(IList<T>, IComparer<T>)

Returns an integer array whose values are the indices into list in the order defined by comparer, without modifying the list itself.

Declaration

public static int[] CreateSortIndices<T>(this IList<T> list, IComparer<T> comparer)

Parameters

Type	Name	Description
IList<T>	list	The list to generate sort indices for. May be null, in which case null is returned.
IComparer<T>	comparer	The comparer that defines the desired element ordering. Must not be null.

Returns

Type	Description
int[]	A new int[] of the same length as list containing the source indices ordered by comparer, or null if list is null.

Type Parameters

Name	Description
T	The type of elements in the list.

Remarks

Identical in behavior to CreateSortIndices<T>(IList<T>) but uses a caller-supplied IComparer<T> instead of the natural order, enabling descending sort, locale-sensitive string comparison, multi-key sorting, and other custom orderings.

Exceptions

Type	Condition
ArgumentNullException	Thrown when comparer is null.

Fill<T>(IList<T>, T)

Fills all elements of the list with the specified value.

Declaration

public static void Fill<T>(this IList<T> list, T value)

Parameters

Type	Name	Description
IList<T>	list	The list to fill.
T	value	The value to fill with.

Type Parameters

Name	Description
T	The type of elements in the list.

Exceptions

Type	Condition
ArgumentNullException	Thrown if list is null.

GetFirst<T>(IList<T>)

Returns the element at index 0 without removing it, or default(T) if the list is null or empty. Accepts any IList<T> implementation.

Declaration

public static T GetFirst<T>(this IList<T> list)

Parameters

Type	Name	Description
IList<T>	list	The list to peek at. May be null.

Returns

Type	Description
T	The element at index 0, or default(T) when list is null or has no elements.

Type Parameters

Name	Description
T	The type of elements in the list.

GetFirst<T>(List<T>)

Returns the element at index 0 without removing it, or default(T) if the list is null or empty.

Declaration

public static T GetFirst<T>(this List<T> list)

Parameters

Type	Name	Description
List<T>	list	The list to peek at. May be null.

Returns

Type	Description
T	The element at index 0, or default(T) when list is null or has no elements.

Type Parameters

Name	Description
T	The type of elements in the list.

GetLast<T>(IList<T>)

Returns the last element of the list without removing it, or default(T) if the list is null or empty. Accepts any IList<T> implementation.

Declaration

public static T GetLast<T>(this IList<T> list)

Parameters

Type	Name	Description
IList<T>	list	The list to peek at. May be null.

Returns

Type	Description
T	The element at index Count - 1, or default(T) when list is null or has no elements.

Type Parameters

Name	Description
T	The type of elements in the list.

GetLast<T>(List<T>)

Returns the last element of the list without removing it, or default(T) if the list is null or empty.

Declaration

public static T GetLast<T>(this List<T> list)

Parameters

Type	Name	Description
List<T>	list	The list to peek at. May be null.

Returns

Type	Description
T	The element at index Count - 1, or default(T) when list is null or has no elements.

Type Parameters

Name	Description
T	The type of elements in the list.

RemoveAtIndex<T>(List<T>, int)

Removes the element at the specified index from the list and returns it. Returns default(T) if the list is null or the index is out of range, rather than throwing.

Declaration

public static T RemoveAtIndex<T>(this List<T> list, int index)

Parameters

Type	Name	Description
List<T>	list	The list to remove from. May be null.
int	index	The zero-based index of the element to remove. Values outside [0, Count-1] cause a silent default(T) return instead of an exception.

Returns

Type	Description
T	The removed element, or default(T) if list is null or index is outside the valid range.

Type Parameters

Name	Description
T	The type of elements in the list.

RemoveFirst<T>(List<T>)

Removes the first element from the list and returns it. Returns default(T) if the list is null or empty.

Declaration

public static T RemoveFirst<T>(this List<T> list)

Parameters

Type	Name	Description
List<T>	list	The list to remove from. May be null.

Returns

Type	Description
T	The element that was at index 0, or default(T) if list is null or empty.

Type Parameters

Name	Description
T	The type of elements in the list.

Remarks

This is an O(n) operation because List<T> must shift all remaining elements down by one index after removing index 0. For frequent front removals, prefer a Queue<T> or the Deque<T> structure from Scylla.Core.Structures.

RemoveLast<T>(List<T>)

Removes the last element from the list and returns it. Returns default(T) if the list is null or empty. This is an O(1) operation because no element shifting is required.

Declaration

public static T RemoveLast<T>(this List<T> list)

Parameters

Type	Name	Description
List<T>	list	The list to remove from. May be null.

Returns

Type	Description
T	The element that was at index Count - 1, or default(T) if list is null or empty.

Type Parameters

Name	Description
T	The type of elements in the list.

Resize<T>(List<T>, int, T)

Resizes a List<T> to exactly newSize elements, removing trailing elements when shrinking or appending defaultValue instances when growing.

Declaration

public static void Resize<T>(this List<T> list, int newSize, T defaultValue = default)

Parameters

Type	Name	Description
List<T>	list	The list to resize. Must not be null.
int	newSize	The desired element count after the call. Must be non-negative.
T	defaultValue	The value used to fill newly added slots when newSize exceeds the current count. Defaults to default(T).

Type Parameters

Name	Description
T	The type of elements in the list.

Remarks

When newSize is less than the current count, excess elements are removed via List<T>.RemoveRange in a single O(1) metadata operation (no element destruction in managed code).

When newSize is greater than the current count, the list's internal capacity is pre-set to avoid repeated reallocations, and defaultValue is appended for each new slot. For reference types, passing null (the default) fills the new slots with null; for value types, passing default fills them with the zero value.

Exceptions

Type	Condition
ArgumentNullException	Thrown when list is null.
ArgumentOutOfRangeException	Thrown when newSize is negative.

Reverse<T>(IList<T>)

Reverses all elements of the list in place using a manual swap loop, supporting any IList<T> implementation.

Declaration

public static void Reverse<T>(this IList<T> list)

Parameters

Type	Name	Description
IList<T>	list	The list to reverse. Must not be null.

Type Parameters

Name	Description
T	The type of elements in the list.

Remarks

Because IList<T> does not expose a built-in reverse method, this overload swaps elements from both ends toward the center in a single O(n/2) pass.

Exceptions

Type	Condition
ArgumentNullException	Thrown when list is null.

Reverse<T>(List<T>)

Reverses all elements of the list in place by delegating to List<T>.Reverse().

Declaration

public static void Reverse<T>(this List<T> list)

Parameters

Type	Name	Description
List<T>	list	The list to reverse. Must not be null.

Type Parameters

Name	Description
T	The type of elements in the list.

Exceptions

Type	Condition
ArgumentNullException	Thrown when list is null.

Swap<T>(IList<T>, int, int)

Swaps two elements in the list at the specified indices.

Declaration

public static void Swap<T>(this IList<T> list, int indexA, int indexB)

Parameters

Type	Name	Description
IList<T>	list	The list containing the elements to swap.
int	indexA	The index of the first element.
int	indexB	The index of the second element.

Type Parameters

Name	Description
T	The type of elements in the list.

Exceptions

Type	Condition
ArgumentNullException	Thrown if list is null.
ArgumentOutOfRangeException	Thrown if either index is out of range.

TryGetFirst<T>(IList<T>, out T)

Attempts to get the first element of the list without removing it.

Declaration

public static bool TryGetFirst<T>(this IList<T> list, out T result)

Parameters

Type	Name	Description
IList<T>	list	The list to get the first element from.
T	result	When this method returns, contains the first element if found, otherwise default(T).

Returns

Type	Description
bool	True if the list is not null or empty, otherwise false.

Type Parameters

Name	Description
T	The type of elements in the list.

TryGetFirst<T>(List<T>, out T)

Attempts to get the first element of the list without removing it.

Declaration

public static bool TryGetFirst<T>(this List<T> list, out T result)

Parameters

Type	Name	Description
List<T>	list	The list to get the first element from.
T	result	When this method returns, contains the first element if found, otherwise default(T).

Returns

Type	Description
bool	True if the list is not null or empty, otherwise false.

Type Parameters

Name	Description
T	The type of elements in the list.

TryGetLast<T>(IList<T>, out T)

Attempts to get the last element of the list without removing it.

Declaration

public static bool TryGetLast<T>(this IList<T> list, out T result)

Parameters

Type	Name	Description
IList<T>	list	The list to get the last element from.
T	result	When this method returns, contains the last element if found, otherwise default(T).

Returns

Type	Description
bool	True if the list is not null or empty, otherwise false.

Type Parameters

Name	Description
T	The type of elements in the list.

TryGetLast<T>(List<T>, out T)

Attempts to get the last element of the list without removing it.

Declaration

public static bool TryGetLast<T>(this List<T> list, out T result)

Parameters

Type	Name	Description
List<T>	list	The list to get the last element from.
T	result	When this method returns, contains the last element if found, otherwise default(T).

Returns

Type	Description
bool	True if the list is not null or empty, otherwise false.

Type Parameters

Name	Description
T	The type of elements in the list.

See Also

ArrayUtil