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.