Merge pull request #51 from JuliaMath/teh/compact_printing

Compact systematic display of values

Author: timholy

README.md

@@ -28,7 +28,7 @@ is the number of fraction bits.
 
 For `T<:Signed` (a signed integer), there is a fixed-point type
 `Fixed{T, f}`; for `T<:Unsigned` (an unsigned integer), there is the
-`UFixed{T, f}` type. However, there are slight differences in behavior
+`Normed{T, f}` type. However, there are slight differences in behavior
 that go beyond signed/unsigned distinctions.
 
 The `Fixed{T,f}` types use 1 bit for sign, and `f` bits to represent
@@ -43,23 +43,23 @@ is interpreted as if the integer representation has been divided by
 
 because the range of `Int8` is from -128 to 127.
 
-In contrast, the `UFixed{T,f}`, with `f` fraction bits, map the closed
+In contrast, the `Normed{T,f}`, with `f` fraction bits, map the closed
 interval [0.0,1.0] to the span of numbers with `f` bits.  For example,
-the `UFixed8` type (aliased to `UFixed{UInt8,8}`) is represented
+the `Normed8` type (aliased to `Normed{UInt8,8}`) is represented
 internally by a `UInt8`, and makes `0x00` equivalent to `0.0` and
-`0xff` to `1.0`. Consequently, `UFixed` numbers are scaled by `2^f-1`
-rather than `2^f`.  The type aliases `UFixed10`, `UFixed12`,
-`UFixed14`, and `UFixed16` are all based on `UInt16` and reach the
+`0xff` to `1.0`. Consequently, `Normed` numbers are scaled by `2^f-1`
+rather than `2^f`.  The type aliases `Normed10`, `Normed12`,
+`Normed14`, and `Normed16` are all based on `UInt16` and reach the
 value `1.0` at 10, 12, 14, and 16 bits, respectively (`0x03ff`,
 `0x0fff`, `0x3fff`, and `0xffff`).
 
-To construct such a number, use `convert(UFixed12, 1.3)`, `UFixed12(1.3)`, `UFixed{UInt16,12}(1.3)`, or the literal syntax
-`0x14ccuf12`.  The latter syntax means to construct a `UFixed12` (it ends in
+To construct such a number, use `convert(Normed12, 1.3)`, `Normed12(1.3)`, `Normed{UInt16,12}(1.3)`, or the literal syntax
+`0x14ccuf12`.  The latter syntax means to construct a `Normed12` (it ends in
 `uf12`) from the `UInt16` value `0x14cc`.
 
 More generally, an arbitrary number of bits from any of the standard unsigned
 integer widths can be used for the fractional part.  For example:
-`UFixed{UInt32,16}`, `UFixed{UInt64,3}`, `UFixed{UInt128,7}`.
+`Normed{UInt32,16}`, `Normed{UInt64,3}`, `Normed{UInt128,7}`.
 
 There currently is no literal syntax for signed `Fixed` numbers.
 

contrib/deprecation_UFixed.sh

@@ -0,0 +1,8 @@
+sed -i "s/UFixed8/N0f8/g" $*
+sed -i "s/UFixed10/N6f10/g" $*
+sed -i "s/UFixed12/N4f12/g" $*
+sed -i "s/UFixed14/N2f14/g" $*
+sed -i "s/UFixed16/N0f16/g" $*
+# For types from ColorTypes
+sed -i "s/U8/N0f8/g" $*
+sed -i "s/U16/N0f16/g" $*

src/FixedPointNumbers.jl

@@ -26,26 +26,27 @@ using Compat
 # f => Number of Bytes reserved for fractional part
 abstract FixedPoint{T <: Integer, f} <: Real
 
+
 export
     FixedPoint,
     Fixed,
-    UFixed,
-    Fixed16,
-    UFixed8,
-    UFixed10,
-    UFixed12,
-    UFixed14,
-    UFixed16,
-    # literal constructor constants
+    Normed,
+# "special" typealiases
+    # Q and U typealiases are exported in separate source files
+# literal constructor constants
     uf8,
     uf10,
     uf12,
     uf14,
     uf16,
-    # Functions
+# Functions
     scaledual
 
 reinterpret(x::FixedPoint) = x.i
+reinterpret{T,f}(::Type{T}, x::FixedPoint{T,f}) = x.i
+
+# construction using the (approximate) intended value, i.e., N0f8
+*{X<:FixedPoint}(x::Real, ::Type{X}) = X(x)
 
 # comparison
 =={T <: FixedPoint}(x::T, y::T) = x.i == y.i
@@ -90,9 +91,28 @@ floattype{T<:ShortInts,f}(::Type{FixedPoint{T,f}}) = Float32
 floattype{T,f}(::Type{FixedPoint{T,f}}) = Float64
 floattype(x::FixedPoint) = floattype(supertype(typeof(x)))
 
+# This IOBuffer is used during module definition to generate typealias names
+_iotypealias = IOBuffer()
+
+# Printing. These are used to generate type-symbols, so we need them
+# before we include any files.
+function showtype{X<:FixedPoint}(io::IO, ::Type{X})
+    print(io, typechar(X))
+    f = nbitsfrac(X)
+    m = sizeof(X)*8-f-signbits(X)
+    print(io, m, 'f', f)
+    io
+end
+function show{T,f}(io::IO, x::FixedPoint{T,f})
+    showcompact(io, x)
+    showtype(io, typeof(x))
+end
+const _log2_10 = 3.321928094887362
+showcompact{T,f}(io::IO, x::FixedPoint{T,f}) = show(io, round(convert(Float64,x), ceil(Int,f/_log2_10)))
+
 
 include("fixed.jl")
-include("ufixed.jl")
+include("normed.jl")
 include("deprecations.jl")
 
 eps{T<:FixedPoint}(::Type{T}) = T(one(rawtype(T)),0)
@@ -113,14 +133,6 @@ reducedim_init{T<:FixedPoint}(f::typeof(@functorize(identity)),
                               A::AbstractArray{T}, region) =
     reducedim_initarray(A, region, one(Treduce))
 
-# TODO: rewrite this by @generated
-for T in tuple(Fixed16, UF...)
-    R = rawtype(T)
-    @eval begin
-        reinterpret(::Type{$R}, x::$T) = x.i
-    end
-end
-
 for f in (:div, :fld, :fld1)
     @eval begin
         $f{T<:FixedPoint}(x::T, y::T) = $f(reinterpret(x),reinterpret(y))
@@ -141,17 +153,6 @@ scaledual{T<:FixedPoint}(Tdual::Type, x::Union{T,AbstractArray{T}}) =
 scaledual{Tdual<:Number, T<:FixedPoint}(b::Tdual, x::Union{T,AbstractArray{T}}) =
     convert(Tdual, b/one(T)), reinterpret(rawtype(T), x)
 
-# printing
-function show{T,f}(io::IO, x::FixedPoint{T,f})
-    shorttype = typeof(x)<:UFixed ? "UFixed" : "Fixed"
-    print(io, shorttype, "{", T, ",", f, "}")
-    print(io, "(")
-    showcompact(io, x)
-    print(io, ")")
-end
-const _log2_10 = 3.321928094887362
-showcompact{T,f}(io::IO, x::FixedPoint{T,f}) = show(io, round(Float64(x), ceil(Int,f/_log2_10)))
-
 @noinline function throw_converterror{T<:FixedPoint}(::Type{T}, x)
     n = 2^(8*sizeof(T))
     bitstring = sizeof(T) == 1 ? "an 8-bit" : "a $(8*sizeof(T))-bit"

src/deprecations.jl

@@ -1,25 +1,57 @@
 import Base.@deprecate_binding
 
-@deprecate_binding UfixedBase UFixed
-@deprecate_binding UfixedConstructor UFixedConstructor
-@deprecate_binding Ufixed UFixed
-@deprecate_binding Ufixed8 UFixed8
-@deprecate_binding Ufixed10 UFixed10
-@deprecate_binding Ufixed12 UFixed12
-@deprecate_binding Ufixed14 UFixed14
-@deprecate_binding Ufixed16 UFixed16
-
-@deprecate_binding Fixed32 Fixed16
+@deprecate_binding Fixed16 Q15f16
+@deprecate_binding UFixed8 N0f8
+@deprecate_binding UFixed10 N6f10
+@deprecate_binding UFixed12 N4f12
+@deprecate_binding UFixed14 N2f14
+@deprecate_binding UFixed16 N0f16
+
+@deprecate_binding UfixedBase Normed
+@deprecate_binding Ufixed Normed
+@deprecate_binding UFixed Normed
+@deprecate_binding Ufixed8 N0f8
+@deprecate_binding Ufixed10 N6f10
+@deprecate_binding Ufixed12 N4f12
+@deprecate_binding Ufixed14 N2f14
+@deprecate_binding Ufixed16 N0f16
+
+@deprecate_binding Fixed32 Q15f16
+
+const UF = (N0f8, N6f10, N4f12, N2f14, N0f16)
+
 @deprecate Fixed(x::Real) convert(Fixed{Int32, 16}, x)
 
-@deprecate ufixed8(x)  UFixed8(x)
-@deprecate ufixed10(x) UFixed10(x)
-@deprecate ufixed12(x) UFixed12(x)
-@deprecate ufixed14(x) UFixed14(x)
-@deprecate ufixed16(x) UFixed16(x)
+@deprecate ufixed8(x)  N0f8(x)
+@deprecate ufixed10(x) N6f10(x)
+@deprecate ufixed12(x) N4f12(x)
+@deprecate ufixed14(x) N2f14(x)
+@deprecate ufixed16(x) N0f16(x)
 
 Compat.@dep_vectorize_1arg Real ufixed8
 Compat.@dep_vectorize_1arg Real ufixed10
 Compat.@dep_vectorize_1arg Real ufixed12
 Compat.@dep_vectorize_1arg Real ufixed14
 Compat.@dep_vectorize_1arg Real ufixed16
+
+## The next lines mimic the floating-point literal syntax "3.2f0"
+# construction using a UInt, i.e., 0xccuf8
+immutable NormedConstructor{T,f} end
+function *{T,f}(n::Integer, ::NormedConstructor{T,f})
+    i = 8*sizeof(T)-f
+    io = IOBuffer()
+    show(io, n)
+    nstr = takebuf_string(io)
+    cstr = typeof(n) == T ? nstr : "convert($T, $nstr)"
+    Base.depwarn("$(nstr)uf$f is deprecated, please use reinterpret(N$(i)f$f, $cstr) instead", :*)
+    reinterpret(Normed{T,f}, convert(T, n))
+end
+const uf8  = NormedConstructor{UInt8,8}()
+const uf10 = NormedConstructor{UInt16,10}()
+const uf12 = NormedConstructor{UInt16,12}()
+const uf14 = NormedConstructor{UInt16,14}()
+const uf16 = NormedConstructor{UInt16,16}()
+
+@deprecate_binding UfixedConstructor NormedConstructor
+@deprecate_binding UFixedConstructor NormedConstructor
+

src/fixed.jl

@@ -9,13 +9,23 @@ immutable Fixed{T <: Signed,f} <: FixedPoint{T,  f}
     Fixed(x) = convert(Fixed{T,f}, x)
 end
 
-typealias Fixed16 Fixed{Int32, 16}
-
 reinterpret{T<:Signed, f}(::Type{Fixed{T,f}}, x::T) = Fixed{T,f}(x, 0)
 
   rawtype{T,f}(::Type{Fixed{T,f}}) = T
 nbitsfrac{T,f}(::Type{Fixed{T,f}}) = f
 floattype{T<:Fixed}(::Type{T}) = floattype(supertype(T))
+typechar{X<:Fixed}(::Type{X}) = 'Q'
+signbits{X<:Fixed}(::Type{X}) = 1
+
+for T in (Int8, Int16, Int32, Int64)
+    for f in 0:sizeof(T)*8-1
+        sym = Symbol(takebuf_string(showtype(_iotypealias, Fixed{T,f})))
+        @eval begin
+            typealias $sym Fixed{$T,$f}
+            export $sym
+        end
+    end
+end
 
 # basic operators
 -{T,f}(x::Fixed{T,f}) = Fixed{T,f}(-x.i,0)