1//===----------------------------------------------------------------------===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#ifndef _LIBCPP___ALGORITHM_LOWER_BOUND_H
10#define _LIBCPP___ALGORITHM_LOWER_BOUND_H
11
12#include <__algorithm/comp.h>
13#include <__algorithm/half_positive.h>
14#include <__algorithm/iterator_operations.h>
15#include <__config>
16#include <__functional/identity.h>
17#include <__iterator/advance.h>
18#include <__iterator/distance.h>
19#include <__iterator/iterator_traits.h>
20#include <__type_traits/invoke.h>
21#include <__type_traits/is_callable.h>
22
23#if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
24# pragma GCC system_header
25#endif
26
27_LIBCPP_BEGIN_NAMESPACE_STD
28
29template <class _AlgPolicy, class _Iter, class _Type, class _Proj, class _Comp>
30[[__nodiscard__]] _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX20 _Iter __lower_bound_bisecting(
31 _Iter __first,
32 const _Type& __value,
33 typename iterator_traits<_Iter>::difference_type __len,
34 _Comp& __comp,
35 _Proj& __proj) {
36 while (__len != 0) {
37 auto __l2 = std::__half_positive(__len);
38 _Iter __m = __first;
39 _IterOps<_AlgPolicy>::advance(__m, __l2);
40 if (std::__invoke(__comp, std::__invoke(__proj, *__m), __value)) {
41 __first = ++__m;
42 __len -= __l2 + 1;
43 } else {
44 __len = __l2;
45 }
46 }
47 return __first;
48}
49
50// One-sided binary search, aka meta binary search, has been in the public domain for decades, and has the general
51// advantage of being \Omega(1) rather than the classic algorithm's \Omega(log(n)), with the downside of executing at
52// most 2*log(n) comparisons vs the classic algorithm's exact log(n). There are two scenarios in which it really shines:
53// the first one is when operating over non-random-access iterators, because the classic algorithm requires knowing the
54// container's size upfront, which adds \Omega(n) iterator increments to the complexity. The second one is when you're
55// traversing the container in order, trying to fast-forward to the next value: in that case, the classic algorithm
56// would yield \Omega(n*log(n)) comparisons and, for non-random-access iterators, \Omega(n^2) iterator increments,
57// whereas the one-sided version will yield O(n) operations on both counts, with a \Omega(log(n)) bound on the number of
58// comparisons.
59template <class _AlgPolicy, class _ForwardIterator, class _Sent, class _Type, class _Proj, class _Comp>
60[[__nodiscard__]] _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX20 _ForwardIterator
61__lower_bound_onesided(_ForwardIterator __first, _Sent __last, const _Type& __value, _Comp& __comp, _Proj& __proj) {
62 // step = 0, ensuring we can always short-circuit when distance is 1 later on
63 if (__first == __last || !std::__invoke(__comp, std::__invoke(__proj, *__first), __value))
64 return __first;
65
66 using _Distance = typename iterator_traits<_ForwardIterator>::difference_type;
67 for (_Distance __step = 1; __first != __last; __step <<= 1) {
68 auto __it = __first;
69 auto __dist = __step - _IterOps<_AlgPolicy>::__advance_to(__it, __step, __last);
70 // once we reach the last range where needle can be we must start
71 // looking inwards, bisecting that range
72 if (__it == __last || !std::__invoke(__comp, std::__invoke(__proj, *__it), __value)) {
73 // we've already checked the previous value and it was less, we can save
74 // one comparison by skipping bisection
75 if (__dist == 1)
76 return __it;
77 return std::__lower_bound_bisecting<_AlgPolicy>(__first, __value, __dist, __comp, __proj);
78 }
79 // range not found, move forward!
80 __first = __it;
81 }
82 return __first;
83}
84
85template <class _AlgPolicy, class _ForwardIterator, class _Sent, class _Type, class _Proj, class _Comp>
86[[__nodiscard__]] inline _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX20 _ForwardIterator
87__lower_bound(_ForwardIterator __first, _Sent __last, const _Type& __value, _Comp& __comp, _Proj& __proj) {
88 const auto __dist = _IterOps<_AlgPolicy>::distance(__first, __last);
89 return std::__lower_bound_bisecting<_AlgPolicy>(__first, __value, __dist, __comp, __proj);
90}
91
92template <class _ForwardIterator, class _Tp, class _Compare>
93[[__nodiscard__]] inline _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX20 _ForwardIterator
94lower_bound(_ForwardIterator __first, _ForwardIterator __last, const _Tp& __value, _Compare __comp) {
95 static_assert(__is_callable<_Compare&, decltype(*__first), const _Tp&>::value, "The comparator has to be callable");
96 auto __proj = std::__identity();
97 return std::__lower_bound<_ClassicAlgPolicy>(__first, __last, __value, __comp, __proj);
98}
99
100template <class _ForwardIterator, class _Tp>
101[[__nodiscard__]] inline _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX20 _ForwardIterator
102lower_bound(_ForwardIterator __first, _ForwardIterator __last, const _Tp& __value) {
103 return std::lower_bound(__first, __last, __value, __less<>());
104}
105
106_LIBCPP_END_NAMESPACE_STD
107
108#endif // _LIBCPP___ALGORITHM_LOWER_BOUND_H
109