libcxx/include/__algorithm/lower_bound.h

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