CUtlVector

A CUtlVector is a templated, array-like container to which you can add and remove elements at any position. Code can be found in public/tier1/utlvector.h.

Warning:Vector elements can be moved around in memory, so never keep pointers to elements in the vector.

Accessing elements

Simple access

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

// Initialize vector
CUtlVector<CBaseEntity> vectorList;

// Do population here

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

You can also access the head and tail:

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

Getting bounds

For loops, you can use the Count() method.

Warning:There is also a Size() method, but it is deprecated.

For individual elements, you can use the IsValidIndex( int i ) method.

Handy methods for assertions may be:

• 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:

Single elements

• AddToHead( const T& src ) puts the element first in the list.
• AddToTail( const T& src ) puts the element last in the list.
• InsertBefore( int elem, const T& src ) puts the element before a certain index.
• InsertAfter( int elem, const T& src ) puts the element after a certain index.

Multiple elements

• 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

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

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

• The Find() method allows you to search through the CUtlVector.
• HasElement() allows you to check if the vector contains a certain element.
• With FindAndRemove(), you can easily remove elements from the vector.

Removing elements

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

Single elements

• You can use FindAndRemove() (see above).
• Remove( int elem ) calls the destructor of the element at the given position and shifts all elements left.
• FastRemove( int elem ) is similar to Remove(), but just does a memcpy to accomodate for the removed element.

Multiple elements

• 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

From array

• 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 with other CUtlVector

• Swap( CUtlVector< T, A > &vec ) simply swaps the vector with the given one.

Memory deallocation

• Purge() calls RemoveAll() and purges the allocated memory.
• PurgeAndDeleteElements() first delete's all elements and then calls Purge().

Sorting a CUtlVector

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;
}

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