add documentation

src/data_container.h

@@ -13,18 +13,21 @@
 #define DATA_CONTAINER_H
 
 
+// Basic data type holding the return value of the DataContainer get
+// operations.
 class QueryResultContainer {
     public:
         bool active;
         int index;
         double * data;
-        
+
         QueryResultContainer() : active(false), index(-1), data(NULL) {};
 
         QueryResultContainer(bool a, int i, double * d_ptr) : active(a), index(i), data(d_ptr) {};
 };
 
 
+// Basic data type that can be used as a DataContainer subscript.
 class DataIndexType {
     protected:
         int index;
@@ -66,12 +69,17 @@ class DataContainer {
         int  insert(const double data[]);
         bool remove(int index);
 
+        // Unsafe (can point to invalide data) but fast data access operators
         double * unsafe_peek(int index) const {return & data[index * n_dim];};
         double * operator[](DataIndexType & idx) const {return unsafe_peek(idx.get_index());};
 
+        // Index increment operators (used by ittereators). Next and prev skip
+        // inactive elements and stop at the "edges" of the data.
         int next_active(int index) const;
         int prev_active(int index) const;
 
+        // Safe (will not point to invalid data) but slower data access
+        // operators
         QueryResultContainer get(int index) const;
         QueryResultContainer get_next(int index) const;
         QueryResultContainer get_prev(int index) const;
@@ -81,6 +89,9 @@ class DataContainer {
 };
 
 
+// Itterator for traversing the valid fields in the DataContainer. This can be
+// used in the (unsafe) subscript data access operator. Recommended for
+// high-performance data access.
 class DataIndexItter : public DataIndexType {
     protected:
         const DataContainer * dc;
@@ -88,12 +99,17 @@ class DataIndexItter : public DataIndexType {
 
     public:
         DataIndexItter(DataContainer & dc);
-        
+
         bool is_valid();
         DataIndexItter & operator++();
 };
 
 
+// Itterator for traversing the valid fields in the DataContainer. Gives access
+// to the DataContainer's get operator. It can also be used in the (unsafe)
+// subscript data access operator. Note: while get() is not optimized for
+// performance, the DataContainerItter can still be used as the (fast)
+// subscript wherever safety is not an issue.
 class DataContainerItter : public DataIndexItter {
     public:
         DataContainerItter(DataContainer & dc) : DataIndexItter(dc) {};

test/data_container/interactive.cpp

@@ -13,7 +13,7 @@ void print_data_container(DataContainer & dc){
     int length = dc.data_capacity();
     int n_dim  = dc.payload_dim();
 
-    std::cout << "Capacity: " << dc.data_capacity() 
+    std::cout << "Capacity: " << dc.data_capacity()
         << " Lenght: " << dc.data_length()
         << " Index Range: [" << dc.first_index() << ", " << dc.last_index() << "]"
         << std::endl;
@@ -32,23 +32,30 @@ void print_data_container(DataContainer & dc){
 
 
 void itterate_data_container(DataContainer & dc){
-    std::cout << "Itterator runs over:" << std::endl;
+    std::cout << "DataContainerItter runs over:" << std::endl;
     int n_dim  = dc.payload_dim();
 
     DataContainerItter dc_itt(dc);
     for(QueryResultContainer qr = dc_itt.get(); dc_itt.is_valid(); qr = dc_itt.next()){
         std::cout << qr.index << ": ";
         print_vector(qr.data, n_dim);
+        if(qr.index != dc.last_index()) std::cout << ", ";
+    }
+    std::cout << std::endl;
 
-        if(qr.index != dc.last_index()) 
-            std::cout << ", ";
+    std::cout << "DataIndexItter runs over:" << std::endl;
+    for(DataIndexItter dci(dc); dci.is_valid(); ++dci){
+        double * data = dc[dci];
+        std::cout << dci.get_index() << ": ";
+        print_vector(data, n_dim);
+        if(dci.get_index() != dc.last_index()) std::cout<< ", ";
     }
     std::cout << std::endl;
 }
 
 
 int main(int argc, char * argv[]){
-    
+
     DataContainer dc(2,3);
 
     double sample_v_1[] = {1, 2, 3};