Bug fixes and is_partititioned_XXX for the 1.65.0 release

doc/Jamfile.v2

@@ -16,17 +16,17 @@ using quickbook ;
 using doxygen ;
 using boostbook ;
 
-doxygen autodoc 
-    : 
-        [ glob ../../../boost/algorithm/*.hpp 
+doxygen autodoc
+    :
+        [ glob ../../../boost/algorithm/*.hpp
                ../../../boost/algorithm/searching/*.hpp
                ../../../boost/algorithm/cxx11/*.hpp
                ../../../boost/algorithm/cxx14/*.hpp
         ]
-    : 
+    :
        <doxygen:param>"PREDEFINED=\"BOOST_ALGORITHM_DOXYGEN=1\""
        <doxygen:param>WARNINGS=YES # Default NO, but useful to see warnings, especially in a logfile.
-    ; 
+    ;
 
 
 xml algorithm : algorithm.qbk ;
@@ -35,7 +35,7 @@ boostbook standalone
   :
     algorithm
   :
-    <dependency>autodoc 
+    <dependency>autodoc
     <xsl:param>boost.root=../../../..
     <xsl:param>"boost.doxygen.reftitle=Boost.Algorithms C++ Reference"
     <xsl:param>chapter.autolabel=0
@@ -47,10 +47,10 @@ boostbook standalone
 
 ###############################################################################
 alias boostdoc
-    : algorithm ../string/doc/string_algo.xml
+    : ../string/doc/string_algo.xml
     :
-    : <dependency>autodoc <dependency>../string/doc//autodoc
+    : <dependency>../string/doc//autodoc
     : ;
 explicit boostdoc ;
-alias boostrelease ;
+alias boostrelease : standalone ;
 explicit boostrelease ;

doc/algorithm.qbk

@@ -67,6 +67,7 @@ Thanks to all the people who have reviewed this library and made suggestions for
 [include gather.qbk]
 [include hex.qbk]
 [include is_palindrome.qbk]
+[include is_partitioned_until.qbk]
 [endsect]
 
 

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/is_partitioned.qbk

@@ -57,7 +57,7 @@ Both of the variants of `is_partitioned` take their parameters by value or const
 
 * The iterator-based version of the routine `is_partitioned` is also available as part of the C++11 standard.
 
-* `is_partitioned` returns true for empty ranges, no matter what predicate is passed to test against. 
+* `is_partitioned` returns true for empty and single-element ranges, no matter what predicate is passed to test against. 
 
 [endsect]
 

doc/is_partitioned_until.qbk

@@ -0,0 +1,67 @@
+[/ File is_partitioned_until.qbk]
+
+[section:is_partitioned_until is_partitioned_until ]
+
+[/license
+Copyright (c) 2017 Alexander Zaitsev
+
+Distributed under the Boost Software License, Version 1.0.
+(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+]
+
+The header file 'is_partitioned_until.hpp' contains two variants of a single algorithm, `is_partitioned_until`. The algorithm tests to see if a sequence is partitioned according to a predicate; in other words, all the items in the sequence that satisfy the predicate are at the beginning of the sequence.
+
+The routine `is_partitioned_until` takes a sequence and a predicate. It returns the last iterator 'it' in the sequence [begin, end) for which the is_partitioned(begin, it) is true.
+
+`is_partitioned_until` come in two forms; the first one takes two iterators to define the range. The second form takes a single range parameter, and uses Boost.Range to traverse it.
+
+
+[heading interface]
+
+The function `is_partitioned_until` returns the last iterator 'it' in the sequence [begin, end) for which the is_partitioned(begin, it) is true. There are two versions; one takes two iterators, and the other takes a range.
+
+``
+template<typename InputIterator, typename Predicate>
+	InputIterator is_partitioned_until ( InputIterator first, InputIterator last, Predicate p );
+template<typename Range, typename Predicate> 
+	typename boost::range_iterator<const Range>::type is_partitioned_until ( const Range &r, Predicate p );
+``
+
+[heading Examples]
+
+Given the container `c` containing `{ 0, 1, 2, 3, 14, 15 }`, then
+``
+bool isOdd ( int i ) { return i % 2 == 1; }
+bool lessThan10 ( int i ) { return i < 10; }
+
+is_partitioned_until ( c, isOdd ) --> iterator to '1'
+is_partitioned_until ( c, lessThan10 ) --> end
+is_partitioned_until ( c.begin (), c.end (), lessThan10 ) --> end
+is_partitioned_until ( c.begin (), c.begin () + 3, lessThan10 ) --> end
+is_partitioned_until ( c.end (), c.end (), isOdd ) --> end  // empty range
+``
+
+[heading Iterator Requirements]
+
+`is_partitioned_until` works on all iterators except output iterators.
+
+[heading Complexity]
+
+Both of the variants of `is_partitioned_until` run in ['O(N)] (linear) time; that is, they compare against each element in the list once. If the sequence is found to be not partitioned at any point, the routine will terminate immediately, without examining the rest of the elements.
+
+[heading Exception Safety]
+
+Both of the variants of `is_partitioned_until` take their parameters by value or const reference, and do not depend upon any global state. Therefore, all the routines in this file provide the strong exception guarantee.
+
+[heading Notes]
+
+* `is_partitioned_until` returns iterator to the end for empty and single-element ranges, no matter what predicate is passed to test against. 
+
+[endsect]
+
+[/ File is_partitioned_until.qbk
+Copyright 2017 Alexander Zaitsev
+Distributed under the Boost Software License, Version 1.0.
+(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt).
+]
+

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.