@@ -113,11 +113,11 @@ newtype Fixed (precision :: Precision) = Fixed BigInt.BigInt
113113-- | Extract the numerator from the representation of the number as a fraction.
114114-- |
115115-- | ```
116−-- | > numerator (fromNumber 0.1234 :: Fixed P1000)
117−-- | fromString "123"
116+-- | > map numerator (fromNumber 0.1234 :: Fixed P1000)
117+-- | (Just fromString "123")
118118-- |
119−-- | > numerator (fromNumber 0.1239 :: Fixed P1000)
120−-- | fromString "123"
119+-- | > map numerator (fromNumber 0.1239 :: Fixed P1000)
120+-- | (Just fromString "123")
121121-- | ```
122122numerator :: forall precision. Fixed precision -> BigInt.BigInt
123123numerator (Fixed n) = n
@@ -136,11 +136,21 @@ fromInt i = Fixed (BigInt.fromInt i * BigInt.fromInt (reflectPrecision (PProxy :
136136-- | Approximate a `Number` as a `Fixed` value with the specified precision.
137137-- |
138138-- | ```
139−-- | > fromNumber 0.1234 :: Fixed P10000
140−-- | fromNumber 0.1234 :: P100
139+-- | > fromNumber 0.1234 :: Maybe (Fixed P10000)
140+-- | (Just (fromNumber 0.1234 :: P10000))
141141-- |
142−-- | > fromNumber 0.1234 :: Fixed P100
143−-- | fromNumber 0.12 :: P100
142+-- | > fromNumber 0.1234 :: Maybe (Fixed P100)
143+-- | (Just (fromNumber 0.12 :: P100))
144+-- | ```
145+-- |
146+-- | When given a finite `Number`, this function always succeeds: the number is
147+-- | truncated (rounded towards zero) to the closest possible `Fixed` value.
148+-- | This function only returns `Nothing` if it is given NaN, or positive or
149+-- | negative infinity.
150+-- |
151+-- | ```
152+-- | > fromNumber (1.0 / 0.0) :: Maybe (Fixed P100)
153+-- | Nothing
144154-- | ```
145155fromNumber
146156 :: forall precision
@@ -163,14 +173,14 @@ toNumber f = BigInt.toNumber (numerator f) / Int.toNumber (denominator f)
163173-- | value.
164174-- |
165175-- | ```
166−-- | > floor $ fromNumber 0.1 :: Fixed P10
167−-- | fromNumber 0.0 :: P10
176+-- | > map floor $ fromNumber 0.1 :: Maybe (Fixed P10)
177+-- | (Just (fromNumber 0.0 :: P10))
168178-- |
169−-- | > floor $ fromNumber 1.0 :: Fixed P10
170−-- | fromNumber 1.0 :: P10
179+-- | > map floor $ fromNumber 1.0 :: Maybe (Fixed P10)
180+-- | (Just (fromNumber 1.0 :: P10))
171181-- |
172−-- | > floor $ fromNumber (-0.1) :: Fixed P10
173−-- | fromNumber (-1.0) :: P10
182+-- | > floor $ fromNumber (-0.1) :: Maybe (Fixed P10)
183+-- | (Just (fromNumber (-1.0) :: P10))
174184-- | ```
175185floor
176186 :: forall precision
@@ -187,14 +197,14 @@ floor n = Fixed (numerator n - x) where
187197-- | value.
188198-- |
189199-- | ```
190−-- | > ceil $ fromNumber 0.1 :: Fixed P10
191−-- | fromNumber 1.0 :: P10
200+-- | > map ceil $ fromNumber 0.1 :: Maybe (Fixed P10)
201+-- | (Just (fromNumber 1.0 :: P10))
192202-- |
193−-- | > ceil $ fromNumber 1.0 :: Fixed P10
194−-- | fromNumber 1.0 :: P10
203+-- | > map ceil $ fromNumber 1.0 :: Maybe (Fixed P10)
204+-- | (Just (fromNumber 1.0 :: P10))
195205-- |
196−-- | > ceil $ fromNumber (-0.1) :: Fixed P10
197−-- | fromNumber 0.0 :: P10
206+-- | > map ceil $ fromNumber (-0.1) :: Maybe (Fixed P10)
207+-- | (Just (fromNumber 0.0 :: P10))
198208-- | ```
199209ceil
200210 :: forall precision
@@ -211,17 +221,17 @@ ceil n = Fixed (numerator n + x) where
211221-- | Round the specified value to the nearest whole number.
212222-- |
213223-- | ```
214−-- | > round $ fromNumber 0.1 :: Fixed P10
215−-- | fromNumber 0.0 :: P10
224+-- | > map round $ fromNumber 0.1 :: Maybe (Fixed P10)
225+-- | (Just (fromNumber 0.0 :: P10))
216226-- |
217−-- | > round $ fromNumber 0.9 :: Fixed P10
218−-- | fromNumber 1.0 :: P10
227+-- | > map round $ fromNumber 0.9 :: Maybe (Fixed P10)
228+-- | (Just (fromNumber 1.0 :: P10))
219229-- |
220−-- | > round $ fromNumber 0.5 :: Fixed P10
221−-- | fromNumber 1.0 :: P10
230+-- | > map round $ fromNumber 0.5 :: Maybe (Fixed P10)
231+-- | (Just (fromNumber 1.0 :: P10))
222232-- |
223−-- | > round $ fromNumber (-0.1) :: Fixed P10
224−-- | fromNumber 0.0 :: P10
233+-- | > map round $ fromNumber (-0.1) :: Maybe (Fixed P10)
234+-- | (Just (fromNumber 0.0 :: P10))
225235-- | ```
226236round
227237 :: forall precision
@@ -238,16 +248,16 @@ round n = Fixed (numerator n + x) where
238248-- | Approximate division of fixed-precision numbers.
239249-- |
240250-- | ```
241−-- | > fromNumber 22.0 `approxDiv` fromNumber 7.0 :: Fixed P100
242−-- | fromNumber 3.14 :: P100
251+-- | > lift2 approxDiv (fromNumber 22.0) (fromNumber 7.0) :: Maybe (Fixed P100)
252+-- | (Just (fromNumber 3.14 :: P100))
243253-- | ```
244254-- |
245255-- | _Note_: `Fixed` is not a `EuclideanRing` in general - it is not even
246256-- | an integral domain, since it has non-zero zero-divisors:
247257-- |
248258-- | ```
249−-- | > fromNumber 0.1 * fromNumber 0.1 :: Fixed P10
250−-- | fromNumber 0.0 :: P10
259+-- | > lift2 (*) (fromNumber 0.1) (fromNumber 0.1) :: Maybe (Fixed P10)
260+-- | (Just (fromNumber 0.0 :: P10))
251261-- | ```
252262approxDiv
253263 :: forall precision