taken over container

container/FixedOrderedMultimap.h

@@ -5,120 +5,200 @@
 #include <cstring>
 
 /**
- * @brief   Map implementation which allows entries with identical keys
+ * @brief  An associative container which allows multiple entries of the same key.
  * @details
- * Performs no dynamic memory allocation except on initialization.
+ * Same keys are ordered by KEY_COMPARE function which is std::less<key_t> > by default.
- * Uses an ArrayList as the underlying container and thus has a linear
+ *
+ * It uses the ArrayList, so technically this is not a real map, it is an array of pairs
+ * of type key_t, T. It is ordered by key_t as FixedMap but allows same keys. Thus it has a linear
  * complexity O(n). As long as the number of entries remains low, this
  * should not be an issue.
  * The number of insertion and deletion operation should be minimized
- * as those incur exensive memory move operations (the underlying container
+ * as those incur extensive memory move operations (the underlying container
  * is not node based).
- * @ingroup container
+ *
+ * Its of fixed size so no allocations are performed after the construction.
+ *
+ * The maximum size is given as first parameter of the constructor.
+ *
+ * It provides an iterator to do list iterations.
+ *
+ * The type T must have a copy constructor if it is not trivial copy-able.
+ *
+ * @warning Iterators return a non-const key_t in the pair.
+ * @warning A User is not allowed to change the key, otherwise the map is corrupted.
+ *
+ * \ingroup container
  */
 template<typename key_t, typename T, typename KEY_COMPARE = std::less<key_t>>
 class FixedOrderedMultimap {
 public:
 	static const uint8_t INTERFACE_ID = CLASS_ID::FIXED_MULTIMAP;
-	static const ReturnValue_t KEY_ALREADY_EXISTS = MAKE_RETURN_CODE(0x01);
+	static const ReturnValue_t MAP_FULL = MAKE_RETURN_CODE(0x01);
-	static const ReturnValue_t MAP_FULL = MAKE_RETURN_CODE(0x02);
+	static const ReturnValue_t KEY_DOES_NOT_EXIST = MAKE_RETURN_CODE(0x02);
-	static const ReturnValue_t KEY_DOES_NOT_EXIST = MAKE_RETURN_CODE(0x03);
 
-	/**
+	/***
-	 * Initializes the ordered multimap with a fixed maximum size.
+	 * Constructor which needs a size_t for the maximum allowed size
-	 * @param maxSize
+	 *
+	 * Can not be resized during runtime
+	 *
+	 * Allocates memory at construction
+	 * @param maxSize size_t of Maximum allowed size
 	 */
-    FixedOrderedMultimap(size_t maxSize);
+    FixedOrderedMultimap(size_t maxSize):theMap(maxSize), _size(0){
+    }
 
-    virtual ~FixedOrderedMultimap() {}
+	/***
+	 * Virtual destructor frees Memory by deleting its member
+	 */
+	virtual ~FixedOrderedMultimap() {
+	}
 
-    class Iterator: public ArrayList<std::pair<key_t, T>, uint32_t>::Iterator {
+	/***
+	 * Special iterator for FixedOrderedMultimap
+	 */
+	class Iterator: public ArrayList<std::pair<key_t, T>, size_t>::Iterator {
 	public:
-        /** Returns an iterator to nullptr */
+		Iterator() :
-        Iterator();
+			ArrayList<std::pair<key_t, T>, size_t>::Iterator() {
-        /** Initializes iterator to given entry */
+		}
-        Iterator(std::pair<key_t, T> *pair);
+
+		Iterator(std::pair<key_t, T> *pair) :
+			ArrayList<std::pair<key_t, T>, size_t>::Iterator(pair) {
+		}
 	};
 
-    /** Iterator to start of map */
+	/***
-    Iterator begin() const;
+	 * Returns an iterator pointing to the first element
-    /** Iterator to end of map */
+	 * @return Iterator pointing to first element
-    Iterator end() const;
+	 */
-    /** Current (variable) size of the map */
+	Iterator begin() const {
-    size_t size() const;
+		return Iterator(&theMap[0]);
+	}
 
 	/**
-     * Insert a key/value pair inside the map. An iterator to the stored
+	 * Returns an iterator pointing to one element past the end
-     * value might be returned optionally.
+	 * @return Iterator pointing to one element past the end
-     * @param key
+	 */
-     * @param value
+	Iterator end() const {
-     * @param storedValue
+		return Iterator(&theMap[_size]);
-     * @return
+	}
+
+	/***
+	 * Returns the current size of the map (not maximum size!)
+	 * @return Current size
+	 */
+	size_t size() const{
+		return _size;
+	}
+
+	/**
+	 * Clears the map, does not deallocate any memory
+	 */
+	void clear(){
+		_size = 0;
+	}
+
+	/**
+	 * Returns the maximum size of the map
+	 * @return Maximum size of the map
+	 */
+	size_t maxSize() const{
+		return theMap.maxSize();
+	}
+
+	/***
+	 * Used to insert a key and value separately.
+	 *
+	 * @param[in] key Key of the new element
+	 * @param[in] value Value of the new element
+	 * @param[in/out] (optional) storedValue On success this points to the new value, otherwise a nullptr
+	 * @return RETURN_OK if insert was successful, MAP_FULL if no space is available
 	 */
 	ReturnValue_t insert(key_t key, T value, Iterator *storedValue = nullptr);
-    /**
+
-     * Insert a given std::pair<key, value>
+	/***
-     * @param pair
+	 * Used to insert new pair instead of single values
-     * @return
+	 *
+	 * @param pair Pair to be inserted
+	 * @return RETURN_OK if insert was successful, MAP_FULL if no space is available
 	 */
 	ReturnValue_t insert(std::pair<key_t, T> pair);
-    /**
+
-     * Checks existence of key in map.
+	/***
-     * @param key
+	 * Can be used to check if a certain key is in the map
-     * @return
+	 * @param key Key to be checked
-     * - @c KEY_DOES_NOT_EXIST if key does not exists.
+	 * @return RETURN_OK if the key exists KEY_DOES_NOT_EXIST otherwise
-     * - @c RETURN_OK otherwise.
 	 */
 	ReturnValue_t exists(key_t key) const;
 
+	/***
+	 * Used to delete the element in the iterator
+	 *
+	 * The iterator will point to the element before or begin(),
+	 *  but never to one element in front of the map.
+	 *
+	 * @warning The iterator needs to be valid and dereferenceable
+	 * @param[in/out] iter Pointer to iterator to the element that needs to be ereased
+	 * @return RETURN_OK if erased, KEY_DOES_NOT_EXIST if the there is no element like this
+	 */
 	ReturnValue_t erase(Iterator *iter);
+
+	/***
+	 * Used to erase by key
+	 * @param key Key to be erased
+	 * @return RETURN_OK if erased, KEY_DOES_NOT_EXIST if the there is no element like this
+	 */
 	ReturnValue_t erase(key_t key);
 
-    Iterator find(key_t key) const;
+	/***
+	 * Find returns the first appearance of the key
+	 *
+	 * If the key does not exist, it points to end()
+	 *
+	 * @param key Key to search for
+	 * @return Iterator pointing to the first entry of key
+	 */
+	Iterator find(key_t key) const{
+		ReturnValue_t result = exists(key);
+		if (result != HasReturnvaluesIF::RETURN_OK) {
+			return end();
+		}
+		return Iterator(&theMap[findFirstIndex(key)]);
+	};
+
+	/***
+	 * Finds first entry of the given key and returns a
+	 * pointer to the value
+	 *
+	 * @param key Key to search for
+	 * @param value Found value
+	 * @return RETURN_OK if it points to the value,
+	 * KEY_DOES_NOT_EXIST if the key is not in the map
+	 */
 	ReturnValue_t find(key_t key, T **value) const;
 
-    void clear();
+	friend bool operator==(const typename FixedOrderedMultimap::Iterator& lhs,
+			const typename FixedOrderedMultimap::Iterator& rhs) {
+		return (lhs.value == rhs.value);
+	}
 
-    size_t maxSize() const;
+	friend bool operator!=(const typename FixedOrderedMultimap::Iterator& lhs,
+			const typename FixedOrderedMultimap::Iterator& rhs) {
+		return not (lhs.value == rhs.value);
+	}
 
 private:
 	typedef KEY_COMPARE compare;
 	compare myComp;
-	ArrayList<std::pair<key_t, T>, uint32_t> theMap;
+	ArrayList<std::pair<key_t, T>, size_t> theMap;
 	size_t _size;
 
-	uint32_t findFirstIndex(key_t key, uint32_t startAt = 0) const {
+	size_t findFirstIndex(key_t key, size_t startAt = 0) const;
-		if (startAt >= _size) {
-			return startAt + 1;
-		}
-		uint32_t i = startAt;
-		for (i = startAt; i < _size; ++i) {
-			if (theMap[i].first == key) {
-				return i;
-			}
-		}
-		return i;
-	}
 
-	uint32_t findNicePlace(key_t key) const {
+	size_t findNicePlace(key_t key) const;
-		uint32_t i = 0;
-		for (i = 0; i < _size; ++i) {
-			if (myComp(key, theMap[i].first)) {
-				return i;
-			}
-		}
-		return i;
-	}
 
-	void removeFromPosition(uint32_t position) {
+	void removeFromPosition(size_t position);
-		if (_size <= position) {
-			return;
-		}
-		std::memmove(static_cast<void*>(&theMap[position]),
-		        static_cast<void*>(&theMap[position + 1]),
-				(_size - position - 1) * sizeof(std::pair<key_t,T>));
-		--_size;
-	}
 };
 
 #include "FixedOrderedMultimap.tpp"

container/FixedOrderedMultimap.tpp

@@ -1,50 +1,14 @@
 #ifndef FRAMEWORK_CONTAINER_FIXEDORDEREDMULTIMAP_TPP_
 #define FRAMEWORK_CONTAINER_FIXEDORDEREDMULTIMAP_TPP_
 
-template<typename key_t, typename T, typename KEY_COMPARE>
-inline FixedOrderedMultimap<key_t, T, KEY_COMPARE>::Iterator::Iterator():
-        ArrayList<std::pair<key_t, T>, uint32_t>::Iterator(){}
 
 template<typename key_t, typename T, typename KEY_COMPARE>
-inline FixedOrderedMultimap<key_t, T, KEY_COMPARE>::Iterator::Iterator(
+inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::insert(key_t key, T value, Iterator *storedValue) {
-        std::pair<key_t, T> *pair):
-        ArrayList<std::pair<key_t, T>, uint32_t>::Iterator(pair){}
-
-template<typename key_t, typename T, typename KEY_COMPARE>
-inline typename FixedOrderedMultimap<key_t, T, KEY_COMPARE>::Iterator
-FixedOrderedMultimap<key_t, T, KEY_COMPARE>::begin() const {
-    return Iterator(&theMap[0]);
-}
-
-template<typename key_t, typename T, typename KEY_COMPARE>
-inline typename FixedOrderedMultimap<key_t, T, KEY_COMPARE>::Iterator
-FixedOrderedMultimap<key_t, T, KEY_COMPARE>::end() const {
-    return Iterator(&theMap[_size]);
-}
-
-
-template<typename key_t, typename T, typename KEY_COMPARE>
-inline size_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::size() const {
-    return _size;
-}
-
-template<typename key_t, typename T, typename KEY_COMPARE>
-inline FixedOrderedMultimap<key_t, T, KEY_COMPARE>::FixedOrderedMultimap(
-        size_t maxSize): theMap(maxSize), _size(0) {}
-
-
-template<typename key_t, typename T, typename KEY_COMPARE>
-inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::insert(
-        key_t key, T value, Iterator *storedValue) {
 	if (_size == theMap.maxSize()) {
 		return MAP_FULL;
 	}
-    uint32_t position = findNicePlace(key);
+	size_t position = findNicePlace(key);
-    // Compiler might emitt warning because std::pair is not a POD type (yet..)
+	memmove(static_cast<void*>(&theMap[position + 1]),static_cast<void*>(&theMap[position]),
-    // See: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2342.htm#std::pair-example
-    // Circumvent warning by casting to void*
-    std::memmove(static_cast<void*>(&theMap[position + 1]),
-            static_cast<void*>(&theMap[position]),
 			(_size - position) * sizeof(std::pair<key_t,T>));
 	theMap[position].first = key;
 	theMap[position].second = value;
@@ -54,16 +18,13 @@ inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::insert(
 	}
 	return HasReturnvaluesIF::RETURN_OK;
 }
-
 template<typename key_t, typename T, typename KEY_COMPARE>
-inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::insert(
+inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::insert(std::pair<key_t, T> pair) {
-        std::pair<key_t, T> pair) {
+	return insert(pair.first, pair.second);
-    return insert(pair.fist, pair.second);
 }
 
 template<typename key_t, typename T, typename KEY_COMPARE>
-inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::exists(
+inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::exists(key_t key) const {
-        key_t key) const {
 	ReturnValue_t result = KEY_DOES_NOT_EXIST;
 	if (findFirstIndex(key) < _size) {
 		result = HasReturnvaluesIF::RETURN_OK;
@@ -72,10 +33,8 @@ inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::exists(
 }
 
 template<typename key_t, typename T, typename KEY_COMPARE>
-inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::erase(
+inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::erase(Iterator *iter) {
-        Iterator *iter)
+	size_t i;
-{
-    uint32_t i;
 	if ((i = findFirstIndex((*iter).value->first)) >= _size) {
 		return KEY_DOES_NOT_EXIST;
 	}
@@ -89,10 +48,8 @@ inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::erase(
 }
 
 template<typename key_t, typename T, typename KEY_COMPARE>
-inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::erase(
+inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::erase(key_t key) {
-        key_t key)
+	size_t i;
-{
-    uint32_t i;
 	if ((i = findFirstIndex(key)) >= _size) {
 		return KEY_DOES_NOT_EXIST;
 	}
@@ -104,9 +61,7 @@ inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::erase(
 }
 
 template<typename key_t, typename T, typename KEY_COMPARE>
-inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::find(
+inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::find(key_t key, T **value) const {
-        key_t key, T **value) const
-{
 	ReturnValue_t result = exists(key);
 	if (result != HasReturnvaluesIF::RETURN_OK) {
 		return result;
@@ -116,27 +71,38 @@ inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::find(
 }
 
 template<typename key_t, typename T, typename KEY_COMPARE>
-inline typename FixedOrderedMultimap<key_t, T, KEY_COMPARE>::Iterator
+inline size_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::findFirstIndex(key_t key, size_t startAt) const {
-FixedOrderedMultimap<key_t, T, KEY_COMPARE>::find(
+	if (startAt >= _size) {
-        key_t key) const
+		return startAt + 1;
-{
-    ReturnValue_t result = exists(key);
-    if (result != HasReturnvaluesIF::RETURN_OK) {
-        return end();
 	}
-    return Iterator(&theMap[findFirstIndex(key)]);
+	size_t i = startAt;
+	for (i = startAt; i < _size; ++i) {
+		if (theMap[i].first == key) {
+			return i;
+		}
+	}
+	return i;
 }
 
 template<typename key_t, typename T, typename KEY_COMPARE>
-inline void FixedOrderedMultimap<key_t, T, KEY_COMPARE>::clear()
+inline size_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::findNicePlace(key_t key) const {
-{
+	size_t i = 0;
-    _size = 0;
+	for (i = 0; i < _size; ++i) {
+		if (myComp(key, theMap[i].first)) {
+			return i;
+		}
+	}
+	return i;
 }
 
 template<typename key_t, typename T, typename KEY_COMPARE>
-inline size_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::maxSize() const
+inline void FixedOrderedMultimap<key_t, T, KEY_COMPARE>::removeFromPosition(size_t position) {
-{
+	if (_size <= position) {
-    return theMap.maxSize();
+		return;
+	}
+	memmove(static_cast<void*>(&theMap[position]), static_cast<void*>(&theMap[position + 1]),
+			(_size - position - 1) * sizeof(std::pair<key_t,T>));
+	--_size;
 }