Merge pull request #8 from nkaaf/change_default_mutability_behavior

change default mutable state; small rework on getting values/pointers

Author: nkaaf

Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = "Arduino List Library"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 1.0.1
+PROJECT_NUMBER         = 2.0.0
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

examples/List/DifferenceMutableAndImmutable/DifferenceMutableAndImmutable.ino

@@ -1,9 +1,9 @@
 #include <List.hpp>
 
 // Create a mutable list
-List<int> mutableList;
+List<int> mutableList(true);
 // Create an immutable list
-List<int> immutableList(false);
+List<int> immutableList;
 
 void setup() {
   Serial.begin(9600);

examples/List/ManageElements/ManageElements.ino

@@ -1,6 +1,6 @@
 #include <List.hpp>
 
-// Create a mutable list
+// Create an immutable list
 List<int> list;
 
 void setup() {
@@ -14,20 +14,21 @@ void setup() {
   Serial.println();
 
   // Get the first element
-  Serial.print("The value of the first element with the get() method and '*' is: ");
-  int firstElement = *list.get(0); // Here, have to be the '*' to get the int Value, because otherwise a pointer (memory address) will be get.
-  Serial.println(firstElement);
+  Serial.print("The value of the first element with the getValue() method is: ");
+  Serial.println(list.getValue(0)); // The most comfortable way to get the first elements value is to call the getValue() method. You cannot get the address of the element with the getValue() method!
 
   // Get the first element (alternative)
   Serial.print("The value of the first element with the [] operator is: ");
-  firstElement = *list[0]; // The '[]' Operator is a synonym for the get() method.
+  int firstElement = list[0]; // The '[]' Operator is a synonym for the getValue() method.
   Serial.println(firstElement);
 
-  // Get only the value of the first element
-  Serial.print("The value of the first element with the getValue() method is: ");
-  Serial.println(list.getValue(0)); // The more comfortable way to get only the first elements value is to call the getValue() method. You cannot get the address of the element with the getValue() method!
+  // Get the first element (alternative)
+  Serial.print("The value of the first element with the getPointer() method and '*' is: ");
+  int *firstElementPtr = list.getPointer(0); // Here, have to be the '*' to get the int Value, because otherwise a pointer (memory address) will be returned.
+  Serial.println(*firstElementPtr);
+  free(firstElementPtr); // free the pointer because it is an immutable list
 
-  Serial.println("As you can see, there are three possible ways to get the value. Choose your favorite one :)");
+  Serial.println("As you can see, there are three possible ways to get the value. The last way is not for beginners because you have to handle pointers.");
   Serial.println();
 
   // Get the size of the list

examples/List/UtilsAndHelper/UtilsAndHelper.ino

@@ -1,6 +1,6 @@
 #include <List.hpp>
 
-// Create a mutable list
+// Create an immutable list
 List<int> list;
 
 void setup() {
@@ -45,6 +45,8 @@ void setup() {
     }
   }
   Serial.println("]");
+  // free memory space generated by toArray(), because it is not used anymore
+  free(array);
 
   Serial.println();
 
@@ -78,10 +80,10 @@ void setup() {
   Serial.println("Add all elements of the second list to the first list.");
   list.addAll(secondList);
 
-  // Print every element from the new array
-  Serial.print("The list contains the following values which are get by converting the list to an array: [");
+  // Print every element from the combined list
+  Serial.print("The list contains the following values: [");
   for (int i = 0; i < list.getSize(); ++i) {
-    Serial.print(*list[i]);
+    Serial.print(list[i]);
     if (i != list.getSize() - 1) { // only add the ',' if the element is not the last; otherwise the output would be: [2,2,]; but now it is [2,2]
       Serial.print(",");
     }

keywords.txt

@@ -16,8 +16,8 @@ SingleLinkedList	KEYWORD1
 
 addAtIndex	KEYWORD2
 remove	KEYWORD2
-get	KEYWORD2
 getValue	KEYWORD2
+getPointer	KEYWORD2
 addLast	KEYWORD2
 addFirst	KEYWORD2
 add	KEYWORD2

library.properties

@@ -1,5 +1,5 @@
 name=List
-version=1.0.1
+version=2.0.0
 author=Niklas Kaaf <[email protected]>
 maintainer=Niklas Kaaf <[email protected]>
 sentence=The Ultimate Collection of Lists

src/AbstractList.hpp

@@ -26,6 +26,8 @@
 #ifndef LIST_ABSTRACT_LIST_HPP
 #define LIST_ABSTRACT_LIST_HPP
 
+#include <stdlib.h>
+
 /*!
  * @brief   Abstract class from which all lists can be derived.
  *
@@ -68,6 +70,17 @@ template <typename T> class AbstractList {
     return index < 0 || index >= this->getSize();
   }
 
+  /*!
+   * @brief Get a pointer to the entry at the given index. If the given index
+   *        does not exists, null will be returned.
+   * @note  If the list is immutable, the returned pointer has to be free'd with
+   *        free() in order to prevent memory leaks.
+   *
+   * @param index   Index of the element to get.
+   * @return    Pointer to the element.
+   */
+  virtual T *get(int index) = 0;
+
 public:
   /*!
    * @brief Add the value to the list at the given index. The original entry at
@@ -89,27 +102,32 @@ template <typename T> class AbstractList {
   virtual void remove(int index) = 0;
 
   /*!
-   * @brief Get a pointer to the entry at the given index. If the given index
-   * does not exists in the list or the list is immutable, null will be
-   * returned.
-   * @note  If you only want to get the value, use getValue().
+   * @brief Get the value at the index.
+   * @note  Be safe, that the index exists otherwise the program will crash
+   *        here!
    *
-   * @param index   Index of the element to get.
-   * @return    Pointer to the element.
+   * @param index   Index of element to get.
+   * @return    Value.
    */
-  virtual T *get(int index) = 0;
+  T getValue(int index) {
+    T *ptr = getPointer(index);
+    T val = *ptr;
+    if (!this->isMutable()) {
+      free(ptr);
+    }
+    return val;
+  }
 
   /*!
-   * @brief Get the plain value at the given index.
-   * @note  Be safe, that the given index exists and the list is mutable,
-   * otherwise the program will crash here!
-   * @see   get()
-   * @todo  Rewrite this to let the program not crash!
+   * @brief Get a pointer to the entry at the given index. If the given index
+   *        does not exists, null will be returned.
+   * @note  If the list is immutable, the returned pointer has to be free'd with
+   *        free() in order to prevent memory leaks.
    *
    * @param index   Index of element to get.
-   * @return    Value.
+   * @return    Pointer to the element.
    */
-  T getValue(int index) { return *get(index); }
+  T *getPointer(int index) { return get(index); }
 
   /*!
    * @brief Add a new entry at the end of the list.
@@ -140,26 +158,25 @@ template <typename T> class AbstractList {
    *
    * @param list    Other list to copy from.
    */
-  void addAll(AbstractList<T> &list) {
-    for (int i = 0; i < list.getSize(); ++i) {
-      this->addLast(*list.get(i));
-    }
-  }
+  void addAll(AbstractList<T> &list) { this->addAll(this->getSize(), list); }
 
   /*!
    * @brief Add all entries from the given list to this list at the given index.
    *        The original entry at this index, and followings, will be placed
    *        directly after the entries of the given list.
-   * @see   addAtIndex()
-   * @note  Use this only if you know what you are doing. Otherwise use
-   *        addAll().
    *
    * @param index   Index, at which the list should be added.
    * @param list    List to add.
    */
   void addAll(int index, AbstractList<T> &list) {
     for (int i = 0; i < list.getSize(); i++) {
-      this->addAtIndex(index++, *list.get(i));
+      T val = list.getValue(i);
+      T *finalValue = (T *)malloc(sizeof(T));
+      memcpy(finalValue, &val, sizeof(T));
+      this->addAtIndex(index++, *finalValue);
+      if (!this->isMutable()) {
+        free(finalValue);
+      }
     }
   }
 
@@ -178,7 +195,7 @@ template <typename T> class AbstractList {
     T *arr = (T *)malloc(this->getSize() * sizeof(T));
 
     for (int i = 0; i < this->getSize(); ++i) {
-      arr[i] = *this->get(i);
+      arr[i] = this->getValue(i);
     }
 
     return arr;
@@ -223,22 +240,21 @@ template <typename T> class AbstractList {
     }
 
     for (int i = 0; i < this->getSize(); i++) {
-      if (*list.get(i) != *this->get(i)) {
+      if (list.getValue(i) != this->getValue(i)) {
         return false;
       }
     }
     return true;
   }
 
   /*!
-   * @brief Get a pointer to the entry at the given index.
-   * @see   get()
+   * @brief Get the value of the element at the index.
    * @see   getValue()
    *
    * @param index   Index of the element to get.
-   * @return    Pointer to the element.
+   * @return    Value of the element.
    */
-  T *operator[](int index) { return get(index); }
+  T operator[](int index) { return getValue(index); }
 
   /*!
    * @brief Compare two lists whether their attributes and entries are equal.

src/List.hpp

@@ -55,10 +55,10 @@ template <typename T> class List : public SingleLinkedList<T> {
   /*!
    * @brief Constructor of a List Object.
    *
-   * @param mutableList true if the list should be mutable (default); false
-   *                    otherwise.
+   * @param mutableList true if the list should be mutable; false otherwise
+   *                    (default).
    */
-  explicit List<T>(bool mutableList = true)
+  explicit List<T>(bool mutableList = false)
       : SingleLinkedList<T>(mutableList) {}
 };
 

src/SingleLinkedList.hpp

@@ -26,7 +26,6 @@
 #ifndef LIST_SINGLE_LINKED_LIST_HPP
 #define LIST_SINGLE_LINKED_LIST_HPP
 
-#include <stdlib.h>
 #include <string.h>
 
 #include "AbstractList.hpp"
@@ -89,14 +88,36 @@ template <typename T> class SingleLinkedList : public AbstractList<T> {
   Entry *head = nullptr; /// The first entry of the list.
   Entry *tail = nullptr; /// The last entry of the list.
 
+protected:
+  T *get(int index) override {
+    if (this->isIndexOutOfBounds(index)) {
+      return nullptr;
+    }
+
+    Entry *current = this->head;
+    int i = 0;
+    while (i != index) {
+      current = current->getNext();
+      i++;
+    }
+
+    if (this->isMutable()) {
+      return (T *)current->getValue();
+    } else {
+      T *finalValue = (T *)malloc(sizeof(T));
+      memcpy(finalValue, current->getValue(), sizeof(T));
+      return finalValue;
+    }
+  }
+
 public:
   /*!
    * @brief Constructor of a SingleLinkedList Object.
    *
-   * @param mutableList true if the list should be mutable (default); false
-   *                    otherwise.
+   * @param mutableList true if the list should be mutable; false otherwise
+   *                    (default).
    */
-  explicit SingleLinkedList<T>(bool mutableList = true)
+  explicit SingleLinkedList<T>(bool mutableList = false)
       : AbstractList<T>(mutableList) {}
 
   /*!
@@ -207,21 +228,6 @@ template <typename T> class SingleLinkedList : public AbstractList<T> {
       this->tail = nullptr;
     }
   }
-
-  T *get(int index) override {
-    if (!this->isMutable() || this->isIndexOutOfBounds(index)) {
-      return nullptr;
-    }
-
-    Entry *current = this->head;
-    int i = 0;
-    while (i != index) {
-      current = current->getNext();
-      i++;
-    }
-
-    return (T *)current->getValue();
-  }
 };
 
 #endif /* LIST_SINGLE_LINKED_LIST_HPP */