CUtlVector

CUtlVector is Source's equivalent of the C++ Vector type. It can be thought of as an array of dynamic length. Code can be found in public/tier1/utlvector.h.

For detailed discussion of the pros and cons of vectors, see Wikipedia.

Warning:Vector elements are moved around in memory, so never store pointers to them. Always use Element(int) or the [] notation.

Accessing elements

You can use array-style or use a method for index access:

// Initialize vector for given type
CUtlVector<CBaseEntity*> vectorList;

// (Populate vector here)

// Access vector 
vectorList[ 0 ]->entindex();
vectorList.Element( 0 )->entindex();

You can also access the head (first element) and tail (last element):

vectorList.Head();
vectorList.Tail();

Finding bounds

Count(): The total number of items in the vector. (There is also a Size() method, but it is deprecated.)
IsValidIndex( int i ): Self-explanatory.
EnsureCapacity( int num ): Makes sure we have enough memory allocated to store a requested number of elements.
EnsureCount( int num ): Makes sure we have at least this many elements.

Adding elements

There are several methods for adding individual elements, multiple elements as well as other CUtlVectors:

Singly:

AddToHead( const T& src )
AddToTail( const T& src ): Adds the element to the start or end of the list.
InsertBefore( int elem, const T& src )
InsertAfter( int elem, const T& src ): Puts the element before or after a certain index.

In batches:

AddMultipleToTail( int num, const T *pToCopy ): Adds several elements to the end of the list.
InsertMultipleBefore( int elem, int num, const T *pToInsert ): Adds several elements before a valid index position except the head (which is always 0).
AddVectorToTail( CUtlVector const &src ): Adds another CUtlVector to the tail.

Searching elements

Tip:If you want an automatically sorting list, have a look at CUtlSortVector.

To search for an element, your type must have implemented the == operator.

Find( const T& src ): Searches the vector for the given element, returning the index if found, and -1 if not.
HasElement( const T& src ): Check if the vector contains the given element.
FindAndRemove(): Self-explanatory.

Removing elements

When you remove an element, its destructor is called and the vector is reordered.

Singly:

FindAndRemove(): Self-explanatory.
Remove( int elem ): Calls the destructor of the element at the given position and shifts all elements left.
FastRemove( int elem ): Similar to Remove(), but just does a memcpy to accomodate for the removed element.

In batches:

RemoveMultiple( int elem, int num ): Removes num elements starting at position elem. Actual removal of elements is done in a right-to-left manner.
RemoveAll(): Clears the entire vector.

Copying

CopyArray( const T *pArray, int size ): Copies size elements of the given array into the vector, possibly overwriting elements. Always starts from index 0.
Swap( CUtlVector< T, A > &vec ): Simply swaps the vector with the given one.

Deallocating

Purge(): Calls RemoveAll() and purges the allocated memory.
PurgeAndDeleteElements(): First deletes all elements and then calls Purge().

Sorting

The class has a Sort method that takes a predicate, like so:

// Sort vector by predicate
vectorList.Sort( predicateFunction );

In this case, the predicate must be of the type int (__cdecl *)(const CBaseEntity *, const CBaseEntity *):

static int __cdecl predicateFunction( const CBaseEntity *a, const CBaseEntity *b )
{
	int valueA = a->entindex();
	int valueB = b->entindex();

	if( valueA < valueB )
		return -1;
	else if( valueA == valueB )
		return 0;
	else return 1;
 }

This function needs to be defined before the method it is called in.