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.

Iterating over elements

To loop through each element, you can write a for loop the same way you would for an std::vector, or you can use the FOR_EACH_VEC macro:

// start at first element
FOR_EACH_VEC(vectorList, i)
{
	CBaseEntity* ent = vectorList[i];
	...
}

// start at last element and work backwards
FOR_EACH_VEC_BACK(vectorList, i)
{
	CBaseEntity* ent = vectorList[i];
	...
}

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.