Updated the docs for the searchers to reflect the new interface, and added rationale for the change.

doc/boyer_moore.qbk

@@ -37,7 +37,7 @@ public:
     ~boyer_moore ();
     
     template <typename corpusIter>
-    corpusIter operator () ( corpusIter corpus_first, corpusIter corpus_last );
+    pair<corpusIter, corpusIter> operator () ( corpusIter corpus_first, corpusIter corpus_last );
     };
 ``
 
@@ -45,14 +45,28 @@ and here is the corresponding procedural interface:
 
 ``
 template <typename patIter, typename corpusIter>
-corpusIter boyer_moore_search ( 
+pair<corpusIter, corpusIter> boyer_moore_search ( 
         corpusIter corpus_first, corpusIter corpus_last, 
         patIter pat_first, patIter pat_last );
 ``
 
 Each of the functions is passed two pairs of iterators. The first two define the corpus and the second two define the pattern. Note that the two pairs need not be of the same type, but they do need to "point" at the same type. In other words, `patIter::value_type` and `curpusIter::value_type` need to be the same type.
 
-The return value of the function is an iterator pointing to the start of the pattern in the corpus. If the pattern is not found, it returns the end of the corpus (`corpus_last`).
+The return value of the function is a pair of iterators pointing to the position of the pattern in the corpus. If the pattern is empty, it returns at empty range at the start of the corpus (`corpus_first`, `corpus_first`). If the pattern is not found, it returns at empty range at the end of the corpus (`corpus_last`, `corpus_last`).
+
+[heading Compatibility Note]
+
+Earlier versions of this searcher returned only a single iterator.  As explained in [@https://cplusplusmusings.wordpress.com/2016/02/01/sometimes-you-get-things-wrong/], this was a suboptimal interface choice, and has been changed, starting in the 1.62.0 release.  Old code that is expecting a single iterator return value can be updated by replacing the return value of the searcher's `operator ()` with the `.first` field of the pair.
+
+Instead of:
+``
+iterator foo = searcher(a, b);
+``
+
+you now write:
+``
+iterator foo = searcher(a, b).first;
+``
 
 [heading Performance]
 

doc/boyer_moore_horspool.qbk

@@ -35,7 +35,7 @@ public:
     ~boyer_moore_horspool ();
     
     template <typename corpusIter>
-    corpusIter operator () ( corpusIter corpus_first, corpusIter corpus_last );
+    pair<corpusIter, corpusIter> operator () ( corpusIter corpus_first, corpusIter corpus_last );
     };
 ``
 
@@ -43,14 +43,28 @@ and here is the corresponding procedural interface:
 
 ``
 template <typename patIter, typename corpusIter>
-corpusIter boyer_moore_horspool_search ( 
+pair<corpusIter, corpusIter> boyer_moore_horspool_search ( 
         corpusIter corpus_first, corpusIter corpus_last, 
         patIter pat_first, patIter pat_last );
 ``
 
 Each of the functions is passed two pairs of iterators. The first two define the corpus and the second two define the pattern. Note that the two pairs need not be of the same type, but they do need to "point" at the same type. In other words, `patIter::value_type` and `curpusIter::value_type` need to be the same type.
 
-The return value of the function is an iterator pointing to the start of the pattern in the corpus. If the pattern is not found, it returns the end of the corpus (`corpus_last`).
+The return value of the function is a pair of iterators pointing to the position of the pattern in the corpus. If the pattern is empty, it returns at empty range at the start of the corpus (`corpus_first`, `corpus_first`). If the pattern is not found, it returns at empty range at the end of the corpus (`corpus_last`, `corpus_last`).
+
+[heading Compatibility Note]
+
+Earlier versions of this searcher returned only a single iterator.  As explained in [@https://cplusplusmusings.wordpress.com/2016/02/01/sometimes-you-get-things-wrong/], this was a suboptimal interface choice, and has been changed, starting in the 1.62.0 release.  Old code that is expecting a single iterator return value can be updated by replacing the return value of the searcher's `operator ()` with the `.first` field of the pair.
+
+Instead of:
+``
+iterator foo = searcher(a, b);
+``
+
+you now write:
+``
+iterator foo = searcher(a, b).first;
+``
 
 [heading Performance]
 

doc/knuth_morris_pratt.qbk

@@ -39,7 +39,7 @@ public:
     ~knuth_morris_pratt ();
     
     template <typename corpusIter>
-    corpusIter operator () ( corpusIter corpus_first, corpusIter corpus_last );
+    pair<corpusIter, corpusIter> operator () ( corpusIter corpus_first, corpusIter corpus_last );
     };
 ``
 
@@ -47,15 +47,28 @@ and here is the corresponding procedural interface:
 
 ``
 template <typename patIter, typename corpusIter>
-corpusIter knuth_morris_pratt_search ( 
+pair<corpusIter, corpusIter> knuth_morris_pratt_search ( 
         corpusIter corpus_first, corpusIter corpus_last, 
         patIter pat_first, patIter pat_last );
 ``
 
 Each of the functions is passed two pairs of iterators. The first two define the corpus and the second two define the pattern. Note that the two pairs need not be of the same type, but they do need to "point" at the same type. In other words, `patIter::value_type` and `curpusIter::value_type` need to be the same type.
 
-The return value of the function is an iterator pointing to the start of the pattern in the corpus. If the pattern is not found, it returns the end of the corpus (`corpus_last`).
+The return value of the function is a pair of iterators pointing to the position of the pattern in the corpus. If the pattern is empty, it returns at empty range at the start of the corpus (`corpus_first`, `corpus_first`). If the pattern is not found, it returns at empty range at the end of the corpus (`corpus_last`, `corpus_last`).
 
+[heading Compatibility Note]
+
+Earlier versions of this searcher returned only a single iterator.  As explained in [@https://cplusplusmusings.wordpress.com/2016/02/01/sometimes-you-get-things-wrong/], this was a suboptimal interface choice, and has been changed, starting in the 1.62.0 release.  Old code that is expecting a single iterator return value can be updated by replacing the return value of the searcher's `operator ()` with the `.first` field of the pair.
+
+Instead of:
+``
+iterator foo = searcher(a, b);
+``
+
+you now write:
+``
+iterator foo = searcher(a, b).first;
+``
 [heading Performance]
 
 The execution time of the Knuth-Morris-Pratt algorithm is linear in the size of the string being searched. Generally the algorithm gets faster as the pattern being searched for becomes longer. Its efficiency derives from the fact that with each unsuccessful attempt to find a match between the search string and the text it is searching, it uses the information gained from that attempt to rule out as many positions of the text as possible where the string cannot match.