CUtlMap

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

Discrepancies

In std::map accessor functions will find an element by key., CUtlMap's accessor functions do not find a specific element by key, but rather, by index. This means that the following code

// Initialize map for given type
CUtlMap<int, CBaseEntity*> mapList;

// (Populate map here)
mapList.Insert(CBaseEntity->entindex(), CBaseEntity);

// Access map
mapList[ 3 ]->entindex();
mapList.Element( 3 )->entindex();

will return a pointer to CBaseEntity at index position 3 of the map, instead of the CBaseEntity that has key of 3.

In order to access the element at a specific key, use

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

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 on trying to insert more than one element into the map!

To specify the LessFunc for your map, 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

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

Key( IndexType_t i )

Returns the key at index i

Find( const KeyType_t &key )

Returns the index at the given key

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 CTree

You can swap one CUtlMap for another with

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

Self explanatory