RefSortedList

by Theodis
A list kept sorted by the contained item's ref value
ID:125880
 
RefSortedList

This is a list that works much like normal lists in BYOND with the exception
that the contained items are kept sorted by their ref value. This has several
advantages and disadvantages and when used properly can lead to large
performance increases.

Its advantages are
Much faster find times
Much faster removal times
Much easier to find and remove duplicates

Its disadvantages are
The order of the list must be kept otherwise find and remove procs won't work
properly.
Adding items is slower

Since the order of the items must remain sorted you should never manipulate the
contents variable in anyway that would change order. The easiest way this can
happen accidentally is if an item in the list is deleted and not removed as
it'll become a null reference. So you should always first remove an item before
deleting it. If you are unable to do this and the list order gets corrupted
just call Fix() and the list will sort itself out properly again. Other than
that as long as you use the RefSortedList list procs instead of the contents
list procs everything should remain ok.

Because the list order must remain sorted Insert and Swap procs were not
implemented.

Many of the procs have an exact version of them(ie Add and AddExact, Remove and
RemoveExact, etc). To work like the base list class provided by BYOND if you
pass a list into Add or Remove it adds or removes the items contained in the
list rather than the list reference itself. The exact versions of the procs do
not do this instead just add or remove the references of the encountered lists.
Because of this there is less overhead in the Exact procs so those will be
faster and should be used unless you want the list items to be added rather than
the list itself.

Usage
contents - The underlying list of the class use it to access the items in the
list but don't mess with their order or alter them in some way that would change
their reference.

New(l[])

l - The base list to build off of. It can be null.

The base constructor for the class creates an empty list if null is passed in
otherwise it copies the passed in list and sorts the copy.

Add(), Remove(), Copy(), Cut(), Find()
All these procs behave identically to their list counterparts see the BYOND
reference for them

Fix()
Resorts the list. Use this if something messes up the order of the list items
and it needs to be fixed.

RemoveAll(item1, item2, ...)
args - The item(s) which will be removed.

This proc works like remove except that it'll remove all instances of an item
from the list if there are several copies rather than just one.

RemoveDuplicates(item1, item2, ...)
args - The item(s) to remove duplicates for

This proc works like RemoveAll() however it leaves one of the items and only
clears out duplicates.