- Removed bugs in FloatmuIterator

- Added method `eligible_step`

Author: goualard-f

Project.toml

@@ -1,7 +1,7 @@
 name = "MicroFloatingPoints"
 uuid = "6e0295d3-a2ae-4d9e-ab31-7b55fc0f4333"
 authors = ["Frédéric Goualard <[email protected]>"]
-version = "1.0.0"
+version = "1.1.0"
 
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/src/developer.md

@@ -35,6 +35,12 @@ MicroFloatingPoints.roundfrac(f,szf)
 MicroFloatingPoints.float64_to_uint32mu(x::Float64,szE,szf)
 ```
 
+## Iterators
+
+```@docs
+check_eligibility_step(start::Floatmu{szE,szf}, stop::Floatmu{szE,szf}, step::Floatmu{szE,szf}) where {szE,szf}
+```
+
 ## The `MicroFloatingPoints.MFPRandom` module
 
 ```@meta

docs/src/manual.md

@@ -215,6 +215,14 @@ FloatmuIterator{szE,szf}
     FloatmuIterator{2,2}(-1.25, -0.25, 0.25)
     ```
 
+It is possible to know in advance the number of floats in the resulting range with the [`length`](https://docs.julialang.org/en/v1/base/collections/#Base.length) function.	
+
+As stated in the documentation for `FloatmuIterator` above, one cannot use a floating-point step smaller than the largest gap in the domain we iterate through. The function `eligible_step` gives the smallest value allowed when given two bounds.
+
+```@docs
+eligible_step
+```
+	
 ### Rounding
 
 We have seen in section [Creating a `Floatmu` float](@ref) that each `Floatmu` retains the information whether the value it was created from required rounding or not.

src/Floatmu.jl

@@ -1137,6 +1137,56 @@ Return the value of the global inexact flag.
 """
 inexact() = return inexact_flag
 
+
+"""
+    eligible_step(start::Floatmu{szE,szf}, stop::Floatmu{szE,szf}) where {szE,szf}
+    eligible_step(::Type{Floatmu{szE,szf}}, start::Float64, stop::Float64) where {szE,szf}
+
+Return the smallest `Floatmu{szE,szf}` eligible step allowed to iterate through the domain
+`[start,stop]`.
+
+# Examples
+
+```jldoctest
+julia> eligible_step(Floatmu{2,2}(-0.5),Floatmu{2,2}(2.5))
+0.5
+```
+"""
+function eligible_step end
+
+function eligible_step(start::Floatmu{szE,szf}, stop::Floatmu{szE,szf}) where {szE,szf}
+    maxi = max(abs(start),abs(stop))
+    return maxi - prevfloat(maxi) # The difference of two consecutive floats is always representable
+end
+
+function eligible_step(::Type{Floatmu{szE,szf}}, start::Float64, stop::Float64) where {szE,szf}
+    return eligible_step(Floatmu{szE,szf}(start),Floatmu{szE,szf}(stop))
+end
+
+
+"""
+    check_eligibility_step(start::Floatmu{szE,szf}, stop::Floatmu{szE,szf},
+                           step::Floatmu{szE,szf}) where {szE,szf}
+
+Check whether the step `step` can be reliability used for the domain [start, stop].
+Throw an ArgumentError exception in the negative.
+"""
+function check_eligibility_step(start::Floatmu{szE,szf}, stop::Floatmu{szE,szf},
+                                step::Floatmu{szE,szf}) where {szE,szf}
+    if isnan(start) || isnan(stop) || isinf(start) || isinf(stop)
+        throw(ArgumentError("bounds of the iteration cannot be NaNs or infinities"))
+    end
+    if step == 0.0
+        throw(ArgumentError("the step cannot be zero"))
+    end
+    # Finding the largest distance between two floats in the domain
+    eligible = eligible_step(start,stop)
+    if step < eligible
+        throw(ArgumentError("the step cannot be reliably used. Use a step greater or equal to $eligible"))
+    end
+end
+
+
 """
     FloatmuIterator(start::Floatmu{szE,szf},stop::Floatmu{szE,szf},
                     step::Floatmu{szE,szf}) where {szE,szf}
@@ -1155,8 +1205,26 @@ can be initialized with two `Floatmu{szE,szf}` or with two `Float64`.
 One may iterate from one float to the next (the default) or choose some step. 
 The step may be a number of floats or an amount to add.
 
-An ArgumentError is raised if the bounds are NaNs or if the step chosen is zero
-(or rounds to zero when converted to a `Floatmu{szE,szf}`).
+An ArgumentError is raised if the bounds are NaNs, if the step chosen is zero
+(or rounds to zero when converted to a `Floatmu{szE,szf}`), or if the
+step is a value smaller than the largest distance between two consecutive
+floats in `[last, stop]` (use [`eligible_step`](@ref) to know the smallest
+value allowed).
+
+When the step is an amount to add, the bounds cannot be infinities. 
+
+When the step is a number of floats, infinities are allowed for the bounds and are always
+part of the resulting range:
+```jldoctest
+julia> collect(FloatmuIterator(Floatmu{2,2},-Inf,Inf,5))
+6-element Vector{Floatmu{2, 2}}:
+ -Infμ{2, 2}
+  -1.75
+  -0.5
+   0.75
+   2.0
+  Infμ{2, 2}
+```
 
 # Examples
 ```jldoctest
@@ -1174,31 +1242,35 @@ julia> L2=[x for x = FloatmuIterator(Floatmu{2, 2}, 0.0, 1.0, 2)]
  1.0
 ```
 """
-struct FloatmuIterator{szE,szf}
+mutable struct FloatmuIterator{szE,szf}
     first::Floatmu{szE,szf}
     last::Floatmu{szE,szf}
     step::Union{Int,Floatmu{szE,szf}}
+    stopit::Bool
 
     function FloatmuIterator(start::Floatmu{szE,szf},stop::Floatmu{szE,szf},
                              step::Floatmu{szE,szf}) where {szE,szf}
-        if isnan(start) || isnan(stop)
-            throw(ArgumentError("bounds of the iteration cannot be NaNs"))
-        end
-        if step == 0.0
-            throw(ArgumentError("the step shall be non-null"))
-        end
-        return new{szE,szf}(start,stop,step)
+        check_eligibility_step(start,stop,step);
+
+        return new{szE,szf}(start,stop,step,false)
     end
+    
     function FloatmuIterator(start::Floatmu{szE,szf},stop::Floatmu{szE,szf},
                              step::Float64) where {szE,szf}
-        if isnan(start) || isnan(stop)
-            throw(ArgumentError("bounds of the iteration cannot be NaNs"))
-        end
-        if step == 0.0
-            throw(ArgumentError("the step shall be non-null"))
-        end
-        return new{szE,szf}(start,stop,Floatmu{szE,szf}(step))
+        mustep = Floatmu{szE,szf}(step)
+        check_eligibility_step(start,stop,mustep)
+        return new{szE,szf}(start,stop,mustep,false)
+    end
+    
+    function FloatmuIterator(::Type{Floatmu{szE,szf}},start::Float64,stop::Float64,
+                             step::Float64) where {szE,szf}
+        mustart = Floatmu{szE,szf}(float64_to_uint32mu(start, szE, szf),nothing)
+        mustop = Floatmu{szE,szf}(float64_to_uint32mu(stop, szE, szf),nothing)
+        mustep = Floatmu{szE,szf}(step)
+        check_eligibility_step(mustart,mustop,mustep)
+        return new{szE,szf}(mustart, mustop, mustep, false)
     end
+
     function FloatmuIterator(start::Floatmu{szE,szf},stop::Floatmu{szE,szf},
                              step::Int = 1) where {szE,szf}
         if isnan(start) || isnan(stop)
@@ -1207,8 +1279,9 @@ struct FloatmuIterator{szE,szf}
         if step == 0
             throw(ArgumentError("the step shall be non-null"))
         end
-        return new{szE,szf}(start,stop,step)
+        return new{szE,szf}(start,stop,step,false)
     end
+    
     function FloatmuIterator(::Type{Floatmu{szE,szf}},start::Float64,stop::Float64,
                              step::Int = 1) where {szE,szf}
         if isnan(start) || isnan(stop)
@@ -1218,39 +1291,37 @@ struct FloatmuIterator{szE,szf}
             throw(ArgumentError("the step shall be non-null"))
         end
         return new{szE,szf}(Floatmu{szE,szf}(float64_to_uint32mu(start, szE, szf),nothing),
-                            Floatmu{szE,szf}(float64_to_uint32mu(stop, szE, szf),nothing),step)
-    end
-    function FloatmuIterator(::Type{Floatmu{szE,szf}},start::Float64,stop::Float64,
-                             step::Float64) where {szE,szf}
-        if isnan(start) || isnan(stop)
-            throw(ArgumentError("bounds of the iteration cannot be NaNs"))
-        end
-        mustep = Floatmu{szE,szf}(step)
-        if mustep == 0.0
-            throw(ArgumentError("the step shall be non-null"))
-        end
-        return new{szE,szf}(Floatmu{szE,szf}(float64_to_uint32mu(start, szE, szf),nothing),
-                            Floatmu{szE,szf}(float64_to_uint32mu(stop, szE, szf),nothing),mustep)
+                            Floatmu{szE,szf}(float64_to_uint32mu(stop, szE, szf),nothing),step,false)
     end
 end
 
 function iterate(iter::FloatmuIterator{szE,szf},state=iter.first) where {szE,szf}
-    if state <= iter.last
+    if state <= iter.last && !iter.stopit
         if iter.step isa Int
-            return (state,nextfloat(state,iter.step))
+            nextstate = nextfloat(state,iter.step)
         else
-            return (state,state+iter.step)
+            nextstate = state+iter.step
         end
+        iter.stopit = (state == nextstate)
+        return (state,nextstate)
     else
         return nothing
     end
 end
 
 function length(iter::FloatmuIterator{szE,szf}) where {szE,szf}
     if iter.step isa Int
-        return ceil(Int,nb_fp_numbers(iter.first,iter.last)/iter.step)
+        nr = (nb_fp_numbers(iter.first,iter.last)-1)/iter.step
+        nt = trunc(nr)
+        if isinf(iter.last)
+            # If the right bound is an infinity, it will be included in the range even
+            # if the number of steps does not match => add 1 value more in the range.
+            return Int(nt) + (nt != nr ? 2 : 1)
+        else
+            return 1 + Int(nt)
+        end
     else
-        return ceil(Int,(Float64(iter.last)-Float64(iter.first))/Float64(iter.step))
+        return 1 + trunc(Int,(Float64(iter.last)-Float64(iter.first))/Float64(iter.step))
     end
 end
 

src/MicroFloatingPoints.jl

@@ -25,6 +25,7 @@ export μ, λ, NaNμ, Infμ
 export FloatmuIterator
 export isinexact, errorsign, reset_inexact, inexact
 export Emax, Emin, nb_fp_numbers, bias
+export eligible_step
 
 include("Floatmu.jl")
 

test/iterator.jl

@@ -1,3 +1,45 @@
-@testset "FloatmuIterator" begin
-    @test [x for x in FloatmuIterator(Floatmu{2,2},0.0,1.0)] == [0.0, 0.25, 0.5, 0.75, 1.0]
+@testset "FloatmuIterator Floatmu Floatmu Floatmu" begin
+    @test collect(FloatmuIterator(Floatmu{2,2}(-0.5),Floatmu{2,2}(0.75),Floatmu{2,2}(0.3))) == [-0.5, -0.25, -0.0, 0.25, 0.5, 0.75]
+end;
+
+@testset "FloatmuIterator Floatmu Floatmu Float64" begin
+    @test collect(FloatmuIterator(Floatmu{2,2}(0.0),Floatmu{2,2}(1.75),0.7)) == [0.0, 0.75, 1.5]
+    @test_throws ArgumentError collect(FloatmuIterator(Floatmu{2,2}(1.0),Floatmu{2,2}(3.5),0.1))
+end;
+
+@testset "FloatmuIterator Floatmu Floatmu [Int]" begin
+    @test collect(FloatmuIterator(Floatmu{2,2}(0.0),Floatmu{2,2}(1.75),4)) == [0.0, 1.0]
+end;
+
+@testset "FloatmuIterator Type Float64 Float64 [Int]" begin
+    @test collect(FloatmuIterator(Floatmu{2,2},0.0,1.0)) == [0.0, 0.25, 0.5, 0.75, 1.0]
+    @test collect(FloatmuIterator(Floatmu{2,2},1.0,Inf)) == [1.0, 1.25, 1.5, 1.75, 2.0, 2.5, 3, 3.5, Infμ(Floatmu{2,2})]
+    @test collect(FloatmuIterator(Floatmu{2,2},-Inf,-1.0)) == [-Infμ(Floatmu{2,2}), -3.5, -3, -2.5, -2.0, -1.75, -1.5, -1.25, -1.0]
+    @test collect(FloatmuIterator(Floatmu{2,2},-Inf,Inf,5)) == [-Infμ(Floatmu{2,2}), -1.75, -0.5, 0.75, 2.0, Infμ(Floatmu{2,2})]
+end;
+
+@testset "FloatmuIterator Type Float64 Float64 Float64" begin
+    @test_throws ArgumentError collect(FloatmuIterator(Floatmu{2,2},1.25,3.0,0.25))
+end;
+
+@testset "length" begin
+    @test length(FloatmuIterator(Floatmu{2,2},-0.25,2.5)) == 11
+    @test length(FloatmuIterator(Floatmu{2,2},-3.0,-0.5)) == 9
+    @test length(FloatmuIterator(Floatmu{2,2},-Inf,-1.5)) == 7
+    @test length(FloatmuIterator(Floatmu{2,2},-Inf,Inf)) == 25
+    @test length(FloatmuIterator(Floatmu{2,2},-Inf,Inf,3)) == 9
+    @test length(FloatmuIterator(Floatmu{2,2},-3.5,3.5,1.0)) == 8
+    @test length(FloatmuIterator(Floatmu{2,2},-1.0,1.5,0.25)) == 11
+    @test length(FloatmuIterator(Floatmu{2,2},-1.0,1.5,0.5)) == 6
+    @test length(FloatmuIterator(Floatmu{2,2}(0.0),Floatmu{2,2}(1.75),0.7)) == 3
+    @test length(FloatmuIterator(Floatmu{2,2}(0.0),Floatmu{2,2}(1.75),4)) == 2
+end;
+
+@testset "eligible_step" begin
+    @test eligible_step(Floatmu{2,2}(0.25),Floatmu{2,2}(2.0)) == 0.25
+    @test eligible_step(Floatmu{2,2}(0.25),Floatmu{2,2}(2.5)) == 0.5
+    @test eligible_step(Floatmu{8,23}(0.0),Floatmu{8,23}(1.0)) == 2.0^-24
+    @test eligible_step(Floatmu{8,23}(-1.0),Floatmu{8,23}(0.0)) == 2.0^-24
+    @test eligible_step(Floatmu{8,23}(-1.0),Floatmu{8,23}(0.5)) == 2.0^-24
+    @test eligible_step(Floatmu{8,23}(-0.5),Floatmu{8,23}(1.0)) == 2.0^-24
 end;