CSimpleMap Class

This class provides support for a simple mapping array.

Syntax

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.

Members

Public Typedefs

Public Constructors

Public Methods

Remarks

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.

Requirements

Header: atlsimpcoll.h

Example

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

CSimpleMap::Add

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.

CSimpleMap::_ArrayElementType

A typedef for the key type.

typedef TVal _ArrayElementType;

CSimpleMap::_ArrayKeyType

A typedef for the value type.

typedef TKey _ArrayKeyType;

CSimpleMap::CSimpleMap

The constructor.

CSimpleMap();

Remarks

Initializes the data members.

CSimpleMap::~CSimpleMap

The destructor.

~CSimpleMap();

Remarks

Frees all allocated resources.

CSimpleMap::FindKey

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.

CSimpleMap::FindVal

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.

CSimpleMap::GetKeyAt

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.

CSimpleMap::GetSize

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.

CSimpleMap::GetValueAt

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.

CSimpleMap::Lookup

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.

CSimpleMap::Remove

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.

CSimpleMap::RemoveAll

Removes all keys and values.

void RemoveAll();

Remarks

Removes all keys and values from the mapping array object.

CSimpleMap::RemoveAt

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.

CSimpleMap::ReverseLookup

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.

CSimpleMap::SetAt

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.

CSimpleMap::SetAtIndex

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.

See also

Class Overview