Add checked, wrapping and saturating arithmetic for add/sub/neg

The default arithmetic is still the wrapping arithmetic.

Author: kimikage

src/FixedPointNumbers.jl

@@ -11,7 +11,7 @@ import Base: ==, <, <=, -, +, *, /, ~, isapprox,
 
 import Statistics   # for _mean_promote
 
-using Base.Checked: checked_add, checked_sub, checked_div
+import Base.Checked: checked_neg, checked_add, checked_sub, checked_div
 
 using Base: @pure
 
@@ -34,7 +34,9 @@ export
 # "special" typealiases
     # Q and N typealiases are exported in separate source files
 # Functions
-    scaledual
+    scaledual,
+    wrapping_neg, wrapping_add, wrapping_sub,
+    saturating_neg, saturating_add, saturating_sub
 
 include("utilities.jl")
 
@@ -178,6 +180,49 @@ floattype(::Type{Base.TwicePrecision{T}}) where T<:Union{Float16,Float32} = wide
 
 float(x::FixedPoint) = convert(floattype(x), x)
 
+# wrapping arithmetic
+wrapping_neg(x::X) where {X <: FixedPoint} = X(-x.i, 0)
+wrapping_add(x::X, y::X) where {X <: FixedPoint} = X(x.i + y.i, 0)
+wrapping_sub(x::X, y::X) where {X <: FixedPoint} = X(x.i - y.i, 0)
+
+# saturating arithmetic
+saturating_neg(x::X) where {X <: FixedPoint} = X(~min(x.i - true, x.i), 0)
+saturating_neg(x::X) where {X <: FixedPoint{<:Unsigned}} = zero(X)
+
+function saturating_add(x::X, y::X) where {X <: FixedPoint}
+    r, f = Base.Checked.add_with_overflow(x.i, y.i)
+    ifelse(f, ifelse(y.i < 0, typemin(X), typemax(X)), X(r, 0))
+end
+saturating_add(x::X, y::X) where {X <: FixedPoint{<:Unsigned}} = X(x.i + min(~x.i, y.i), 0)
+
+function saturating_sub(x::X, y::X) where {X <: FixedPoint}
+    r, f = Base.Checked.sub_with_overflow(x.i, y.i)
+    ifelse(f, ifelse(y.i < 0, typemax(X), typemin(X)), X(r, 0))
+end
+saturating_sub(x::X, y::X) where {X <: FixedPoint{<:Unsigned}} = X(x.i - min(x.i, y.i), 0)
+
+# checked arithmetic
+checked_neg(x::X) where {X <: FixedPoint} = X(checked_neg(x.i), 0)
+checked_add(x::X, y::X) where {X <: FixedPoint} = X(checked_add(x.i, y.i), 0)
+checked_sub(x::X, y::X) where {X <: FixedPoint} = X(checked_sub(x.i, y.i), 0)
+
+# default arithmetic
+const DEFAULT_ARITHMETIC = :wrapping
+
+for (op, name) in ((:-, :neg), )
+    f = Symbol(DEFAULT_ARITHMETIC, :_, name)
+    @eval begin
+        $op(x::X) where {X <: FixedPoint} = $f(x)
+    end
+end
+for (op, name) in ((:+, :add), (:-, :sub))
+    f = Symbol(DEFAULT_ARITHMETIC, :_, name)
+    @eval begin
+        $op(x::X, y::X) where {X <: FixedPoint} = $f(x, y)
+    end
+end
+
+
 function minmax(x::X, y::X) where {X <: FixedPoint}
     a, b = minmax(reinterpret(x), reinterpret(y))
     X(a,0), X(b,0)
@@ -227,12 +272,12 @@ for f in (:(==), :<, :<=, :div, :fld, :fld1)
         $f(x::X, y::X) where {X <: FixedPoint} = $f(x.i, y.i)
     end
 end
-for f in (:-, :~, :abs)
+for f in (:~, :abs)
     @eval begin
         $f(x::X) where {X <: FixedPoint} = X($f(x.i), 0)
     end
 end
-for f in (:+, :-, :rem, :mod, :mod1, :min, :max)
+for f in (:rem, :mod, :mod1, :min, :max)
     @eval begin
         $f(x::X, y::X) where {X <: FixedPoint} = X($f(x.i, y.i), 0)
     end

test/fixed.jl

@@ -1,5 +1,6 @@
 using FixedPointNumbers, Statistics, Test
 using FixedPointNumbers: bitwidth
+using Base.Checked
 
 function test_op(fun::F, ::Type{T}, fx, fy, fxf, fyf, tol) where {F,T}
     # Make sure that the result is representable
@@ -129,6 +130,55 @@ end
     end
 end
 
+@testset "neg" begin
+    for F in (Q0f7, Q7f8, Q0f15, Q15f16, Q0f31, Q31f32, Q0f63)
+        @test   wrapping_neg(typemin(F)) === typemin(F)
+        @test saturating_neg(typemin(F)) === typemax(F)
+        @test_throws OverflowError checked_neg(typemin(F))
+
+        @test   wrapping_neg(typemax(F)) === typemin(F) + eps(F)
+        @test saturating_neg(typemax(F)) === typemin(F) + eps(F)
+        @test    checked_neg(typemax(F)) === typemin(F) + eps(F)
+
+        @test   wrapping_neg(eps(F)) === zero(F) - eps(F)
+        @test saturating_neg(eps(F)) === zero(F) - eps(F)
+        @test    checked_neg(eps(F)) === zero(F) - eps(F)
+    end
+end
+
+@testset "add" begin
+    for F in (Q0f7, Q7f8, Q0f15, Q15f16, Q0f31, Q31f32, Q0f63)
+        @test   wrapping_add(typemin(F), typemin(F)) === zero(F)
+        @test saturating_add(typemin(F), typemin(F)) === typemin(F)
+        @test_throws OverflowError checked_add(typemin(F), typemin(F))
+
+        @test   wrapping_add(typemax(F), eps(F)) ===   wrapping_add(eps(F), typemax(F)) === typemin(F)
+        @test saturating_add(typemax(F), eps(F)) === saturating_add(eps(F), typemax(F)) === typemax(F)
+        @test_throws OverflowError checked_add(typemax(F), eps(F))
+        @test_throws OverflowError checked_add(eps(F), typemax(F))
+
+        @test   wrapping_add(zero(F), eps(F)) ===   wrapping_add(eps(F), zero(F)) === eps(F)
+        @test saturating_add(zero(F), eps(F)) === saturating_add(eps(F), zero(F)) === eps(F)
+        @test    checked_add(zero(F), eps(F)) ===    checked_add(eps(F), zero(F)) === eps(F)
+    end
+end
+
+@testset "sub" begin
+    for F in (Q0f7, Q7f8, Q0f15, Q15f16, Q0f31, Q31f32, Q0f63)
+        @test   wrapping_sub(typemin(F), typemin(F)) === zero(F)
+        @test saturating_sub(typemin(F), typemin(F)) === zero(F)
+        @test    checked_sub(typemin(F), typemin(F)) === zero(F)
+
+        @test   wrapping_sub(typemin(F), eps(F)) === typemax(F)
+        @test saturating_sub(typemin(F), eps(F)) === typemin(F)
+        @test_throws OverflowError checked_sub(typemin(F), eps(F))
+
+        @test   wrapping_sub(eps(F), zero(F)) === eps(F)
+        @test saturating_sub(eps(F), zero(F)) === eps(F)
+        @test    checked_sub(eps(F), zero(F)) === eps(F)
+    end
+end
+
 @testset "rounding" begin
     for T in (Int8, Int16, Int32, Int64)
         rs = vcat([ oneunit(T) << b - oneunit(T) for b = 0:bitwidth(T)-1],

test/normed.jl

@@ -1,5 +1,6 @@
 using FixedPointNumbers, Statistics, Test
 using FixedPointNumbers: bitwidth
+using Base.Checked
 
 @testset "domain of f" begin
     @test_throws DomainError zero(Normed{UInt8,-1})
@@ -276,6 +277,55 @@ end
     end
 end
 
+@testset "neg" begin
+    for N in (N0f8, N8f8, N0f16, N16f16, N0f32, N32f32, N0f64)
+        @test   wrapping_neg(typemin(N)) === zero(N)
+        @test saturating_neg(typemin(N)) === zero(N)
+        @test    checked_neg(typemin(N)) === zero(N)
+
+        @test   wrapping_neg(typemax(N)) === eps(N)
+        @test saturating_neg(typemax(N)) === zero(N)
+        @test_throws OverflowError checked_neg(typemax(N))
+
+        @test   wrapping_neg(eps(N)) === typemax(N)
+        @test saturating_neg(eps(N)) === zero(N)
+        @test_throws OverflowError checked_neg(eps(N))
+    end
+end
+
+@testset "add" begin
+    for N in (N0f8, N8f8, N0f16, N16f16, N0f32, N32f32, N0f64)
+        @test   wrapping_add(typemin(N), typemin(N)) === zero(N)
+        @test saturating_add(typemin(N), typemin(N)) === zero(N)
+        @test    checked_add(typemin(N), typemin(N)) === zero(N)
+
+        @test   wrapping_add(typemax(N), eps(N)) ===   wrapping_add(eps(N), typemax(N)) === zero(N)
+        @test saturating_add(typemax(N), eps(N)) === saturating_add(eps(N), typemax(N)) === typemax(N)
+        @test_throws OverflowError checked_add(typemax(N), eps(N))
+        @test_throws OverflowError checked_add(eps(N), typemax(N))
+
+        @test   wrapping_add(zero(N), eps(N)) ===   wrapping_add(eps(N), zero(N)) === eps(N)
+        @test saturating_add(zero(N), eps(N)) === saturating_add(eps(N), zero(N)) === eps(N)
+        @test    checked_add(zero(N), eps(N)) ===    checked_add(eps(N), zero(N)) === eps(N)
+    end
+end
+
+@testset "sub" begin
+    for N in (N0f8, N8f8, N0f16, N16f16, N0f32, N32f32, N0f64)
+        @test   wrapping_sub(typemin(N), typemin(N)) === zero(N)
+        @test saturating_sub(typemin(N), typemin(N)) === zero(N)
+        @test    checked_sub(typemin(N), typemin(N)) === zero(N)
+
+        @test   wrapping_sub(typemin(N), eps(N)) === typemax(N)
+        @test saturating_sub(typemin(N), eps(N)) === typemin(N)
+        @test_throws OverflowError checked_sub(typemin(N), eps(N))
+
+        @test   wrapping_sub(eps(N), zero(N)) === eps(N)
+        @test saturating_sub(eps(N), zero(N)) === eps(N)
+        @test    checked_sub(eps(N), zero(N)) === eps(N)
+    end
+end
+
 @testset "rounding" begin
     for T in (UInt8, UInt16, UInt32, UInt64)
         rs = vcat([ oneunit(T) << b - oneunit(T) << 1 for b = 1:bitwidth(T)],