CMapStringToOb Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

A dictionary collection class that maps unique CString objects to CObject pointers.

class CMapStringToOb : public CObject  

Public Constructors

NameDescription
CMapStringToOb::CMapStringToObConstructor.

Public Methods

NameDescription
CMapStringToOb::GetCountReturns the number of elements in this map.
CMapStringToOb::GetHashTableSizeDetermines the current number of elements in the hash table.
CMapStringToOb::GetNextAssocGets the next element for iterating.
CMapStringToOb::GetSizeReturns the number of elements in this map.
CMapStringToOb::GetStartPositionReturns the position of the first element.
CMapStringToOb::HashKeyCalculates the hash value of a specified key.
CMapStringToOb::InitHashTableInitializes the hash table.
CMapStringToOb::IsEmptyTests for the empty-map condition (no elements).
CMapStringToOb::LookupLooks up a void pointer based on the void pointer key. The pointer value, not the entity it points to, is used for the key comparison.
CMapStringToOb::LookupKeyReturns a reference to the key associated with the specified key value.
CMapStringToOb::RemoveAllRemoves all the elements from this map.
CMapStringToOb::RemoveKeyRemoves an element specified by a key.
CMapStringToOb::SetAtInserts an element into the map; replaces an existing element if a matching key is found.

Public Operators

NameDescription
CMapStringToOb::operator [ ]Inserts an element into the map — operator substitution for SetAt.

Once you have inserted a CString- CObject* pair (element) into the map, you can efficiently retrieve or delete the pair using a string or a CString value as a key. You can also iterate over all the elements in the map.

A variable of type POSITION is used for alternate entry access in all map variations. You can use a POSITION to "remember" an entry and to iterate through the map. You might think that this iteration is sequential by key value; it is not. The sequence of retrieved elements is indeterminate.

CMapStringToOb incorporates the IMPLEMENT_SERIAL macro to support serialization and dumping of its elements. Each element is serialized in turn if a map is stored to an archive, either with the overloaded insertion ( <<) operator or with the Serialize member function.

If you need a diagnostic dump of the individual elements in the map (the CString value and the CObject contents), you must set the depth of the dump context to 1 or greater.

When a CMapStringToOb object is deleted, or when its elements are removed, the CString objects and the CObject pointers are removed. The objects referenced by the CObject pointers are not destroyed.

Map class derivation is similar to list derivation. See the article Collections for an illustration of the derivation of a special-purpose list class.

CObject

CMapStringToOb

Header: afxcoll.h

Constructs an empty CString-to- CObject* map.

CMapStringToOb(INT_PTR nBlockSize = 10);

Parameters

nBlockSize
Specifies the memory-allocation granularity for extending the map.

Remarks

As the map grows, memory is allocated in units of nBlockSize entries.

The following table shows other member functions that are similar to CMapStringToOb:: CMapStringToOb.

ClassMember Function
CMapPtrToPtrCMapPtrToPtr( INT_PTR nBlockSize = 10 );
CMapPtrToWordCMapPtrToWord( INT_PTR nBlockSize = 10 );
CMapStringToPtrCMapStringToPtr( INT_PTR nBlockSize = 10 );
CMapStringToStringCMapStringToString( INT_PTR nBlockSize = 10 );
CMapWordToObCMapWordToOb( INT_PTR nBlockSize = 10 );
CMapWordToPtrMapWordToPtr( INT_PTR nBlockSize = 10 );

Example

         CMapStringToOb map(20);  // Map on the stack with blocksize of 20

         CMapStringToOb* pm = new CMapStringToOb;  // Map on the heap
                                                   // with default blocksize

See CObList::CObList for a listing of the CAge class used in all collection examples.

Determines how many elements are in the map.

INT_PTR GetCount() const;  

Return Value

The number of elements in this map.

Remarks

The following table shows other member functions that are similar to CMapStringToOb::GetCount.

ClassMember Function
CMapPtrToPtrINT_PTR GetCount( ) const;
CMapPtrToWordINT_PTR GetCount( ) const;
CMapStringToPtrINT_PTR GetCount( ) const;
CMapStringToStringINT_PTR GetCount( ) const;
CMapWordToObINT_PTR GetCount( ) const;
CMapWordToPtrINT_PTR GetCount( ) const;

Example

See CObList::CObList for a listing of the CAge class used in all collection examples.

         CMapStringToOb map;

         map.SetAt(_T("Bart"), new CAge(13));
         map.SetAt(_T("Homer"), new CAge(36));
         ASSERT(map.GetCount() == 2);

Determines the current number of elements in the hash table.

UINT GetHashTableSize() const;  

Return Value

Returns the number of elements in the hash table.

Remarks

The following table shows other member functions that are similar to CMapStringToOb::GetHashTableSize.

ClassMember Function
CMapPtrToPtrUINT GetHashTableSize( ) const;
CMapPtrToWordUINT GetHashTableSize( ) const;
CMapStringToPtrUINT GetHashTableSize( ) const;
CMapStringToStringUINT GetHashTableSize( ) const;
CMapWordToObUINT GetHashTableSize( ) const;
CMapWordToPtrUINT GetHashTableSize( ) const;

Retrieves the map element at rNextPosition, then updates rNextPosition to refer to the next element in the map.

void GetNextAssoc(
    POSITION& rNextPosition,  
    CString& rKey,  
    CObject*& rValue) const;  

Parameters

rNextPosition
Specifies a reference to a POSITION value returned by a previous GetNextAssoc or GetStartPosition call.

rKey
Specifies the returned key of the retrieved element (a string).

rValue
Specifies the returned value of the retrieved element (a CObject pointer). See Remarks for more about this parameter.

Remarks

This function is most useful for iterating through all the elements in the map. Note that the position sequence is not necessarily the same as the key value sequence.

If the retrieved element is the last in the map, then the new value of rNextPosition is set to NULL.

For the rValue parameter, be sure to cast your object type to CObject*&, which is what the compiler requires, as shown in the following example:

         CObject* ob;
         map.GetNextAssoc(pos, key, (CObject*&)ob);      

This is not true of GetNextAssoc for maps based on templates.

The following table shows other member functions that are similar to CMapStringToOb::GetNextAssoc.

ClassMember Function
CMapPtrToPtrvoid GetNextAssoc( POSITION& rNextPosition , void*& rKey , void*& rValue ) const;
CMapPtrToWordvoid GetNextAssoc( POSITION& rNextPosition , void*& rKey , WORD& rValue ) const;
CMapStringToPtrvoid GetNextAssoc( POSITION& rNextPosition , CString& rKey , void*& rValue ) const;
CMapStringToStringvoid GetNextAssoc( POSITION& rNextPosition , CString& rKey , CString& rValue ) const;
CMapWordToObvoid GetNextAssoc( POSITION& rNextPosition , WORD& rKey , CObject*& rValue ) const;
CMapWordToPtrvoid GetNextAssoc( POSITION& rNextPosition , WORD& rKey , void*& rValue ) const;

Example

See CObList::CObList for a listing of the CAge class used in all collection examples.

         CMapStringToOb map;
         POSITION pos;
         CString key;
         CAge* pa;
         
         map.SetAt(_T("Bart"), new CAge(13));
         map.SetAt(_T("Lisa"), new CAge(11));
         map.SetAt(_T("Homer"), new CAge(36));
         map.SetAt(_T("Marge"), new CAge(35));
         // Iterate through the entire map, dumping both name and age.
         for (pos = map.GetStartPosition(); pos != NULL;)
         {
            map.GetNextAssoc(pos, key, (CObject*&)pa);
            #ifdef _DEBUG
                  afxDump << key << _T(" : ") << pa << _T("\n");
            #endif
         }

The results from this program are as follows:

Lisa : a CAge at $4724 11

Marge : a CAge at $47A8 35

Homer : a CAge at $4766 36

Bart : a CAge at $45D4 13

Returns the number of map elements.

INT_PTR GetSize() const;  

Return Value

The number of items in the map.

Remarks

Call this method to retrieve the number of elements in the map.

The following table shows other member functions that are similar to CMapStringToOb::GetSize.

ClassMember Function
CMapPtrToPtrINT_PTR GetSize( ) const;
CMapPtrToWordINT_PTR GetSize( ) const;
CMapStringToPtrINT_PTR GetSize( ) const;
CMapStringToStringINT_PTR GetSize( ) const;
CMapWordToObINT_PTR GetSize( ) const;
CMapWordToPtrINT_PTR GetSize( ) const;

Example

         CMapStringToOb map;

         map.SetAt(_T("Bart"), new CAge(13));
         map.SetAt(_T("Homer"), new CAge(36));
         ASSERT(map.GetSize() == 2);         

Starts a map iteration by returning a POSITION value that can be passed to a GetNextAssoc call.

POSITION GetStartPosition() const;  

Return Value

A POSITION value that indicates a starting position for iterating the map; or NULL if the map is empty.

Remarks

The iteration sequence is not predictable; therefore, the "first element in the map" has no special significance.

The following table shows other member functions that are similar to CMapStringToOb::GetStartPosition.

ClassMember Function
CMapPtrToPtrPOSITION GetStartPosition( ) const;
CMapPtrToWordPOSITION GetStartPosition( ) const;
CMapStringToPtrPOSITION GetStartPosition( ) const;
CMapStringToStringPOSITION GetStartPosition( ) const;
CMapWordToObPOSITION GetStartPosition( ) const;
CMapWordToPtrPOSITION GetStartPosition( ) const;

Example

See the example for CMapStringToOb::GetNextAssoc.

Calculates the hash value of a specified key.

UINT HashKey(LPCTSTR key) const;  

Parameters

key
The key whose hash value is to be calculated.

Return Value

The Key's hash value

Remarks

The following table shows other member functions that are similar to CMapStringToOb::HashKey.

ClassMember Function
CMapPtrToPtrUINT HashKey( void* key ) const;
CMapPtrToWordUINT HashKey( void* key ) const;
CMapStringToStringUINT HashKey( LPCTSTR key ) const;
CMapStringToPtrUINT HashKey( LPCTSTR key ) const;
CMapWordToObUINT HashKey( WORD key ) const;
CMapWordToPtrUINT HashKey( WORD key ) const;

Initializes the hash table.

void InitHashTable(
    UINT hashSize,  
    BOOL bAllocNow = TRUE);

Parameters

hashSize
Number of entries in the hash table.

bAllocNow
If TRUE, allocates the hash table upon initialization; otherwise the table is allocated when needed.

Remarks

For best performance, the hash table size should be a prime number. To minimize collisions, the size should be roughly 20 percent larger than the largest anticipated data set.

The following table shows other member functions that are similar to CMapStringToOb::InitHashTable.

ClassMember Function
CMapPtrToPtrvoid InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );
CMapPtrToWordvoid InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );
CMapStringToStringvoid InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );
CMapStringToPtrvoid InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );
CMapWordToObvoid InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );
CMapWordToPtrvoid InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE );

Determines whether the map is empty.

BOOL IsEmpty() const;  

Return Value

Nonzero if this map contains no elements; otherwise 0.

Example

See the example for RemoveAll.

Remarks

The following table shows other member functions that are similar to CMapStringToOb:: IsEmpty.

ClassMember Function
CMapPtrToPtrBOOL IsEmpty( ) const;
CMapPtrToWordBOOL IsEmpty( ) const;
CMapStringToPtrBOOL IsEmpty( ) const;
CMapStringToStringBOOL IsEmpty( ) const;
CMapWordToObBOOL IsEmpty( ) const;
CMapWordToPtrBOOL IsEmpty( ) const;

Returns a CObject pointer based on a CString value.

BOOL Lookup(
    LPCTSTR key,  
    CObject*& rValue) const;  

Parameters

key
Specifies the string key that identifies the element to be looked up.

rValue
Specifies the returned value from the looked-up element.

Return Value

Nonzero if the element was found; otherwise 0.

Remarks

Lookup uses a hashing algorithm to quickly find the map element with a key that matches exactly ( CString value).

The following table shows other member functions that are similar to CMapStringToOb::LookUp.

ClassMember Function
CMapPtrToPtrBOOL Lookup( void* key , void*& rValue ) const;
CMapPtrToWordBOOL Lookup( void* key , WORD& rValue ) const;
CMapStringToPtrBOOL Lookup( LPCTSTR key , void*& rValue ) const;
CMapStringToStringBOOL Lookup( LPCTSTR key , CString& rValue ) const;
CMapWordToObBOOL Lookup( WORD key , CObject*& rValue ) const;
CMapWordToPtrBOOL Lookup( WORD key , void*& rValue ) const;

Example

See CObList::CObList for a listing of the CAge class used in all collection examples.

         CMapStringToOb map;
         CAge* pa;

         map.SetAt(_T("Bart"), new CAge(13));
         map.SetAt(_T("Lisa"), new CAge(11));
         map.SetAt(_T("Homer"), new CAge(36));
         map.SetAt(_T("Marge"), new CAge(35));
         ASSERT(map.Lookup(_T("Lisa"), (CObject*&)pa)); // Is "Lisa" in the map?
         ASSERT(*pa ==  CAge(11)); // Is she 11?         

Returns a reference to the key associated with the specified key value.

BOOL LookupKey(
    LPCTSTR key,  
    LPCTSTR& rKey) const;  

Parameters

key
Specifies the string key that identifies the element to be looked up.

rKey
The reference to the associated key.

Return Value

Nonzero if the key was found; otherwise 0.

Remarks

Using a reference to a key is unsafe if used after the associated element was removed from the map or after the map was destroyed.

The following table shows other member functions that are similar to CMapStringToOb:: LookupKey.

ClassMember Function
CMapStringToPtrBOOL LookupKey( LPCTSTR key , LPCTSTR& rKey ) const;
CMapStringToStringBOOL LookupKey( LPCTSTR key , LPCTSTR& rKey ) const;

A convenient substitute for the SetAt member function.

CObject*& operator[ ](LPCTSTR key);

Return Value

A reference to a pointer to a CObject object; or NULL if the map is empty or key is out of range.

Remarks

Thus it can be used only on the left side of an assignment statement (an l-value). If there is no map element with the specified key, then a new element is created.

There is no "right side" (r-value) equivalent to this operator because there is a possibility that a key may not be found in the map. Use the Lookup member function for element retrieval.

The following table shows other member functions that are similar to CMapStringToOb::operator [].

ClassMember Function
CMapPtrToPtrvoid*& operator[]( void* key );
CMapPtrToWordWORD& operator[]( void* key );
CMapStringToPtrvoid*& operator[]( LPCTSTR key );
CMapStringToStringCString& operator[]( LPCTSTR key );
CMapWordToObCObject*& operator[]( WORD key );
CMapWordToPtrvoid*& operator[]( WORD key );

Example

See CObList::CObList for a listing of the CAge class used in all collection examples.

         CMapStringToOb map;
         
         map[_T("Bart")] = new CAge(13);
         map[_T("Lisa")] = new CAge(11);
         #ifdef _DEBUG
            afxDump.SetDepth(1);
            afxDump << _T("Operator [] example: ") << &map << _T("\n");
         #endif         

The results from this program are as follows:

Operator [] example: A CMapStringToOb with 2 elements

[Lisa] = a CAge at $4A02 11

[Bart] = a CAge at $497E 13

Removes all the elements from this map and destroys the CString key objects.

void RemoveAll();

Remarks

The CObject objects referenced by each key are not destroyed. The RemoveAll function can cause memory leaks if you do not ensure that the referenced CObject objects are destroyed.

The function works correctly if the map is already empty.

The following table shows other member functions that are similar to CMapStringToOb::RemoveAll.

ClassMember Function
CMapPtrToPtrvoid RemoveAll( );
CMapPtrToWordvoid RemoveAll( );
CMapStringToPtrvoid RemoveAll( );
CMapStringToStringvoid RemoveAll( );
CMapWordToObvoid RemoveAll( );
CMapWordToPtrvoid RemoveAll( );

Example

See CObList::CObList for a listing of the CAge class used in all collection examples.

         {
            CMapStringToOb map;

            CAge age1(13); // Two objects on the stack
            CAge age2(36);
            map.SetAt(_T("Bart"), &age1);
            map.SetAt(_T("Homer"), &age2);
            ASSERT(map.GetCount() == 2);
            map.RemoveAll(); // CObject pointers removed; objects not removed.
            ASSERT(map.GetCount() == 0);
            ASSERT(map.IsEmpty());
         } // The two CAge objects are deleted when they go out of scope.         

Looks up the map entry corresponding to the supplied key; then, if the key is found, removes the entry.

BOOL RemoveKey(LPCTSTR key);

Parameters

key
Specifies the string used for map lookup.

Return Value

Nonzero if the entry was found and successfully removed; otherwise 0.

Remarks

This can cause memory leaks if the CObject object is not deleted elsewhere.

The following table shows other member functions that are similar to CMapStringToOb::RemoveKey.

ClassMember Function
CMapPtrToPtrBOOL RemoveKey( void* key );
CMapPtrToWordBOOL RemoveKey( void* key );
CMapStringToPtrBOOL RemoveKey( LPCTSTR key );
CMapStringToStringBOOL RemoveKey( LPCTSTR key );
CMapWordToObBOOL RemoveKey( WORD key );
CMapWordToPtrBOOL RemoveKey( WORD key );

Example

See CObList::CObList for a listing of the CAge class used in all collection examples.

         CMapStringToOb map;
         
         map.SetAt(_T("Bart"), new CAge(13));
         map.SetAt(_T("Lisa"), new CAge(11));
         map.SetAt(_T("Homer"), new CAge(36));
         map.SetAt(_T("Marge"), new CAge(35));
         map.RemoveKey(_T("Lisa")); // Memory leak: CAge object not
                                    // deleted.
         #ifdef _DEBUG
            afxDump.SetDepth(1);
            afxDump << _T("RemoveKey example: ") << &map << _T("\n");
         #endif         

The results from this program are as follows:

RemoveKey example: A CMapStringToOb with 3 elements

[Marge] = a CAge at $49A0 35

[Homer] = a CAge at $495E 36

[Bart] = a CAge at $4634 13

The primary means to insert an element in a map.

void SetAt(
    LPCTSTR key,  
    CObject* newValue);

Parameters

key
Specifies the string that is the key of the new element.

newValue
Specifies the CObject pointer that is the value of the new element.

Remarks

First, the key is looked up. If the key is found, then the corresponding value is changed; otherwise a new key-value element is created.

The following table shows other member functions that are similar to CMapStringToOb::SetAt.

ClassMember Function
CMapPtrToPtrvoid SetAt( void* key , void* newValue );
CMapPtrToWordvoid SetAt( void* key , WORD newValue );
CMapStringToPtrvoid SetAt( LPCTSTR key , void* newValue );
CMapStringToStringvoid SetAt( LPCTSTR key , LPCTSTR newValue );
CMapWordToObvoid SetAt( WORD key , CObject* newValue );
CMapWordToPtrvoid SetAt( WORD key , void* newValue );

Example

See CObList::CObList for a listing of the CAge class used in all collection examples.

         CMapStringToOb map;
         CAge* pa;

         map.SetAt(_T("Bart"), new CAge(13));
         map.SetAt(_T("Lisa"), new CAge(11)); // Map contains 2 
                                                 // elements.
         #ifdef _DEBUG
            afxDump.SetDepth(1);
            afxDump << _T("before Lisa's birthday: ") << &map << _T("\n");
         #endif
         if (map.Lookup(_T("Lisa"), (CObject *&)pa))
         { // CAge 12 pointer replaces CAge 11 pointer.
            map.SetAt(_T("Lisa"), new CAge(12));
            delete pa;  // Must delete CAge 11 to avoid memory leak.
         }
         #ifdef _DEBUG
            afxDump << _T("after Lisa's birthday: ") << &map << _T("\n");
         #endif         

The results from this program are as follows:

before Lisa's birthday: A CMapStringToOb with 2 elements

[Lisa] = a CAge at $493C 11

[Bart] = a CAge at $4654 13

after Lisa's birthday: A CMapStringToOb with 2 elements

[Lisa] = a CAge at $49C0 12

[Bart] = a CAge at $4654 13

CObject Class
Hierarchy Chart
CMapPtrToPtr Class
CMapPtrToWord Class
CMapStringToPtr Class
CMapStringToString Class
CMapWordToOb Class
CMapWordToPtr Class

Show: