forked from boostorg/algorithm
81 lines
2.4 KiB
Plaintext
81 lines
2.4 KiB
Plaintext
|
[/ File equal.qbk]
|
||
|
|
|
||
|
|
[section:equal equal ]
|
||
|
|
|
||
|
|
[/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).
|
||
|
|
]
|