Map

Functions

	`SET_CID`
	`IMPLEMENT_AS`
	`Map`
	`Map`
	`~Map`
`RED_RC`	`operator=`
bool	`empty`
RED::uint64	`size`
void	`begin`
bool	`end`
bool	`next`
Item &	`current`
const Item &	`current`
Key &	`current_key`
const Key &	`current_key`
Item *	`find`
const Item *	`find`
void	`save_parsing`
void	`restore_parsing`
void *	`mt_begin`
bool	`mt_end`
bool	`mt_next`
Item &	`mt_current`
const Item &	`mt_current`
Key &	`mt_current_key`
const Key &	`mt_current_key`
Item *	`mt_find`
const Item *	`mt_find`
void	`clear`
`RED_RC`	`insert`
`RED_RC`	`insert`
void	`erase_current`
void	`mt_erase_current`
void	`erase`

Detailed Description

template<class Key, class Item> class Map : public RED::Object 

Binary tree for template scalars. Similar to the std::map class.

@related class RED::Vector

The Map implements a binary search tree. The algorithm used is based on the red-black tree balance method to ensure that the entire tree remains properly balanced all the times.

Red-black tree rules are:

1) A tree node is either RED or BLACK. 2) The root node is BLACK. 3) All leaves are BLACK (we assume that every item with data in our tree is a node and has NULL leaves that are considered black). 4) Both children of a RED node are BLACK. 5) All paths from any given node to its leaf nodes contain the same number of black nodes.

The ‘Key’ and the ‘Item’ may be scalars and / or classes.

The Map class is not thread-safe for all operations that may change it’s contents. It has two parsing APIs: one which is not thread safe and one which is thread safe and prefixed by ‘mt_’ in the method names used.

Public Functions

SET_CID(CID_class_REDMap)

IMPLEMENT_AS()

Map(): Map default construction method.

Map(const Map<Key, Item> &iSource)

Map copy construction method.

The memory capacity of ‘this’ is set to the actual size of ‘iSource’.

Parameters:	iSource – Item source defining our contents.

virtual ~Map(): Map destruction method.

RED_RC operator=(const Map<Key, Item> &iSource)

Assignment operator.

The memory capacity of ‘this’ is set to the actual size of ‘iSource’.

Parameters:	iSource – Source overwriting our current contents.
Returns:	RED_OK when the assignment succeeded, RED_ALLOC_FAILURE if an internal allocation did fail.

bool empty() const

Returns:	true if the map is empty, false if the map is not empty.

RED::uint64 size() const

Returns:	The number of Objects in the map.

void begin() const

Initializes the map parsing.

This is not a thread safe operation refer to ‘mt_begin’ for a thread safe map parsing.

bool end() const

Checks whether we have reached the last map element.

This is not a thread safe operation refer to ‘mt_end’ for a thread safe map parsing.

Returns:	true if the map parsing is finished.

bool next() const

Moves to the next map element.

This is not a thread safe operation refer to ‘mt_next’ for a thread safe map parsing.

Returns:	true if we have a valid element after that call, false if we have finished the map parsing.

Item &current()

Gets the current element value.

This is not a thread safe operation refer to ‘mt_current’ for a thread safe map parsing.

The current element value is valid if:

We are parsing the map contents.
OR after a call to Map::find.

Returns:	the element value.

const Item &current() const

Key &current_key()

Gets the current element key.

This is not a thread safe operation refer to ‘mt_current_key’ for a thread safe map parsing.

The current element key is valid if:

We are parsing the map contents.
OR after a call to Map::find.

Returns:	the element key.

const Key &current_key() const

Item *find(const Key &iKey)

Looks for an element value by its key.

This is not a thread safe operation refer to ‘mt_find’ for a thread safe map parsing.

The current element is set to the result of the research. No call to this method should be issued during a map parsing. Note that after a find, Map::erase_current can be issued.

Parameters:	iKey – Searched element key.
Returns:	The address of the searched element. NULL when not found.

const Item *find(const Key &iKey) const

void save_parsing() const

Saves the parsing position.

This is not a thread safe operation.

Saves the current parsing position. It can be restored with a call to Map::restore_parsing.

void restore_parsing() const

Restores the parsing position.

This is not a thread safe operation.

Restores a previously saved parsing position. Note that the contents of the map must not have changed between Map::save_parsing and Map::restore_parsing.

void *mt_begin() const

Initializes the map parsing.

Thread safe method.

Returns:	A parsing address to reuse for all ‘mt_’ map parsing operations. This parsing address can be seen as an iterator.

bool mt_end(void *iParsingAddress) const

Checks whether we have reached the last map element.

Thread safe method.

Parameters:	iParsingAddress – The current parsing address.
Returns:	true if the map parsing is finished.

bool mt_next(void *&ioParsingAddress) const

Moves to the next map element.

Thread safe method.

Parameters:	ioParsingAddress – The current parsing address.
Returns:	true if we have a valid element after that call, false if we have finished the map parsing.

Item &mt_current(void *iParsingAddress)

Gets the current element value.

Thread

safe method.

The current element value is valid if:

We are parsing the map contents.
OR after a call to Map::find.

Parameters:	iParsingAddress – The current parsing address.
Returns:	the element value.

const Item &mt_current(void *iParsingAddress) const

Key &mt_current_key(void *iParsingAddress)

Gets the current element key.

Thread

safe method.

The current element key is valid if:

We are parsing the map contents.
OR after a call to Map::find.

Parameters:	iParsingAddress – The current parsing address.
Returns:	the element key.

const Key &mt_current_key(void *iParsingAddress) const

Item *mt_find(void *&oParsingAddress, const Key &iKey)

Looks for an element value by its key.

Thread

safe method.

The current element is set to the result of the research thanks to the parsing address. No call to this method should be issued during a map parsing.

Parameters:	oParsingAddress – The parsing address to reuse or access the current element using the ‘mt_’ parsing API. This parsing address can be seen as an iterator. iKey – Searched element key.
Returns:	The address of the searched element. NULL when not found.

const Item *mt_find(void *&oParsingAddress, const Key &iKey) const

void clear()

Erases the contents of the map.

All Objects in the map are destroyed. All map storage memory is released.

RED_RC insert(const Key &iKey, const Item &iValue)

Inserts an element in the map.

Multiple insertions of values with the same key do not produce any changes to the map.

Parameters:

iKey – Insertion key.
iValue – Insertion object value.

Returns:

RED_OK when the insertion succeeded,

RED_ALLOC_FAILURE if an internal allocation did fail.

RED_RC insert(bool &oInsert, const Key &iKey, const Item &iValue)

Inserts an element in the map.

Multiple insertions of values with the same key do not produce any changes to the map.

Parameters:

oInsert – Set to true when the element has been successfully inserted in the map, false if ‘iKey’ existed already in the map.
iKey – Insertion key.
iValue – Insertion object value.

Returns:

RED_OK when the insertion succeeded,

RED_ALLOC_FAILURE if an internal allocation did fail.

void erase_current()

Erases the current element in the map parsing.

The current element in the map parsing, or that was found is being erased by the call. The ‘cursor’ is set to the next element in the map after the deletion.

void mt_erase_current(void *&oParsingAddress)

void erase(const Key &iKey)

Erases an element by its key.

Parameters:	iKey – Key used to look for the element.