diff --git a/doc/algorithm.qbk b/doc/algorithm.qbk index 9e015df..3d1230f 100644 --- a/doc/algorithm.qbk +++ b/doc/algorithm.qbk @@ -64,7 +64,8 @@ Thanks to all the people who have reviewed this library and made suggestions for [section:Misc Other Algorithms] [include clamp-hpp.qbk] -[include find.qbk] +[include find_not.qbk] +[include find_backward.qbk] [include gather.qbk] [include hex.qbk] [include is_palindrome.qbk] diff --git a/doc/find_backward.qbk b/doc/find_backward.qbk new file mode 100644 index 0000000..820a3fc --- /dev/null +++ b/doc/find_backward.qbk @@ -0,0 +1,99 @@ +[/ File find_backward.qbk] + +[section:find_backward find_backward ] + +[/license +Copyright (c) 2018 T. Zachary Laine + +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 'find_backward.hpp' contains variants of the stl algorithm +`find`. These variants are like `find`, except that the evaluate the elements +of the given sequence if reverse order. + +Consider how finding the last element that is equal to `x` in a range is +typically done: + + // Assume a valid range if elements delimited by [first, last). + while (last-- != first) { + if (*last == x) { + // Use last here... + } + } + +Raw loops are icky though. PErhaps we should do a bit of extra work to allow +the use of `std::find()`: + + auto rfirst = std::make_reverse_iterator(last); + auto rlast = std::make_reverse_iterator(first); + auto it = std::find(rfirst, rlast); + // Use it here... + +That seems nicer, but it has two major drawbacks. First, it requires an +unpleasant amount of typing. Second, it is considerably less efficient than +forward-iterator `find` , since `std::reverse_iterator` calls its +base-iterator's `operator--()` in most of its members before doing the work +that the member requires. + +[heading interface] + + template + BidiIter find_backward(BidiIter first, BidiIter last, T const & x); + +The function `find_backward` returns an iterator to the last element of +`[first, last)` that is equal to `x`. + + template + BidiIter find_not_backward(BidiIter first, BidiIter last, T const & x); + +The function `find_not_backward` returns an iterator to the last element of +`[first, last)` that is not equal to `x`. + + template + BidiIter find_if_backward(BidiIter first, BidiIter last, Pred p); + +The function `find_if_backward` returns an iterator to the last element of +`[first, last)` for which `pred` returns `true`. + + template + BidiIter find_if_not_backward(BidiIter first, BidiIter last, Pred p); + +The function `find_if_not_backward` returns an iterator to the last element of +`[first, last)` for which `pred` returns `false`. + +[heading Examples] + +Given the container `c1` containing `{ 2, 1, 2 }`, then + + find_backward ( c1.begin(), c1.end(), 2 ) --> --c1.end() + find_backward ( c1.begin(), c1.end(), 3 ) --> c1.end() + find_if_backward ( c1.begin(), c1.end(), [](int i) {return i == 2;} ) --> --c1.end() + find_if_backward ( c1.begin(), c1.end(), [](int i) {return i == 3;} ) --> c1.end() + find_not_backward ( c1.begin(), c1.end(), 2 ) --> std::prev(c1.end(), 2) + find_not_backward ( c1.begin(), c1.end(), 1 ) --> c1.end() + find_if_not_backward ( c1.begin(), c1.end(), [](int i) {return i == 2;} ) --> std::prev(c1.end(), 2) + find_if_not_backward ( c1.begin(), c1.end(), [](int i) {return i == 1;} ) --> c1.end() + +[heading Iterator Requirements] + +All variants work on bidirectional iterators. + +[heading Complexity] + +Linear. + +[heading Exception Safety] + +All of the variants take their parameters by value and do not depend upon any +global state. Therefore, all the routines in this file provide the strong +exception guarantee. + +[endsect] + +[/ File equal.qbk +Copyright 2018 T. Zachary Laine +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). +] diff --git a/doc/find.qbk b/doc/find_not.qbk similarity index 86% rename from doc/find.qbk rename to doc/find_not.qbk index 35cd189..146f8c9 100644 --- a/doc/find.qbk +++ b/doc/find_not.qbk @@ -1,6 +1,6 @@ -[/ File equal.qbk] +[/ File find_not.qbk] -[section:equal equal ] +[section:find_not find_not ] [/license Copyright (c) 2018 T. Zachary Laine @@ -39,10 +39,8 @@ our find condition. [heading interface] -`` -template -InputIter find_not(InputIter first, Sentinel last, T const & x); -`` + template + InputIter find_not(InputIter first, Sentinel last, T const & x); The function `find_not` returns the first value in the sequence `[first, last)` that is not equal to `x`. @@ -51,8 +49,8 @@ last)` that is not equal to `x`. Given the container `c1` containing `{ 0, 1, 2 }`, then - find_not ( c1.begin (), c1.end (), 1 ) --> c1.begin() - find_not ( c1.begin (), c1.end (), 0 ) --> std::next(c1.begin()) + find_not ( c1.begin(), c1.end(), 1 ) --> c1.begin() + find_not ( c1.begin(), c1.end(), 0 ) --> std::next(c1.begin()) [heading Iterator Requirements]