benchmark swap

results/heap_sort_swap.plot

+4 2.691000
+8 11.625000
+16 38.618000
+32 110.312000
+64 287.477000
+128 709.014000
+256 1682.503000
+512 3888.728000
+1024 8823.067000
+

src/binary_heap.hpp

@@ -25,6 +25,11 @@ protected:
   virtual bool heap_cmp(T & value1, T & value2) = 0;
   
 public:
+  /**
+     Class constructor.
+     Creates a heap of at most 'max' elements and initializes swap counters to zero.
+     @input max is the maximal number of elements the heap can contain
+  */
   BinaryHeap(size_t max){
     this->max = max;
     this->size = 0;
@@ -45,6 +50,11 @@ public:
     return this->size;
   }
 
+  /**
+     This method is used during benchmarks, when one wants to know
+     how many time the swap function has been called.
+     It is to be called at the beginning of each benchmark.
+  */
   void resetCounters(){
     counter_swap_up = 0;
     counter_swap_down = 0;
@@ -53,20 +63,36 @@ public:
   size_t getSwapsCounters(){
     return counter_swap_down + counter_swap_up;
   }
-
-  inline int parent(int position){
+  
+  /**
+     Returns the position of a node's parent
+     @requires 0 < position < this->size
+     @param position is the position of a node of the heap, except the root
+     @return the position of a node's parent
+   */
+  inline int parent(size_t position){
     return (position-1)/2;
   }
 
-  inline int left_child(int position){
+  /**
+     Returns the position of a node's left child
+     @param position is the position of a node of the heap, except the root
+     @return the position of a node's parent
+  */
+  inline int left_child(size_t position){
     return position*2+1;
   }
 
-  inline int right_child(int position){
+  inline int right_child(size_t position){
     return position*2+2;
   }
   
-  void heapify_up(int position){
+  /**
+     This function takes the position of a value as an input
+     and makes it go UP in the heap until the comparison constraint is satisfied.
+     @param position is the position of the value we want to check
+   */
+  void heapify_up(size_t position){
     while(position > 0 && heap_cmp(data[position], data[parent(position)])){
       std::swap(data[parent(position)], data[position]);
       counter_swap_up++;
@@ -74,7 +100,12 @@ public:
     }
   }
 
-  void heapify_down(int position){
+  /**
+     This function takes the position of a value as an input
+     and makes it go DOWN in the heap until the comparison constraint is satisfied.
+     @param position is the position of the value we want to check
+   */
+  void heapify_down(size_t position){
     int min_child;
     min_child = heap_cmp(data[left_child(position)], data[right_child(position)])? left_child(position): right_child(position);
     while(min_child < (size-1) && heap_cmp(data[min_child], data[position])){
@@ -84,7 +115,13 @@ public:
       counter_swap_down++;
     }
   }
-  
+
+  /* This function insert a value in the heap
+     @param value is the value we want to add.
+     @requires this->size != this-> max (the heap is not full)
+     @ensures the size is incremented
+     @exception throws a FullBinaryHeapException if the heap is full.
+   */
   void insert(T value) {
     if(size == max)
       throw new FullBinaryHeapException();
@@ -92,16 +129,25 @@ public:
     heapify_up(size-1);
   }
 
+  /*
+    Extract the value at the top of the heap
+    @ensures the size is decremented
+    @returns the value at the top of the heap
+  */
   T extract(){
     std::swap(data[0], data[size-1]);
     heapify_down(0);
     return data[--size];
   }
 
+  /**
+     Outputs the content of the heap a a regular tabular
+   */
   friend std::ostream& operator<<(std::ostream& os, const BinaryHeap<int>& heap);
   
 };
 
+
 std::ostream& operator<<(std::ostream& os, const BinaryHeap<int>& heap)
 {
   for( int i = 0; i < heap.size; i++)