Map
Functions
|
|
void * |
|
const void * |
|
class T_As |
|
class T_As |
|
|
|
|
|
|
|
|
|
bool |
|
RED::uint64 |
|
void |
|
bool |
|
bool |
|
Item & |
|
const Item & |
|
Key & |
|
const Key & |
|
Item * |
|
const Item * |
|
void |
|
void |
|
void * |
|
bool |
|
bool |
|
Item & |
|
const Item & |
|
Key & |
|
const Key & |
|
Item * |
|
const Item * |
|
void |
|
|
|
|
|
void |
|
void |
|
void |
|
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
-
virtual void *As(const RED::CID &iCID)
Converts the object to an instance of the given type.
- Parameters
iCID – Requested class.
- Returns
An object pointer of the given class on success, NULL otherwise.
-
virtual const void *As(const RED::CID &iCID) const
Converts the object to an instance of the given type.
- Parameters
iCID – Requested class.
- Returns
An object pointer of the given class on success, NULL otherwise.
-
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.
-
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.
-
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 ¤t()
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.
-
Key ¤t_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.
-
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.
-
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.
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.
-
Key &mt_current_key(void *iParsingAddress)
Gets the current element key.
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.
-
Item *mt_find(void *&oParsingAddress, const Key &iKey)
Looks for an element value by its key.
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.
-
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)
-
virtual void *As(const RED::CID &iCID)
