diff --git a/doc/boyer_moore.qbk b/doc/boyer_moore.qbk index 13c9666..1651133 100644 --- a/doc/boyer_moore.qbk +++ b/doc/boyer_moore.qbk @@ -37,7 +37,7 @@ public: ~boyer_moore (); template - corpusIter operator () ( corpusIter corpus_first, corpusIter corpus_last ); + pair operator () ( corpusIter corpus_first, corpusIter corpus_last ); }; `` @@ -45,14 +45,28 @@ and here is the corresponding procedural interface: `` template -corpusIter boyer_moore_search ( +pair 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] diff --git a/doc/boyer_moore_horspool.qbk b/doc/boyer_moore_horspool.qbk index 3a10c32..5b8491a 100644 --- a/doc/boyer_moore_horspool.qbk +++ b/doc/boyer_moore_horspool.qbk @@ -35,7 +35,7 @@ public: ~boyer_moore_horspool (); template - corpusIter operator () ( corpusIter corpus_first, corpusIter corpus_last ); + pair operator () ( corpusIter corpus_first, corpusIter corpus_last ); }; `` @@ -43,14 +43,28 @@ and here is the corresponding procedural interface: `` template -corpusIter boyer_moore_horspool_search ( +pair 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] diff --git a/doc/knuth_morris_pratt.qbk b/doc/knuth_morris_pratt.qbk index 7b184cf..b2620f1 100644 --- a/doc/knuth_morris_pratt.qbk +++ b/doc/knuth_morris_pratt.qbk @@ -39,7 +39,7 @@ public: ~knuth_morris_pratt (); template - corpusIter operator () ( corpusIter corpus_first, corpusIter corpus_last ); + pair operator () ( corpusIter corpus_first, corpusIter corpus_last ); }; `` @@ -47,15 +47,28 @@ and here is the corresponding procedural interface: `` template -corpusIter knuth_morris_pratt_search ( +pair 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.