--- trunk/OOPSE-2.0/src/utils/next_combination.hpp	2004/10/28 19:33:46	1675
+++ branches/new_design/OOPSE-2.0/src/utils/next_combination.hpp	2004/10/28 22:34:02	1683
@@ -24,7 +24,7 @@
  */
 
 /**
- * @file GenerateCombination.hpp
+ * @file next_combination.hpp
  * @author    tlin
  * @date  10/27/2004
  * @version 1.0
@@ -35,14 +35,36 @@
 
 #include <vector>
 #include <iterator>
-
+#include <iostream>
 namespace oopse {
 
 /**
- * STL next_permuationtation like combination sequence generator 
- * 
- * <p> Preconditions: </p>
- * 
+ * @brief STL next_permuationtation like combination sequence generator.
+ * Given the first and last iterator of a sequence, next_combination iteratively generates all 
+ * possible combinations.
+ * @return if more combination is availiable, otherwise return false
+ * @param iterContainer iterator container
+ * @param first the first iterator
+ * @param last the last iterator
+ * @note first and last must be random access iterators and iterContainer must be the container of  
+ * random access iterators . And all of the iteratos in iterContainer must be within the range [first, last)
+ *
+ * @code
+ * std::vector<int> iv;
+ * iv.push_back(1);
+ * iv.push_back(8);
+ * std::vector<std::vector<int>::iterator> ic;
+ * while(next_combination(ic, iv.begin(), iv.end())) {
+ *     for (i =  ic.begin(); i < ic.end(); ++i) {
+ *         std::cout << **i << "\t";
+ *     }
+ *     std::cout << std::endl;
+ * }
+ * //output
+ * //1
+ * //8
+ * //1  8
+ * @endcode
  */
 template<class RandomAccessIterator, template<typename ELEM, typename = std::allocator<ELEM> > class IteratorContainer>
 bool next_combination(IteratorContainer<RandomAccessIterator>& iterContainer, RandomAccessIterator first, RandomAccessIterator last) {
@@ -58,15 +80,15 @@ bool next_combination(IteratorContainer<RandomAccessIt
         iterContainer.insert(iterContainer.end(), first);
         return true;
     } else if (*(--i) != endIter){
-        //if the last iterator in iterContainer does not reaches the end, just increment it 
+        //if the last iterator in iterContainer does not reaches the end, just increase its iterator by 1 
         ++(*i);
         return true;
     } else {// the last iterator in iterContainer does not reaches the end
 
         //starts at the end of the sequence and works its way towards the front, looking for two 
         //consecutive members of the sequence where the difference between them is greater 
-        //than one. For example , if the sequence contains 1, 5, 8, 9 (total number is 10, begin
-        //index is 0, therefore 9 is the end index, and the current size is 4). At the end of while
+        //than one. For example , if the sequence contains 1, 5, 8, 9 (total number is 10, first is 0
+        //and the last is 10 (due to STL's half open range)). At the end of while
         //loop, j will point to 5, and i will point to 8, next combination should be 1, 6, 7, 8.
         //If j is less than zero, it means it already reaches the last combination of current size.
         //For instance, sequence may contain 6, 7, 8, 9 at this time, we need to increase the size
@@ -108,6 +130,62 @@ bool next_combination(IteratorContainer<RandomAccessIt
     }
 } //end next_combination
 
+/**
+ * @brief iteratively replace the sequence with wild cards
+ * @return true if more combination sequence is avaliable, otherwise return true
+ * @param cont iterator container, if expect the whole series of combinations,  pass an empty iterator 
+ * container. The user should not modify this iterator container
+ * @param sequence the whole sequence used to generate combination
+ * @param result a possible combination sequence which is set on return
+ * @param wildCard the wild card string. Its value is "X" by default
+ * @note since next_combination never returns an empty sequence, replaceWildCard will not generate 
+ * one special combination, which is n identical wild cards (n is equal to the size of the passing sequence)
+ * 
+ * @code
+ * std::vector<std::string> sv;
+ * std::vector<std::vector<std::string>::iterator> sic;
+ * std::vector<std::string> resultString;
+ * sv.push_back("H");
+ * sv.push_back("C");
+ * sv.push_back("N");
+
+ * while (replaceWildCard(sic, sv, resultString)) {   
+ *     for(std::vector<std::string>::iterator i = resultString.begin(); i != resultString.end(); ++i) {
+ *         std::cout << *i << "\t";
+ *     }
+ *     std::cout << std::endl;
+ * }
+ * //output
+ * //H X X
+ * //X C X
+ * //X X N
+ * //H C X
+ * //H X N
+ * //X C N
+ * //H C N
+ * @endcode
+ */
+bool replaceWildCard(std::vector<std::vector<std::string>::iterator>& cont,
+                                             std::vector<std::string>& sequence, std::vector<std::string>& result,
+                                             const std::string& wildCard = "X") {
+    if (cont.size() > sequence.size()) {
+        std::cerr << "the size of iterator container is greater than the size of sequence";
+    }
+
+    bool hasMoreCombination = next_combination(cont, sequence.begin(), sequence.end());
+    if (hasMoreCombination) {
+        result.clear();
+        result.insert(result.begin(), sequence.size(), wildCard);
+        std::vector<std::vector<std::string>::iterator>::iterator i;
+        for ( i = cont.begin(); i != cont.end(); i++){
+            result[*i - sequence.begin()] = **i;
+        }
+    }
+
+     return hasMoreCombination;
+    
+}//end replaceWildCard
+
 } //end namespace oopse
 #endif //UTILS_NEXT_COMBINATION_HPP