more documentation

[germs.git] / src / geneorder.h

diff --git a/src/geneorder.h b/src/geneorder.h
index ebc427a9c4c0f49bb770de0af27a3c8c795c80de..4659e0efee62ca5194a3505b75d868bfe865c416 100644 (file)
--- a/src/geneorder.h
+++ b/src/geneorder.h
@@ -27,14 +27,21 @@
 #include "misc.h"
 
 /**
- * Stores a gene order permutation and ensures that all genes are present and not duplicated.
+ * Stores a gene order permutation and ensures that all genes are present 
+ * and not duplicated.
+ *
+ * It has limited support for acting as an STL container, but still maintaining
+ * the invariant of a permutation starting with 0 and ending with n, with all
+ * genes present.
+ *
  * \author Michael Andreen
 */
 class GeneOrder{
        public:
 
-               typedef std::vector<long> GeneList;
+               typedef std::vector<Gene> GeneList;
                typedef GeneList::size_type size_type;
+               typedef GeneList::const_iterator iterator;
 
                /**
                 * Creates a copy of the given gene order
@@ -42,9 +49,20 @@ class GeneOrder{
                GeneOrder(const GeneOrder& go);
 
                /**
-                * Creates a gene order from a given list.
+                * Creates a gene order from a given list, using STL-type iterators.
                 *
-                * \throws invalid_argument if the list is not a valid permutation.
+                * The given permutation needs to contain all genes 1 to n, if 0 is
+                * included it has to be the first item, if it is not present it will
+                * be added automatically. Similarily, if n is not the last item, then
+                * n+1 will be added to the end.
+                *
+                * \param begin iterator to the first element in the list, from begin()
+                * on stl collections and pointer to first item on plain arrays.
+                *
+                * \param end iterator to the element behind the last, from end() in
+                * stl collections or pointer to first element+size on plain arrays.
+                *
+                * \throws std::invalid_argument if the list is not a valid permutation.
                 */
                template<class T>
                GeneOrder(T begin, T end);
@@ -62,20 +80,44 @@ class GeneOrder{
                /**
                 * Returns the gene at the given index.
                 *
-                * \throws out_of_range if i is smaller than 0 or too big.
+                * \throws std::out_of_range if i is smaller than 0 or bigger than n.
                 */
                const Gene& operator[](size_type i) const;
 
                /**
                 * Returns the size of the permutation.
                 */
-               int size() const;
+               size_type size() const;
 
                /**
                 * Returns the vector containing the gene order permutation.
                 */
                const GeneList& list() const;
 
+               /**
+                * Returns the start iterator for the permutation.
+                * To be used with STL style functions.
+                *
+                * \see end
+                */
+               iterator begin() const;
+
+               /**
+                * Returns the end iterator for the permutation.
+                * To be used with STL style functions.
+                *
+                * \see begin
+                */
+               iterator end() const;
+
+               /**
+                * Reverserses the interval [i,j], changing the sign on all elements
+                * affected.
+                *
+                * \throws std::out_of_range if i is smaller than 0 or bigger than n.
+                */
+               void reverse(size_type i, size_type j);
+
 
        private:
                GeneList _geneorder;