CSimpleMap Class

 

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

This class provides support for a simple mapping array.

template <class TKey, class TVal, class TEqual = CSimpleMapEqualHelper<TKey, TVal>>  
class CSimpleMap

Parameters

TKey
The key element type.

TVal
The value element type.

TEqual
A trait object, defining the equality test for elements of type T.

Public Typedefs

NameDescription
CSimpleMap::_ArrayElementTypeTypedef for the value type.
CSimpleMap::_ArrayKeyTypeTypedef for the key type.

Public Constructors

NameDescription
CSimpleMap::CSimpleMapThe constructor.
CSimpleMap::~CSimpleMapThe destructor.

Public Methods

NameDescription
CSimpleMap::AddAdds a key and associated value to the map array.
CSimpleMap::FindKeyFinds a specific key.
CSimpleMap::FindValFinds a specific value.
CSimpleMap::GetKeyAtRetrieves the specified key.
CSimpleMap::GetSizeReturns the number of entries in the mapping array.
CSimpleMap::GetValueAtRetrieves the specified value.
CSimpleMap::LookupReturns the value associated with the given key.
CSimpleMap::RemoveRemoves a key and matching value.
CSimpleMap::RemoveAllRemoves all keys and values.
CSimpleMap::RemoveAtRemoves a specific key and matching value.
CSimpleMap::ReverseLookupReturns the key associated with the given value.
CSimpleMap::SetAtSets the value associated with the given key.
CSimpleMap::SetAtIndexSets the specific key and value.

CSimpleMap provides support for a simple mapping array of any given type T, managing an unordered array of key elements and their associated values.

The parameter TEqual provides a means of defining an equality function for two elements of type T. By creating a class similar to CSimpleMapEqualHelper, it is possible to alter the behavior of the equality test for any given array. For example, when dealing with an array of pointers, it may be useful to define the equality as depending on the values the pointers reference. The default implementation utilizes operator==().

Both CSimpleMap and CSimpleArray are provided for compatibility with previous ATL releases, and more complete and efficient collection implementations are provided by CAtlArray and CAtlMap.

Unlike other map collections in ATL and MFC, this class is implemented with a simple array, and lookup searches require a linear search. CAtlMap should be used when the array contains a large number of elements.

Header: atlsimpcoll.h

   // Create a map with an integer key and character pointer value
   CSimpleMap<int, char *> iArray;   

Adds a key and associated value to the map array.

BOOL Add(const TKey& key, const TVal& val);

Parameters

key
The key.

val
The associated value.

Return Value

Returns TRUE if the key and value were successfully added, FALSE otherwise.

Remarks

Each key and value pair added causes the mapping array memory to be freed and reallocated, in order to ensure the data for each is always stored contiguously. That is, the second key element always directly follows the first key element in memory and so on.

A typedef for the key type.

typedef TVal _ArrayElementType;

A typedef for the value type.

typedef TKey _ArrayKeyType;

The constructor.

CSimpleMap();

Remarks

Initializes the data members.

The destructor.

~CSimpleMap();

Remarks

Frees all allocated resources.

Finds a specific key.

int FindKey(const TKey& key) const;

Parameters

key
The key to search for.

Return Value

Returns the index of the key if found, otherwise returns -1.

Finds a specific value.

int FindVal(const TVal& val) const;

Parameters

val
The value for which to search.

Return Value

Returns the index of the value if it is found, otherwise returns -1.

Retrieves the key at the specified index.

TKey& GetKeyAt(int nIndex) const;

Parameters

nIndex
The index of the key to return.

Return Value

Returns the key referenced by nIndex.

Remarks

The index passed by nIndex must be valid for the return value to be meaningful.

Returns the number of entries in the mapping array.

int GetSize() const;

Return Value

Returns the number of entries (a key and value is one entry) in the mapping array.

Retrieves the value at the specific index.

TVal& GetValueAt(int nIndex) const;

Parameters

nIndex
The index of the value to return.

Return Value

Returns the value referenced by nIndex.

Remarks

The index passed by nIndex must be valid for the return value to be meaningful.

Returns the value associated with the given key.

TVal Lookup(const TKey& key) const;

Parameters

key
The key.

Return Value

Returns the associated value. If no matching key is found, NULL is returned.

Removes a key and matching value.

BOOL Remove(const TKey& key);

Parameters

key
The key.

Return Value

Returns TRUE if the key, and matching value, were successfully removed, FALSE otherwise.

Removes all keys and values.

void RemoveAll();

Remarks

Removes all keys and values from the mapping array object.

Removes a key and associated value at the specified index.

BOOL RemoveAt(int nIndex);

Parameters

nIndex
The index of the key and associated value to remove.

Return Value

Returns TRUE on success, FALSE if the index specified is an invalid index.

Returns the key associated with the given value.

TKey ReverseLookup(const TVal& val) const;

Parameters

val
The value.

Return Value

Returns the associated key. If no matching key is found, NULL is returned.

Sets the value associated with the given key.

BOOL SetAt(const TKey& key, const TVal& val);

Parameters

key
The key.

val
The new value to assign.

Return Value

Returns TRUE if the key was found, and the value was successfully changed, FALSE otherwise.

Sets the key and value at a specified index.

BOOL SetAtIndex(  
    int nIndex,
    const TKey& key,
    const TVal& val);

Parameters

nIndex
The index, referencing the key and value pairing to change.

key
The new key.

val
The new value.

Return Value

Returns TRUE if successful, FALSE if the index was not valid.

Remarks

Updates both the key and value pointed to by nIndex.

Class Overview

Show: