Merge branch 'master' into mueller/tcDistribution

container/FixedOrderedMultimap.h

@@ -1,10 +1,33 @@
-#ifndef FRAMEWORK_CONTAINER_FIXEDORDEREDMULTIMAP_H_
+#ifndef FSFW_CONTAINER_FIXEDORDEREDMULTIMAP_H_
-#define FRAMEWORK_CONTAINER_FIXEDORDEREDMULTIMAP_H_
+#define FSFW_CONTAINER_FIXEDORDEREDMULTIMAP_H_
 
 #include "ArrayList.h"
 #include <cstring>
-#include <set>
+
 /**
+ * @brief  An associative container which allows multiple entries of the same key.
+ * @details
+ * Same keys are ordered by KEY_COMPARE function which is std::less<key_t> > by default.
+ *
+ * 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 extensive memory move operations (the underlying container
+ * is not node based).
+ *
+ * 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>>
@@ -14,152 +37,170 @@ public:
 	static const ReturnValue_t MAP_FULL = MAKE_RETURN_CODE(0x01);
 	static const ReturnValue_t KEY_DOES_NOT_EXIST = MAKE_RETURN_CODE(0x02);
 
-private:
+	/***
-	typedef KEY_COMPARE compare;
+	 * Constructor which needs a size_t for the maximum allowed size
-	compare myComp;
+	 *
-	ArrayList<std::pair<key_t, T>, uint32_t> theMap;
+	 * Can not be resized during runtime
-	uint32_t _size;
+	 *
-
+	 * Allocates memory at construction
-	uint32_t findFirstIndex(key_t key, uint32_t startAt = 0) const {
+	 * @param maxSize size_t of Maximum allowed size
-		if (startAt >= _size) {
+	 */
-			return startAt + 1;
+    FixedOrderedMultimap(size_t maxSize):theMap(maxSize), _size(0){
-		}
-		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 {
+	/***
-		uint32_t i = 0;
+	 * Virtual destructor frees Memory by deleting its member
-		for (i = 0; i < _size; ++i) {
+	 */
-			if (myComp(key, theMap[i].first)) {
-				return i;
-			}
-		}
-		return i;
-	}
-
-	void removeFromPosition(uint32_t position) {
-		if (_size <= position) {
-			return;
-		}
-		memmove(static_cast<void*>(&theMap[position]), static_cast<void*>(&theMap[position + 1]),
-				(_size - position - 1) * sizeof(std::pair<key_t,T>));
-		--_size;
-	}
-public:
-	FixedOrderedMultimap(uint32_t maxSize) :
-			theMap(maxSize), _size(0) {
-	}
 	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:
 		Iterator() :
-				ArrayList<std::pair<key_t, T>, uint32_t>::Iterator() {
+			ArrayList<std::pair<key_t, T>, size_t>::Iterator() {
 		}
 
 		Iterator(std::pair<key_t, T> *pair) :
-				ArrayList<std::pair<key_t, T>, uint32_t>::Iterator(pair) {
+			ArrayList<std::pair<key_t, T>, size_t>::Iterator(pair) {
 		}
 	};
 
+	/***
+	 * Returns an iterator pointing to the first element
+	 * @return Iterator pointing to first element
+	 */
 	Iterator begin() const {
 		return Iterator(&theMap[0]);
 	}
 
+	/**
+	 * Returns an iterator pointing to one element past the end
+	 * @return Iterator pointing to one element past the end
+	 */
 	Iterator end() const {
 		return Iterator(&theMap[_size]);
 	}
 
-	uint32_t size() const {
+	/***
+	 * Returns the current size of the map (not maximum size!)
+	 * @return Current size
+	 */
+	size_t size() const{
 		return _size;
 	}
 
-	ReturnValue_t insert(key_t key, T value, Iterator *storedValue = nullptr) {
+	/**
-		if (_size == theMap.maxSize()) {
+	 * Clears the map, does not deallocate any memory
-			return MAP_FULL;
+	 */
-		}
+	void clear(){
-		uint32_t position = findNicePlace(key);
+		_size = 0;
-		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;
-		++_size;
-		if (storedValue != nullptr) {
-			*storedValue = Iterator(&theMap[position]);
-		}
-		return HasReturnvaluesIF::RETURN_OK;
 	}
 
-	ReturnValue_t insert(std::pair<key_t, T> pair) {
+	/**
-		return insert(pair.first, pair.second);
+	 * Returns the maximum size of the map
+	 * @return Maximum size of the map
+	 */
+	size_t maxSize() const{
+		return theMap.maxSize();
 	}
 
-	ReturnValue_t exists(key_t key) const {
+	/***
-		ReturnValue_t result = KEY_DOES_NOT_EXIST;
+	 * Used to insert a key and value separately.
-		if (findFirstIndex(key) < _size) {
+	 *
-			result = HasReturnvaluesIF::RETURN_OK;
+	 * @param[in] key Key of the new element
-		}
+	 * @param[in] value Value of the new element
-		return result;
+	 * @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);
 
-	ReturnValue_t erase(Iterator *iter) {
+	/***
-		uint32_t i;
+	 * Used to insert new pair instead of single values
-		if ((i = findFirstIndex((*iter).value->first)) >= _size) {
+	 *
-			return KEY_DOES_NOT_EXIST;
+	 * @param pair Pair to be inserted
-		}
+	 * @return RETURN_OK if insert was successful, MAP_FULL if no space is available
-		removeFromPosition(i);
+	 */
-		if (*iter != begin()) {
+	ReturnValue_t insert(std::pair<key_t, T> pair);
-			(*iter)--;
-		} else {
-			*iter = begin();
-		}
-		return HasReturnvaluesIF::RETURN_OK;
-	}
 
-	ReturnValue_t erase(key_t key) {
+	/***
-		uint32_t i;
+	 * Can be used to check if a certain key is in the map
-		if ((i = findFirstIndex(key)) >= _size) {
+	 * @param key Key to be checked
-			return KEY_DOES_NOT_EXIST;
+	 * @return RETURN_OK if the key exists KEY_DOES_NOT_EXIST otherwise
-		}
+	 */
-		do {
+	ReturnValue_t exists(key_t key) const;
-			removeFromPosition(i);
-			i = findFirstIndex(key, i);
-		} while (i < _size);
-		return HasReturnvaluesIF::RETURN_OK;
-	}
 
+	/***
+	 * 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);
+
+	/***
+	 * 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)]);
-	}
-
-	ReturnValue_t find(key_t key, T **value) const {
-		ReturnValue_t result = exists(key);
-		if (result != HasReturnvaluesIF::RETURN_OK) {
-			return result;
-		}
-		*value = &theMap[findFirstIndex(key)].second;
-		return HasReturnvaluesIF::RETURN_OK;
-	}
-
-	void clear() {
-		_size = 0;
-	}
-
-	uint32_t maxSize() const {
-		return theMap.maxSize();
-	}
-
 	};
 
-#endif /* FRAMEWORK_CONTAINER_FIXEDORDEREDMULTIMAP_H_ */
+	/***
+	 * 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;
+
+	friend bool operator==(const typename FixedOrderedMultimap::Iterator& lhs,
+			const typename FixedOrderedMultimap::Iterator& rhs) {
+		return (lhs.value == rhs.value);
+	}
+
+	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>, size_t> theMap;
+	size_t _size;
+
+	size_t findFirstIndex(key_t key, size_t startAt = 0) const;
+
+	size_t findNicePlace(key_t key) const;
+
+	void removeFromPosition(size_t position);
+};
+
+#include "FixedOrderedMultimap.tpp"
+
+#endif /* FSFW_CONTAINER_FIXEDORDEREDMULTIMAP_H_ */

container/FixedOrderedMultimap.tpp

@@ -0,0 +1,109 @@
+#ifndef FRAMEWORK_CONTAINER_FIXEDORDEREDMULTIMAP_TPP_
+#define FRAMEWORK_CONTAINER_FIXEDORDEREDMULTIMAP_TPP_
+
+
+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;
+	}
+	size_t position = findNicePlace(key);
+	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;
+	++_size;
+	if (storedValue != nullptr) {
+		*storedValue = Iterator(&theMap[position]);
+	}
+	return HasReturnvaluesIF::RETURN_OK;
+}
+template<typename key_t, typename T, typename KEY_COMPARE>
+inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::insert(std::pair<key_t, T> pair) {
+	return insert(pair.first, pair.second);
+}
+
+template<typename key_t, typename T, typename KEY_COMPARE>
+inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::exists(key_t key) const {
+	ReturnValue_t result = KEY_DOES_NOT_EXIST;
+	if (findFirstIndex(key) < _size) {
+		result = HasReturnvaluesIF::RETURN_OK;
+	}
+	return result;
+}
+
+template<typename key_t, typename T, typename KEY_COMPARE>
+inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::erase(Iterator *iter) {
+	size_t i;
+	if ((i = findFirstIndex((*iter).value->first)) >= _size) {
+		return KEY_DOES_NOT_EXIST;
+	}
+	removeFromPosition(i);
+	if (*iter != begin()) {
+		(*iter)--;
+	} else {
+		*iter = begin();
+	}
+	return HasReturnvaluesIF::RETURN_OK;
+}
+
+template<typename key_t, typename T, typename KEY_COMPARE>
+inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::erase(key_t key) {
+	size_t i;
+	if ((i = findFirstIndex(key)) >= _size) {
+		return KEY_DOES_NOT_EXIST;
+	}
+	do {
+		removeFromPosition(i);
+		i = findFirstIndex(key, i);
+	} while (i < _size);
+	return HasReturnvaluesIF::RETURN_OK;
+}
+
+template<typename key_t, typename T, typename KEY_COMPARE>
+inline ReturnValue_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::find(key_t key, T **value) const {
+	ReturnValue_t result = exists(key);
+	if (result != HasReturnvaluesIF::RETURN_OK) {
+		return result;
+	}
+	*value = &theMap[findFirstIndex(key)].second;
+	return HasReturnvaluesIF::RETURN_OK;
+}
+
+template<typename key_t, typename T, typename KEY_COMPARE>
+inline size_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::findFirstIndex(key_t key, size_t startAt) const {
+	if (startAt >= _size) {
+		return startAt + 1;
+	}
+	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 size_t FixedOrderedMultimap<key_t, T, KEY_COMPARE>::findNicePlace(key_t key) const {
+	size_t i = 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 void FixedOrderedMultimap<key_t, T, KEY_COMPARE>::removeFromPosition(size_t position) {
+	if (_size <= position) {
+		return;
+	}
+	memmove(static_cast<void*>(&theMap[position]), static_cast<void*>(&theMap[position + 1]),
+			(_size - position - 1) * sizeof(std::pair<key_t,T>));
+	--_size;
+}
+
+
+#endif /* FRAMEWORK_CONTAINER_FIXEDORDEREDMULTIMAP_TPP_ */