Difference between revisions of "CUtlMap"

From Valve Developer Community
Jump to: navigation, search
(added info, saving)
 
Line 1: Line 1:
 
{{toc-right}}
 
{{toc-right}}
  
'''<code>CUtlMap</code>''' is Source's equivalent of the [[W:Map (C++)|C++ Map]] type. A map is essentially a dynamic length array where each iterator, or member,  
+
'''<code>CUtlMap</code>''' is Source's equivalent of the [[W:Map (C++)|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 <code>public/tier1/utlmap.h</code>.
 
is mapped to a specific, unique key value. The code can be found in <code>public/tier1/utlmap.h</code>.
  
Line 20: Line 20:
 
: 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
 
: 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
 
; <code>Reinsert( const KeyType_t &key, IndexType_t i )</code>
 
; <code>Reinsert( const KeyType_t &key, IndexType_t i )</code>
: Replaces the element at index i with the element that has the given key.
+
: Replaces the element at index i with the element mapped to the given key.
  
 
{{warning|You must specify the LessFunc or else you won't be able to insert more than one object into your map! If you are experiencing crashing
 
{{warning|You must specify the LessFunc or else you won't be able to insert more than one object into your map! If you are experiencing crashing
Line 29: Line 29:
 
You can use array-style or use a method for index access:
 
You can use array-style or use a method for index access:
 
; <code>Element( IndexType_t i )</code>
 
; <code>Element( IndexType_t i )</code>
:
+
; <code>operator[]( IndexType_t i )</code>
; <code>operator[]</code>
+
: Returns the element at index i
: Gets a pointer to CBaseEntity
+
{{warning|Unlike std::map, '''<code>CUtlMap</code>''''s accessor functions do not find a specific element by key, but rather, by index. }}
{{warning|Unlike std::map, '''<code>CUtlMap</code>''''s accessor functions do not find a specific iterator by key, but rather, by index. }}
+
 
 +
: <code>Key( IndexType_t i )</code>
 +
: Returns the key at index i
 +
== Removing elements ==
 +
You can remove elements at a given index, a given key, or all at once.
 +
 
 +
Single:
 +
; <code>RemoveAt( IndexType_t i )</code>
 +
: Removes the element at index i
 +
; <code>Remove( const KeyType %key )</code>
 +
: Removes the element mapped to the given key
 +
 
 +
All:
 +
; <code>RemoveAll( )</code>
 +
; <code>Purge( )</code>
 +
; <code>PurgeAndDeleteElements( )</code>
 +
: Purges the list and calls delete on each element in it.
  
 
== Discrepancies ==
 
== Discrepancies ==
 
+
In std::map accessor functions will find an element <i>by key</i>., '''<code>CUtlMap</code>''''s accessor functions do not find a specific element by key, but rather, by index.  
In std::map accessor functions will find an iterator <i>by key</i>., '''<code>CUtlMap</code>''''s accessor functions do not find a specific iterator by key, but rather, by index.  
 
 
This means that the following code
 
This means that the following code
  
Line 53: Line 68:
 
will return a pointer to CBaseEntity at index position '''<code>3</code>''' of the map, instead of the CBaseEntity that has key of 3.
 
will return a pointer to CBaseEntity at index position '''<code>3</code>''' of the map, instead of the CBaseEntity that has key of 3.
  
In order to access the iterator at a specific key, use
+
In order to access the element at a specific key, use
 
<source lang=cpp>
 
<source lang=cpp>
  

Revision as of 03:49, 14 March 2016

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.

Finding bounds

Count()
The total number of items in the map.
IsValidIndex( int i )
Self-explanatory.
InvalidIndex( )
Returns an invalid index.
EnsureCapacity( int num )
Makes sure we have enough memory allocated to store a requested number of elements.

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 )
Replaces the element at index i with the element mapped to the given key.
Warning.png Warning: You must specify the LessFunc or else you won't be able to insert more than one object into your map! If you are experiencing crashing when you insert data into your map, this is why!

To specify the LessFunc for your map, use SetDefLessFunc(mapList).

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.png 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

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.

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