diff options
| author | Martin Handley <psxmah@nottingham.ac.uk> | 2020-06-22 06:54:38 +0100 |
|---|---|---|
| committer | Marge Bot <ben+marge-bot@smart-cactus.org> | 2020-07-01 15:42:14 -0400 |
| commit | fb5a0d01d575cdb830918a6a0406f385de2749c2 (patch) | |
| tree | bcda26e15a2d49303994f6c418be83d2817e6d24 | |
| parent | cbb6b62f54c77637e29bc66e3d1214541c347753 (diff) | |
| download | haskell-fb5a0d01d575cdb830918a6a0406f385de2749c2.tar.gz | |
#17169: Clarify Fixed's Enum instance.
| -rw-r--r-- | libraries/base/Data/Fixed.hs | 58 |
1 files changed, 58 insertions, 0 deletions
diff --git a/libraries/base/Data/Fixed.hs b/libraries/base/Data/Fixed.hs index 232175a1ab..7482d1a4cb 100644 --- a/libraries/base/Data/Fixed.hs +++ b/libraries/base/Data/Fixed.hs @@ -94,6 +94,64 @@ withResolution :: (HasResolution a) => (Integer -> f a) -> f a withResolution foo = withType (foo . resolution) -- | @since 2.01 +-- +-- Recall that, for numeric types, 'succ' and 'pred' typically add and subtract +-- @1@, respectively. This is not true in the case of 'Fixed', whose successor +-- and predecessor functions intuitively return the "next" and "previous" values +-- in the enumeration. The results of these functions thus depend on the +-- resolution of the 'Fixed' value. For example, when enumerating values of +-- resolution @10^-3@ of @type Milli = Fixed E3@, +-- +-- @ +-- succ (0.000 :: Milli) == 1.001 +-- @ +-- +-- +-- and likewise +-- +-- @ +-- pred (0.000 :: Milli) == -0.001 +-- @ +-- +-- +-- In other words, 'succ' and 'pred' increment and decrement a fixed-precision +-- value by the least amount such that the value's resolution is unchanged. +-- For example, @10^-12@ is the smallest (positive) amount that can be added to +-- a value of @type Pico = Fixed E12@ without changing its resolution, and so +-- +-- @ +-- succ (0.000000000000 :: Pico) == 0.000000000001 +-- @ +-- +-- +-- and similarly +-- +-- @ +-- pred (0.000000000000 :: Pico) == -0.000000000001 +-- @ +-- +-- +-- This is worth bearing in mind when defining 'Fixed' arithmetic sequences. In +-- particular, you may be forgiven for thinking the sequence +-- +-- @ +-- [1..10] :: [Pico] +-- @ +-- +-- +-- evaluates to @[1, 2, 3, 4, 5, 6, 7, 8, 9, 10] :: [Pico]@. +-- +-- However, this is not true. On the contrary, similarly to the above +-- implementations of 'succ' and 'pred', @enumFromTo :: Pico -> Pico -> [Pico]@ +-- has a "step size" of @10^-12@. Hence, the list @[1..10] :: [Pico]@ has +-- the form +-- +-- @ +-- [1.000000000000, 1.00000000001, 1.00000000002, ..., 10.000000000000] +-- @ +-- +-- +-- and contains @9 * 10^12 + 1@ values. instance Enum (Fixed a) where succ (MkFixed a) = MkFixed (succ a) pred (MkFixed a) = MkFixed (pred a) |