UGTK / Toolkit / Libraries Extensions / List Extension Completed

List Extension

Summary

The List Extension adds the everyday helpers that List<T> is missing: move an element, shuffle, first / last, convert to a queue, strip nulls and pull random elements (optionally excluding some). All of them are C# extension methods, so they read as if they were part of List<T> itself.

Modules Dependencies

None. One static class, no UGTK reference, nothing but System and UnityEngine.

Setup

Nothing to set up: no component, no prefab, no scene. Add UGTK.LibrariesExtensions.ListExtension to your assembly definition references and the right using to your script.

⚠️ The class lives in the namespace UnityGamesToolkit.Runtime, not in the one the assembly definition suggests. The using you need is: csharp using UnityGamesToolkit.Runtime;

How To Use

Moving elements

var list = new List<int> { 2, 6, 8, 9 };

list.MoveElement(1, 3);   // -> [2, 8, 9, 6]

MoveElement is a move, not a swap: the element is removed from currentIndex and inserted at newIndex, so everything in between shifts by one. Out-of-range indices (or a null list) throw ArgumentOutOfRangeException.

list.MoveElementToRandomPosition(1);   // same move, with a random destination index

Shuffle

list.Shuffle();   // Fisher-Yates in place; a list of 0 or 1 elements is left alone

First / last

int a = list.First();   // list[0]
int z = list.Last();    // list[Count - 1]

Both throw InvalidOperationException on an empty or null list — they do not return default like LINQ's FirstOrDefault.

Debug print

list.PrintOnConsole();   // one Debug.Log per element

It logs every element, nulls included — and a null element throws a NullReferenceException on ToString(). Strip the nulls first if the list can contain them.

To queue

Queue<int> queue = list.ListToQueue();   // same order: the first element is the first dequeued

Removing nulls

List<int> clean = ListExtension.RemoveNullValues(list);

RemoveNullValues is the one method that is not an extension method (its parameter has no this), so it has to be called on the class, not on the list. It also returns a new list: the original is untouched.

Random elements

int r  = list.RandomElement();                              // any element
int r2 = list.RandomElementExcept(6);                       // any element except 6
int r3 = list.RandomElementExcept(new List<int> { 2, 9 });  // any element outside the exclusion list

All three throw InvalidOperationException when the list is empty, and the two …Except overloads throw as well when the exclusion removes every candidate — wrap them when the exclusion may cover the whole list. The comparison uses Equals, so reference types match by reference unless they override it.

Which random? Everything random here uses a single static System.Random, not UnityEngine.Random. So Random.InitState(seed) does not make these calls reproducible, and the sequence is shared by every caller in the process.

Testing Scene

Open Debug/ListExtensionScene.unity. It holds a single object, ListExtensionTest, carrying Mn_ListExtensionTest. Every method is reachable from the component's context menu: right-click the header in the Inspector, with no play mode and no button wiring.

What to do, in order:

Run Rebuild to get a clean A, B, C… list. The Output field prints it after every call.
Run Move Element with From Index 0 and To Index 3: A moves to the fourth slot and the rest closes the gap. The list is modified in place — no copy is returned.
Run Shuffle, then Read Random Except First and To Queue to see the read-only helpers.
Set From Index to 99 and run Move Element again.

Step 4 is the interesting one: the method throws ArgumentOutOfRangeException, and the component shows the exception instead of swallowing it. Several methods of this library behave that way, so knowing which ones throw is part of using it.

Technical Info

Path	Content
`Scripts/ListExtension.cs`	The whole system: the static class `ListExtension`, namespace `UnityGamesToolkit.Runtime`

API: MoveElement<T>(int, int), MoveElementToRandomPosition<T>(int), Shuffle<T>(), First<T>(), Last<T>(), PrintOnConsole<T>(), ListToQueue<T>(), RemoveNullValues<T>(List<T>) (static, not an extension), RandomElement<T>(), RandomElementExcept<T>(T), RandomElementExcept<T>(List<T>).