Improved README.md

Author: Azzaare

README.md

@@ -1,33 +1,118 @@
 # CompressedStacks.cpp
+
+The CompressedStacks.cpp module/library implements a time-space trade-off structure for stack's algorithms.
+
+<!-- TODO: Write down a better description -->
+
+## Category of algorithms
+<p>
+This compressed stack structure works correctly as a normal stack for any problems that read input from a file. However, the running time is optimal when the input would be read sequentially with a classical stack structure. For his reason, the only function implemented in the Problem template to solve it (to do a run) is the one presented below in a simplified version.
+</p>
+
 ```cpp
-// Class for test instance
-// T is the type of the context and D is the type of the input data. Please change it on 1st, 3rd, 4th, 18th, and 25th lines.
+template <class T, class D> void Problem<T, D>::run() {
+  initStackIntern();
+  while (notEndOfFile()) {
+    D data = readInput(line);
+    while (notEmptystack() && popCondition(data)) {
+      elt = pop();
+      popAction(elt);
+    }
+    if (pushCondition(data)) {
+      pushAction(data);
+      push(data);
+    }
+  }
+}
+```
+
+## Characterization of a problem
+<p>In the followwing examples, implementations of the Problem interface are given.</p>
+
+### General example : Instance<T,D>
+
+```cpp
+#include <string>
+#include <vector>
+#include <memory>
+
+// T is the type of the context and D is the type of the input data.
 class Instance: public Problem<T,D>{
 public:
-  Instance(std::string filePath, int size):Problem<T,D>(filePath, size){}
-  Instance(std::string filePath, int size, int space, int buffer):Problem<T,D>(filePath, size, space, buffer){}
+  Instance(std::string filePath) : Problem<T, D>(filePath) {}
 private:
   // Functions to implement according to the problem and input
-  int mReadInput(){
-    std::cout << "Implement mReadInput for your instance" << std::endl;
+  D readInput(std::vector<std::string> line){
+    std::cout << "Implement readInput for your instance" << std::endl;
     return 0;
   }
-  void mInitStack(){
-    std::cout << "Implement mInitStack for your instance" << std::endl;
+  std::shared_ptr<T> initStack(){
+    std::cout << "Implement initStack for your instance" << std::endl;
+    std::shared_ptr<T> context(nullptr);
+    return context;
   }
-  bool mPopCondition(int elt){
+  bool popCondition(D data){
     std::cout << "Implement mPopCondition for your instance" << std::endl;
     return false;
   }
-  void mPopAction(Data<D> elt){
+  void popAction(Data<T, D> elt){
     std::cout << "Implement mPopAction for your instance" << std::endl;
   }
-  bool mPushCondition(int elt){
+  bool pushCondition(D data){
     std::cout << "Implement mPushCondition for your instance" << std::endl;
     return true;
   }
-  void mPushAction(Data<D> elt){
+  void pushAction(Data<T, D> elt){
     std::cout << "Implement mPushAction for your instance" << std::endl;
   }
 };
 ```
+
+### Example with T = int and D = int : Instance<int,int>
+The context is initialized at 0. The data (in cvs format) is read as a pair of string such that the first string is the data  and the second is used to update the context. While the context is more than 0, the stack is poped and the context decreased by 1. If the data is more than 0 then it is pushed.
+```cpp
+class Instance : public Problem<int, int> {
+public:
+  Instance(std::string filePath) : Problem<int, int>(filePath) {}
+
+private:
+  // Functions to run the stack
+  int readInput(std::vector<std::string> line) {
+    int value = std::stoi(line[0]);
+    setContext(std::stoi(line[1]));
+    return value;
+  }
+  std::shared_ptr<int> initStack() {
+    std::shared_ptr<int> context(new int(0));
+    return context;
+  }
+  bool popCondition(int data) {
+    if ((getContext() > 0)) {
+      return true;
+    }
+    return false;
+  }
+  void popAction(Data<int, int> elt) {
+    std::cout << elt.toString() << " <<<< Pop!" << std::endl;
+    setContext(getContext() - 1);
+  }
+  bool pushCondition(int data) {
+    if (data > 0) {
+      return true;
+    }
+    return false;
+  }
+  void pushAction(Data<int, int> elt) {
+    std::cout << "Push >>>> " << elt.toString() << std::endl;
+  }
+};
+```
+
+## How to run your problem
+Suppose the class Instance implement the interface Problem<T,D> (as in some examples above). You can run an instance of your problem described in the input located at <i>filepath</i>. The last command just print an output in th console of your compressed stack after the run.
+
+```cpp
+Instance stack(filePath);
+stack.run();
+stack.println();
+```

include/compressedStack.hpp

@@ -149,7 +149,7 @@ CompressedStack<T, D>::CompressedStack(int size, int space, int buffer,
 }
 
 /*==============================================================================
-   New Internals
+   Internals
     1) emptyExplicit (int lvl, int component) : test if the explicit part of
    component is empty. If component = 0, test on all component.
     2) back(int lvl, int component) : if lvl = 0 give the back of mCompressed,
@@ -165,8 +165,6 @@ component
     9) getSign(int component, int lvl) : get the last sign in component at lvl.
 If lvl = 0, look in the fully compressed part
 ==============================================================================*/
-// TODO: Move new internals once finished
-
 template <class T, class D>
 bool CompressedStack<T, D>::empty(int lvl, int component) {
   bool b = true;
@@ -450,8 +448,6 @@ template <class T, class D> std::string CompressedStack<T, D>::toString() {
     3) pushCompressed
     4) resetBlock
 ==============================================================================*/
-// TODO: reorganize the push functions
-
 // Function push that push the data in explicit and index in partial/compressed
 template <class T, class D>
 void CompressedStack<T, D>::push(const Data<T, D> &elt) {

src/main.cpp

@@ -145,15 +145,5 @@ int main(int argc, char *argv[]) {
     exit(-1);
     break;
   }
-
-  // Intances generation, please comment when not in use
-  /*  createTestInput ct=createTestInput();
-    ct.createTestInputFiles(0,"/home/yago/code/CompressedStacks.cpp/instances/pushOnlyInput.csv",1000,3,
-    5, 100, 0.2 );
-    ct.createTestInputFiles(1,"/home/yago/code/CompressedStacks.cpp/instances/CTInput.csv",1000,3);
-    ct.createTestInputFiles(2,"/home/yago/code/CompressedStacks.cpp/instances/CHInput.csv",100,3,-1,
-    11);
-  */
-
   return 0;
 }