|
2 | 2 |
|
3 | 3 | The CompressedStacks.cpp module/library implements the compressed stack structure. This data structure behaves like a usual stack with the usual push and pop operations, but has the additional advantage that it uses less memory. Intuitively, when large blocks of information are pushed into the stack it *compresses* the bottom part (only stores partial information). This information is recomputed whenever it is needed afterwards. See the paper of [Barba *et al.*](https://arxiv.org/abs/1208.3663) for more details on this structure. |
4 | 4 |
|
| 5 | +Please consult the [wiki](https://github.com/Azzaare/CompressedStacks.cpp/wiki) of this project for further details such as : speed and memory consumption tests, more details about installation, examples, and more. |
5 | 6 |
|
6 | | -<!-- TODO: Write down a better description --> |
7 | | - |
8 | | -## Category of algorithms |
| 7 | +## Description of Stack Algorithms |
9 | 8 | <p> |
10 | | -This compressed stack structure works correctly as a normal stack for any problems that read input from a file (**Is this true?**)). However, the running time is optimal when the input would be read sequentially with a classical stack structure. For this 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. |
| 9 | +This compressed stack structure works correctly as a normal stack for any algorithm that read input from a file in a deterministic way. However, the running time is optimal when the input would be read sequentially with a classical stack structure. For this reason, the only function implemented in the StackAlgo template to solve it (to do a run) is the one presented below in a simplified version. |
11 | 10 | </p> |
12 | 11 |
|
13 | 12 | ```cpp |
14 | | -template <class T, class D> void Problem<T, D>::run() { |
| 13 | +template <class T, class D> void StackAlgo<T, D>::run() { |
15 | 14 | initStack(); |
16 | 15 | while (notEndOfFile()) { |
17 | 16 | D data = readInput(line); |
18 | | - while (notEmptystack() && popCondition(data)) { |
19 | | - elt = pop(); |
20 | | - popAction(elt); |
| 17 | + while (notEmptystack()) { |
| 18 | + if (popCondition(data)) { |
| 19 | + prePop(data); |
| 20 | + elt = pop(); |
| 21 | + postPop(elt,data); |
| 22 | + } else { |
| 23 | + noPop(data); |
| 24 | + } |
21 | 25 | } |
22 | 26 | if (pushCondition(data)) { |
23 | | - pushAction(data); |
| 27 | + prePush(data); |
24 | 28 | push(data); |
| 29 | + postPush(data); |
| 30 | + } else { |
| 31 | + noPush(data); |
25 | 32 | } |
26 | 33 | } |
| 34 | + reportStack(); |
27 | 35 | } |
28 | 36 | ``` |
| 37 | +## Use case |
| 38 | +Concrete examples such as a basic test run and the convex hull problem can be found in the [wiki](https://github.com/Azzaare/CompressedStacks.cpp/wiki). |
29 | 39 | |
30 | | -## Characterization of a problem |
31 | | -<p>In the following examples, implementations of the Problem interface are given.</p> |
32 | | - |
33 | | -### General example : ```Instance<T,D>``` |
| 40 | +### Abstract example : ```Instance<T,D,I>``` |
| 41 | +<p>An instance of a Stack Algorithm is described by a set of templates parameters T, D, and I and a set of methods used in the run function above.</p> |
34 | 42 | |
35 | 43 | ```cpp |
36 | | -#include <string> |
37 | | -#include <vector> |
38 | | -#include <memory> |
| 44 | +// T is the type of the context, D is the type of the input data and I is the type of your integer indexes. |
39 | 45 | |
40 | | -// T is the type of the context and D is the type of the input data. |
41 | | -class Instance: public Problem<T,D>{ |
| 46 | +class Instance: public StackAlgo<T,D,I>{ |
42 | 47 | public: |
43 | | - Instance(std::string filePath) : Problem<T, D>(filePath) {} |
| 48 | + Instance(std::string filePath) : StackAlgo<T, D, I>(filePath) {} |
44 | 49 | private: |
45 | | - // Functions to implement according to the problem and input |
46 | | - D readInput(std::vector<std::string> line){ |
47 | | - std::cout << "Implement readInput for your instance" << std::endl; |
48 | | - return 0; |
49 | | - } |
50 | | - std::shared_ptr<T> initStack(){ |
51 | | - std::cout << "Implement initStack for your instance" << std::endl; |
52 | | - std::shared_ptr<T> context(nullptr); |
53 | | - return context; |
54 | | - } |
55 | | - bool popCondition(D data){ |
56 | | - std::cout << "Implement mPopCondition for your instance" << std::endl; |
57 | | - return false; |
58 | | - } |
59 | | - void popAction(Data<T, D> elt){ |
60 | | - std::cout << "Implement mPopAction for your instance" << std::endl; |
61 | | - } |
62 | | - bool pushCondition(D data){ |
63 | | - std::cout << "Implement mPushCondition for your instance" << std::endl; |
64 | | - return true; |
65 | | - } |
66 | | - void pushAction(Data<T, D> elt){ |
67 | | - std::cout << "Implement mPushAction for your instance" << std::endl; |
68 | | - } |
69 | | -}; |
70 | | -``` |
| 50 | + // Methods to implement according to the problem and input structure |
| 51 | + // Some of those methods might be left empty |
| 52 | + D readInput(std::vector<std::string> line); |
| 53 | + std::shared_ptr<T> initStack(); |
71 | 54 | |
72 | | -### Example with ```T = int``` and ```D = int``` : ```Instance<int,int>``` |
73 | | -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. |
74 | | -```cpp |
75 | | -class Instance : public Problem<int, int> { |
76 | | -public: |
77 | | - Instance(std::string filePath) : Problem<int, int>(filePath) {} |
| 55 | + bool popCondition(D data); |
| 56 | + void prePop(D data); |
| 57 | + void postPop(D data, Data<T, D, I> elt); |
| 58 | + void noPop(D data); |
78 | 59 | |
79 | | -private: |
80 | | - // Functions to run the stack |
81 | | - int readInput(std::vector<std::string> line) { |
82 | | - int value = std::stoi(line[0]); |
83 | | - setContext(std::stoi(line[1])); |
84 | | - return value; |
85 | | - } |
86 | | - std::shared_ptr<int> initStack() { |
87 | | - std::shared_ptr<int> context(new int(0)); |
88 | | - return context; |
89 | | - } |
90 | | - bool popCondition(int data) { |
91 | | - if ((getContext() > 0)) { |
92 | | - return true; |
93 | | - } |
94 | | - return false; |
95 | | - } |
96 | | - void popAction(Data<int, int> elt) { |
97 | | - std::cout << elt.toString() << " <<<< Pop!" << std::endl; |
98 | | - setContext(getContext() - 1); |
99 | | - } |
100 | | - bool pushCondition(int data) { |
101 | | - if (data > 0) { |
102 | | - return true; |
103 | | - } |
104 | | - return false; |
105 | | - } |
106 | | - void pushAction(Data<int, int> elt) { |
107 | | - std::cout << "Push >>>> " << elt.toString() << std::endl; |
108 | | - } |
| 60 | + bool pushCondition(D data); |
| 61 | + void prePush(Data<T, D, I> elt); |
| 62 | + void postPush(Data<T, D, I> elt); |
| 63 | + void noPush(D data); |
| 64 | + |
| 65 | + void reportStack(); |
109 | 66 | }; |
110 | 67 | ``` |
111 | | - |
112 | | -## How to run your problem |
113 | | -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. |
| 68 | +### How to run your problem |
| 69 | +Suppose the class Instance implements the interface ```StackAlgo<T, D, I>```. 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 the console of your compressed stack after the run. |
114 | 70 |
|
115 | 71 | ```cpp |
116 | 72 | Instance stack(filePath); |
117 | 73 | stack.run(); |
118 | 74 | stack.println(); |
119 | 75 | ``` |
| 76 | + |
| 77 | +## Contributing |
| 78 | +This project is far from being complete and would benefit greatly from future contributions. Commented code, following the existing file structure is strongly preferred. Please contact one of the author (or create an issue) in case of need. Here is a short sample of possible contributions : |
| 79 | +* Use CI (continuous integration). Definitively the most wanted feature |
| 80 | +* Extends the compressed stack structure to a dequeue structure (push and pop from top and bottom) |
| 81 | +* Add other problems to the examples folder (following, if possible a similar structure) |
| 82 | +* Extends the compressed stack structure to a compressed tree search structure |
| 83 | +* Dynamic size compressed stack. |
| 84 | + |
| 85 | + |
| 86 | +## Credits |
| 87 | +Although this project is a joint work, based on the theoretical work in [Barba *et al.*](https://arxiv.org/abs/1208.3663), credits belong to specific authors for part of the implementation. The work covering the implementation of the Stack Algorithm framework, the Comrpessed Stack structure and extras functionalities (```include``` and ```extras``` repositories) has been done by [Jean-Francois Baffier](https://github.com/Azzaarehttps://github.com/Azzaare). All the examples and their generating algorithms, along with all the test have been implemented by [Yago Diez](https://github.com/nicill). |
| 88 | + |
| 89 | +## License |
| 90 | +This project is an open source software under the MIT license. Please check the ```LICENSE``` file for further information. |
0 commit comments