|
1 | 1 | # FixedPointNumbers |
2 | 2 |
|
3 | | -This library exports fixed-point number types. |
4 | | -A [fixed-point number][wikipedia] represents a fractional, or non-integral, number. |
5 | | -In contrast with the more widely known floating-point numbers, fixed-point |
6 | | -numbers have a fixed number of digits (bits) after the decimal (radix) point. |
7 | | -They are effectively integers scaled by a constant factor. |
| 3 | +This library exports fixed-point number types. A |
| 4 | +[fixed-point number][wikipedia] represents a fractional, or |
| 5 | +non-integral, number. In contrast with the more widely known |
| 6 | +floating-point numbers, with fixed-point numbers the decimal point |
| 7 | +doesn't "float": fixed-point numbers are effectively integers that are |
| 8 | +interpreted as being scaled by a constant factor. Consequently, they |
| 9 | +have a fixed number of digits (bits) after the decimal (radix) point. |
8 | 10 |
|
9 | 11 | Fixed-point numbers can be used to perform arithmetic. Another practical |
10 | 12 | application is to implicitly rescale integers without modifying the |
11 | 13 | underlying representation. |
12 | 14 |
|
13 | 15 | This library exports two categories of fixed-point types. Fixed-point types are |
14 | 16 | used like any other number: they can be added, multiplied, raised to a power, |
15 | | -etc. In many cases these operations result in conversion to floating-point types. |
| 17 | +etc. In some cases these operations result in conversion to floating-point types. |
| 18 | + |
| 19 | +# Type hierarchy and interpretation |
16 | 20 |
|
17 | | -# Type hierarchy |
18 | 21 | This library defines an abstract type `FixedPoint{T <: Integer, f}` as a |
19 | | -subtype of `Real`. The parameter `T` is the underlying representation and `f` |
| 22 | +subtype of `Real`. The parameter `T` is the underlying machine representation and `f` |
20 | 23 | is the number of fraction bits. |
21 | 24 |
|
22 | | -For signed integers, there is a fixed-point type `Fixed{T, f}` and for unsigned |
23 | | -integers, there is the `UFixed{T, f}` type. |
24 | | - |
25 | | -These types, built with `f` fraction bits, map the closed interval [0.0,1.0] to |
26 | | -the span of numbers with `f` bits. For example, the `UFixed8` type (aliased to |
27 | | -UFixed{UInt8,8}) is represented internally by a `UInt8`, and makes `0x00` |
28 | | -equivalent to `0.0` and `0xff` to `1.0`. The type aliases `UFixed10`, `UFixed12`, |
29 | | -`UFixed14`, and `UFixed16` are all based on `UInt16` and reach the value `1.0` |
30 | | -at 10, 12, 14, and 16 bits, respectively (`0x03ff`, `0x0fff`, `0x3fff`, and |
31 | | -`0xffff`). |
32 | | - |
33 | | -To construct such a number, use `convert(UFixed12, 1.3)`, `ufixed12(1.3)` (a |
34 | | -convenience function), `UFixed{UInt16,12}(1.3)`, or the literal syntax |
| 25 | +For `T<:Signed` (a signed integer), there is a fixed-point type |
| 26 | +`Fixed{T, f}`; for `T<:Unsigned` (an unsigned integer), there is the |
| 27 | +`UFixed{T, f}` type. However, there are slight differences in behavior |
| 28 | +that go beyond signed/unsigned distinctions. |
| 29 | + |
| 30 | +The `Fixed{T,f}` types use 1 bit for sign, and `f` bits to represent |
| 31 | +the fraction. For example, `Fixed{Int8,7}` uses 7 bits (all bits |
| 32 | +except the sign bit) for the fractional part. The value of the number |
| 33 | +is interpreted as if the integer representation has been divided by |
| 34 | +`2^f`. Consequently, `Fixed{Int8,7}` numbers `x` satisfy |
| 35 | + |
| 36 | +``` |
| 37 | +-1.0 = -128/128 ≤ x ≤ 127/128 ≈ 0.992. |
| 38 | +``` |
| 39 | + |
| 40 | +because the range of `Int8` is from -128 to 127. |
| 41 | + |
| 42 | +In contrast, the `UFixed{T,f}`, with `f` fraction bits, map the closed |
| 43 | +interval [0.0,1.0] to the span of numbers with `f` bits. For example, |
| 44 | +the `UFixed8` type (aliased to `UFixed{UInt8,8}`) is represented |
| 45 | +internally by a `UInt8`, and makes `0x00` equivalent to `0.0` and |
| 46 | +`0xff` to `1.0`. Consequently, `UFixed` numbers are scaled by `2^f-1` |
| 47 | +rather than `2^f`. The type aliases `UFixed10`, `UFixed12`, |
| 48 | +`UFixed14`, and `UFixed16` are all based on `UInt16` and reach the |
| 49 | +value `1.0` at 10, 12, 14, and 16 bits, respectively (`0x03ff`, |
| 50 | +`0x0fff`, `0x3fff`, and `0xffff`). |
| 51 | + |
| 52 | +To construct such a number, use `convert(UFixed12, 1.3)`, `UFixed12(1.3)`, `UFixed{UInt16,12}(1.3)`, or the literal syntax |
35 | 53 | `0x14ccuf12`. The latter syntax means to construct a `UFixed12` (it ends in |
36 | 54 | `uf12`) from the `UInt16` value `0x14cc`. |
37 | 55 |
|
38 | 56 | More generally, an arbitrary number of bits from any of the standard unsigned |
39 | 57 | integer widths can be used for the fractional part. For example: |
40 | 58 | `UFixed{UInt32,16}`, `UFixed{UInt64,3}`, `UFixed{UInt128,7}`. |
41 | 59 |
|
42 | | -There currently is no literal syntax for signed `Fixed` numbers. |
| 60 | +There currently is no literal syntax for signed `Fixed` numbers. |
43 | 61 |
|
44 | 62 | [wikipedia]: http://en.wikipedia.org/wiki/Fixed-point_arithmetic |
0 commit comments