...one of the most highly
regarded and expertly designed C++ library projects in the
world. — Herb Sutter and Andrei
template <class F, class T, class Tol> std::pair<T, T> bisect( // Unlimited iterations. F f, T min, T max, Tol tol); template <class F, class T, class Tol> std::pair<T, T> bisect( // Limited iterations. F f, T min, T max, Tol tol, boost::uintmax_t& max_iter); template <class F, class T, class Tol, class Policy> std::pair<T, T> bisect( // Specified policy. F f, T min, T max, Tol tol, boost::uintmax_t& max_iter, const Policy&);
These functions locate the root using bisection.
bisect function arguments
A unary functor (or C++ lambda) which is the function f(x) whose root is to be found.
The left bracket of the interval known to contain the root.
The right bracket of the interval known to contain the root.
It is a precondition that min < max and f(min)*f(max) <= 0, the function raises an evaluation_error if these preconditions are violated. The action taken on error is controlled by the Policy template argument: the default behavior is to throw a boost::math::evaluation_error. If the Policy is changed to not throw then it returns std::pair<T>(min, min).
A binary functor (or C++ lambda) that specifies the termination condition: the function will return the current brackets enclosing the root when tol(min, max) becomes true. See also predefined termination functors.
The maximum number of invocations of f(x) to make while searching for the root. On exit, this is updated to the actual number of invocations performed.
The final Policy argument is optional and can be used to control the behaviour of the function: how it handles errors, what level of precision to use etc. Refer to the policy documentation for more details.
Returns: a pair of values r that bracket the root so that:
f(r.first) * f(r.second) <= 0
tol(r.first, r.second) == true
max_iter >= m
where m is the initial value of max_iter passed to the function.
In other words, it's up to the caller to verify whether termination occurred as a result of exceeding max_iter function invocations (easily done by checking the updated value of max_iter when the function returns), rather than because the termination condition tol was satisfied.