Merge pull request #3 from SciML/searchsorted

Add improved searchsortedfirstcorrelated and bracketstrictlymontonic

.github/workflows/Downstream.yml

@@ -0,0 +1,54 @@
+name: IntegrationTest
+on:
+  push:
+    branches: [master]
+    tags: [v*]
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.package.repo }}/${{ matrix.package.group }}/${{ matrix.julia-version }}
+    runs-on: ${{ matrix.os }}
+    env:
+      GROUP: ${{ matrix.package.group }}
+    strategy:
+      fail-fast: false
+      matrix:
+        julia-version: [1]
+        os: [ubuntu-latest]
+        package:
+          - {user: SciML, repo: DataInterpolations.jl, group: Core}
+          - {user: SciML, repo: ModelingToolkit.jl, group: InterfaceI}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: ${{ matrix.julia-version }}
+          arch: x64
+      - uses: julia-actions/julia-buildpkg@latest
+      - name: Clone Downstream
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ matrix.package.user }}/${{ matrix.package.repo }}
+          path: downstream
+      - name: Load this and run the downstream tests
+        shell: julia --color=yes --project=downstream {0}
+        run: |
+          using Pkg
+          try
+            # force it to use this PR's version of the package
+            Pkg.develop(PackageSpec(path="."))  # resolver may fail with main deps
+            Pkg.update()
+            Pkg.test(coverage=true)  # resolver may fail with test time deps
+          catch err
+            err isa Pkg.Resolve.ResolverError || rethrow()
+            # If we can't resolve that means this is incompatible by SemVer and this is fine
+            # It means we marked this as a breaking change, so we don't need to worry about
+            # Mistakenly introducing a breaking change, as we have intentionally made one
+            @info "Not compatible with this release. No problem." exception=err
+            exit(0)  # Exit immediately, as a success
+          end
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v3
+        with:
+          file: lcov.info

README.md

@@ -7,4 +7,42 @@ over more generic implementations.
 
 ## Functions
 
-* `findfirstequal(x::Int64,A::DenseVector{Int64})`: finds the first value in `A` equal to `x`
+### `findfirstequal`
+
+```julia
+findfirstequal(x::Int64,A::DenseVector{Int64})
+```
+
+Finds the first value in `A` equal to `x`
+
+### `bracketstrictlymontonic`
+
+```julia
+bracketstrictlymontonic(v, x, guess; lt=<comparison>, by=<transform>, rev=false)
+```
+
+Starting from an initial `guess` index, find indices `(lo, hi)` such that `v[lo] ≤ x ≤
+v[hi]` according to the specified order, assuming that `x` is actually within the range of
+values found in `v`.  If `x` is outside that range, either `lo` will be `firstindex(v)` or
+`hi` will be `lastindex(v)`.
+
+Note that the results will not typically satisfy `lo ≤ guess ≤ hi`.  If `x` is precisely
+equal to a value that is not unique in the input `v`, there is no guarantee that `(lo, hi)`
+will encompass *all* indices corresponding to that value.
+
+This algorithm is essentially an expanding binary search, which can be used as a precursor
+to `searchsorted` and related functions, which can take `lo` and `hi` as arguments.  The
+purpose of using this function first would be to accelerate convergence in those functions
+by using correlated `guess`es for repeated calls.  The best `guess` for the next call of
+this function would be the index returned by the previous call to `searchsorted`.
+
+See `sort!` for an explanation of the keyword arguments `by`, `lt` and `rev`.
+
+### `searchsortedfirstcorrelated(v::AbstractVector, x, guess)`
+
+```julia
+searchsortedfirstcorrelated(v::AbstractVector, x, guess)
+```
+
+An accelerated `findfirst` on sorted vectors using a bracketed search. Requires a `guess`
+to start the search from.

src/FindFirstFunctions.jl

@@ -68,5 +68,70 @@ function findfirstequal(vpivot::Int64, ivars::DenseVector{Int64})
   ret < 0 ? nothing : ret + 1
 end
 
+"""
+    bracketstrictlymontonic(v, x, guess; lt=<comparison>, by=<transform>, rev=false)
+
+Starting from an initial `guess` index, find indices `(lo, hi)` such that `v[lo] ≤ x ≤
+v[hi]` according to the specified order, assuming that `x` is actually within the range of
+values found in `v`.  If `x` is outside that range, either `lo` will be `firstindex(v)` or
+`hi` will be `lastindex(v)`.
+
+Note that the results will not typically satisfy `lo ≤ guess ≤ hi`.  If `x` is precisely
+equal to a value that is not unique in the input `v`, there is no guarantee that `(lo, hi)`
+will encompass *all* indices corresponding to that value.
+
+This algorithm is essentially an expanding binary search, which can be used as a precursor
+to `searchsorted` and related functions, which can take `lo` and `hi` as arguments.  The
+purpose of using this function first would be to accelerate convergence in those functions
+by using correlated `guess`es for repeated calls.  The best `guess` for the next call of
+this function would be the index returned by the previous call to `searchsorted`.
+
+See [`sort!`](@ref) for an explanation of the keyword arguments `by`, `lt` and `rev`.
+"""
+function bracketstrictlymontonic(v::AbstractVector,
+        x,
+        guess::T,
+        o::Base.Order.Ordering)::NTuple{2, keytype(v)} where {T <: Integer}
+    bottom = firstindex(v)
+    top = lastindex(v)
+    if guess < bottom || guess > top
+        return bottom, top
+        # # NOTE: for cache efficiency in repeated calls, we avoid accessing the first and last elements of `v`
+        # # on each call to this function.  This should only result in significant slow downs for calls with
+        # # out-of-bounds values of `x` *and* bad `guess`es.
+        # elseif lt(o, x, v[bottom])
+        #     return bottom, bottom
+        # elseif lt(o, v[top], x)
+        #     return top, top
+    else
+        u = T(1)
+        lo, hi = guess, min(guess + u, top)
+        @inbounds if Base.Order.lt(o, x, v[lo])
+            while lo > bottom && Base.Order.lt(o, x, v[lo])
+                lo, hi = max(bottom, lo - u), lo
+                u += u
+            end
+        else
+            while hi < top && !Base.Order.lt(o, x, v[hi])
+                lo, hi = hi, min(top, hi + u)
+                u += u
+            end
+        end
+    end
+    return lo, hi
+end
+
+function searchsortedfirstcorrelated(v::AbstractVector, x, guess)
+    lo, hi = bracketstrictlymontonic(v, x, guess, Base.Order.Forward)
+    searchsortedfirst(v, x, lo, hi, Base.Order.Forward)
+end
+
+function searchsortedlastcorrelated(v::AbstractVector, x, guess)
+    lo, hi = bracketstrictlymontonic(v, x, guess, Base.Order.Forward)
+    searchsortedlast(v, x, lo, hi, Base.Order.Forward)
+end
+
+searchsortedfirstcorrelated(r::AbstractRange, x, _) = searchsortedfirst(r, x)
+searchsortedlastcorrelated(r::AbstractRange, x, _) = searchsortedlast(r, x)
 
 end