CUtlMap

CUtlMap is Source's equivalent of the C++ Map type. A map is essentially a CUtlVector where each element, or member, is mapped to a specific, unique key value that can be assigned when the member is added to the map. The code can be found in public/tier1/utlmap.h.

Using CUtlMap

// Initialize map for given type
CUtlMap<int, CBaseEntity*> mapList;
// (Populate map here)
CBaseEntity* pOther;
mapList.Insert(pOther->entindex(), pOther);

// Access map
// Note: Element(..) is given type IndexType_t, not KeyType_t. See Accessing section

// Find index of given key
int idx = mapList.Find(pOther->entindex());
//Ensure that it is a valid index
if (mapList.IsValidIndex(idx))
{
    entindex = mapList.Element(idx)->entindex();
}

Bounds related

Count()

The total number of items in the map.

IsValidIndex( int i )

Checks if a node is valid and in the map.

InvalidIndex( )

Returns an invalid index.

EnsureCapacity( int num )

Makes sure we have enough memory allocated to store a requested number of elements.

MaxElement()

Max "size" of the vector

Adding elements

Insert( const KeyType_t &key, const ElemType_t &insert )

Inserts the element and key into the tail of the map.

InsertOrReplace( ( const KeyType_t &key, const ElemType_t &insert )

Inserts the element and key into the tail of the map, replacing the element if the key is the same as one that already exists

Reinsert( const KeyType_t &key, IndexType_t i )

If you change the search key, this can be used to reinsert the element into the map.

Warning:You must specify the LessFunc or else Source will crash when it tries to insert more than one element into the map! To specify the LessFunc for your CUtlMap, use SetDefLessFunc(exampleCUtlMap).

Accessing Elements

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

Element( IndexType_t i )

operator[]( IndexType_t i )

Returns the element at index i

Key( IndexType_t i )

Returns the key at index i

Find( const KeyType_t &key )

Returns the index at the given key

Warning:Unlike std::map, CUtlMap's accessor functions do not find a specific element by key, but rather, by index.

Removing elements

You can remove elements at a given index, a given key, or all at once.

Single:

RemoveAt( IndexType_t i )

Removes the element at index i

Remove( const KeyType %key )

Removes the element mapped to the given key

All:

RemoveAll( )

Purge( )

PurgeAndDeleteElements( )

Purges the list and calls delete on each element in it.

Iteration

FirstInorder()

NextInorder( IndexType_t i )

PrevInorder( IndexType_t i )

LastInorder()

Other functions

You can get the tree which the CUtlMap consists of using

AccessTree()

Returns a CTree

You can swap one CUtlMap for another with

Swap( CUtlMap< K, T, I > &that )

Self explanatory