boost_algorithm/doc/find_not.qbk

[/ File find_not.qbk]

[section:find_not find_not ]

[/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_not.hpp' contains a variants of a the stl algorithm
`find`. The algorithm finds the first value in the given sequence that is not
equal to the given value.

Consider this use of `find()`:

    auto std::vector<int> vec = { 1, 1, 2 };
    auto it = std::find(vec.begin(), vec.end(), 1);

This gives us the first occurance of `1` in `vec`.  What if we want to find
the first occurrance of any number besides `1` in `vec`?  We have to write an
unfortunate amount of code:

    auto std::vector<int> vec = { 1, 1, 2 };
    auto it = std::find_if(
        vec.begin(), vec.end(),
        [](int i) { return i != 1; });

With `find_not()` the code gets much more terse:

    auto std::vector<int> vec = { 1, 1, 2 };
    auto it = find_not(vec.begin(), vec.end(), 1);

The existing `find` variants are: `find()`, `find_if()`, and `find_if_not()`.
It seems natural to also have `find_not()`, for the very reason that we have
`find_if_not()` -- to avoid having to write a lambda to wrap the negation of
our find condition.

[heading interface]

    template<typename InputIter, typename Sentinel, typename T>        
    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`.

[heading Examples]

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())

[heading Iterator Requirements]

`equal` works on all iterators except output iterators.

The template parameter `Sentinel` is allowed to be different from `InputIter`,
or they may be the same.  For an `InputIter` `it` and a `Sentinel` `end`, `it
== end` and `it != end` must be well-formed expressions.

[heading Complexity]

Linear.

[heading Exception Safety]

`find_not` takes its parameters by value and do not depend upon any global
state. Therefore, it provides 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).
]