RangeHelpers

RangeHelpers

Ever needed a range with startpoint 10, endpoint 121.7 and a step of 25? Well that is mathematically not possible, so you need to compromise. There are lots of options, you could relax the startpoint, endpoint or step. In the past doing this was annoying and prone to off-by-one-errors:

julia> Base.range(10, step=25, length=round(Int, (121.7-10)/25)); # is it correct??

RangeHelpers.jl aims to solve range construction headaches once and for all:

julia> using RangeHelpers: range

julia> using RangeHelpers

julia> range(start=10, stop=121.7, step=around(25)) # compromise on step
10.0:27.925:121.7

julia> range(start=10, stop=121.7, step=below(25))  # compromise step at most 25
10.0:22.34:121.7

julia> range(start=10, stop=above(121.7), step=25)  # exact step, but allow bigger endpoint
10:25:135

julia> anchorrange(42, start=around(10), step=25, stop=around(121.7)) # make sure 42 is on the grid
17:25:117

See the documentation for even more ways to make ranges.

anchorrange(anchor; step, start, stop, pre, post)

Return a range, that approximately has anchor on its grid.

julia> using RangeHelpers

julia> anchorrange(15.5, start=above(11), step=2, stop=below(15))
11.5:2.0:13.5

asrange(itr; check=true, atol, rtol)::AbstractRange

Convert itr into a range, optionally validating the result.

julia> using RangeHelpers

julia> asrange([1,2,3.0])
1.0:1.0:3.0

julia> asrange([1,2,3])
1:1:3

julia> asrange(1:3)
1:3

julia> asrange([1,2,4.0])
ERROR: ArgumentError: Cannot construct range from `itr`
itr = [1.0, 2.0, 4.0]
[...]

julia> asrange([1,2,4.0], atol=10)
1.0:1.5:4.0

bincenters(r::AbstractRange)::AbstractRange

If r is interpreted as a collection of bin boundaries, bincenters returns the bin centers.

julia> using RangeHelpers: bincenters

julia> bincenters(1:10.0)
1.5:1.0:9.5

See also binwalls.

binwalls(r::AbstractRange; first=true, last=true)::AbstractRange

If r is interpreted as a collection of bin centers, binwalls returns the bin boundaries.

julia> using RangeHelpers: binwalls

julia> binwalls(0.0:2.0:10.0)
-1.0:2.0:11.0

julia> binwalls(0.0:2.0:10.0, first=false)
1.0:2.0:11.0

julia> binwalls(0.0:2.0:10.0, last=false)
-1.0:2.0:9.0

See also bincenters.

i = indexof(r::AbstractRange, x)

Return i such that r[i] == x or throw an error if that is not possible.

prolong(r::AbstractRange;start=nothing, stop=nothing, pre=nothing, post=nothing)

Prolong an existing range r according to the arguments:

julia> using RangeHelpers

julia> r = 1.0:0.5:3.0
1.0:0.5:3.0

julia> prolong(r, stop=around(4))
1.0:0.5:4.0

julia> prolong(r, pre=1)
0.5:0.5:3.0

julia> prolong(r, pre=1, post=2)
0.5:0.5:4.0

julia> prolong(r, start=below(0.4), stop=around(4.1))
0.0:0.5:4.0

range(start, stop; length, step)
range(start; stop, length, step)
range(;start, stop, length, step)

Construct a range from the arguments. Three arguments must be given.

julia> using RangeHelpers

julia> using RangeHelpers: range

julia> range(start=1, stop=3, length=3)
1.0:1.0:3.0

julia> range(start=1, stop=3.1, step=around(1))
1.0:1.05:3.1

julia> range(start=1, stop=around(3.1), step=1)
1:1:3

julia> range(start=1, stop=above(3.1), step=1)
1:1:4

julia> range(start=1, stop=above(3.0), step=1)
1:1:3

julia> range(start=around(0.9), stop=3.0, step=1)
1.0:1.0:3.0

julia> range(start=strictbelow(1.0), stop=3.0, step=1)
0.0:1.0:3.0

See also the docs of Base.range.

samegrid(r1::AbstractRange, r2::AbstractRange; atol=0, rtol=0, kw...)::Bool

Check if r1 and r2 are defined on the same grid. That is if there exist equal prolongations of r1 and r1.

julia> using RangeHelpers: samegrid

julia> samegrid(1:10, 11:12)
true

julia> samegrid(1:10, 11:1.1:12)
false

julia> samegrid(1:10, 1:0)
true

julia> samegrid(1:10, 0.1:0)
false

julia> samegrid(1:10, 5:-1:3)
true

julia> samegrid(1:10, 4.1:1:5, rtol=0.2)
true

searchsortedat(coll, x)

Return the index of a sorted collection coll whose corresponding element is closest to x. If coll is not sorted, searchsortedat might silently return a wrong result.

julia> using RangeHelpers

julia> searchsortedat(100:100:1000, around(200))
2

julia> searchsortedat(100:100:1000, around(249))
2

julia> searchsortedat(100:100:1000, around(251))
3

julia> searchsortedat(100:100:1000, below(251))
2

julia> searchsortedat(100:100:1000, above(249))
3

julia> searchsortedat(100:100:1000, 300)
3

julia> searchsortedat(100:100:1000, 301)
ERROR: ArgumentError: coll does not contain x:
coll = 100:100:1000
x = 301
Try `searchsortedat(coll, around(x))`

subdivide(r::AbstractRange, factor::Integer, mode=:walls)

Create a range with smaller step from r. Possible values for mode are (:walls, :centers).

julia> using RangeHelpers

julia> r = 1:3.0
1.0:1.0:3.0

julia> subdivide(r, 2)
1.0:0.5:3.0

julia> subdivide(r, 4)
1.0:0.25:3.0

julia> subdivide(r, 2, mode=:walls)
1.0:0.5:3.0

julia> subdivide(r, 2, mode=:centers)
0.75:0.5:3.25

julia> subdivide(r, 10, mode=:centers)
0.55:0.1:3.45

symrange(;center=0, step, length, start, stop)

Construct a range, that is symmetric around center.

julia> using RangeHelpers

julia> symrange(length=2, step=1)
-0.5:1.0:0.5

julia> symrange(length=3, step=1)
-1.0:1.0:1.0

julia> symrange(length=3, step=1, center=4)
3.0:1.0:5.0

julia> symrange(start=around(-4.1), step=2)
-4.0:2.0:4.0

julia> symrange(start=around(-4.1), step=2, center=1)
-4.0:2.0:6.0

julia> symrange(stop=around(4.1), step=2, center=1)
-2.0:2.0:4.0