Opened 10 years ago

Closed 8 years ago

#3898 closed bug (fixed)

Many floating point documentation/behaviour mismatches.

Reported by: draconx Owned by: daniel.is.fischer
Priority: high Milestone: 7.4.1
Component: libraries/base Version: 6.12.1
Keywords: Cc:
Operating System: Unknown/Multiple Architecture: Unknown/Multiple
Type of failure: None/Unknown Test Case:
Blocked By: Blocking:
Related Tickets: Differential Rev(s):
Wiki Page:

Description

I was looking at the haddock documentation for the Prelude to find out what the heck isIEEE did (which didn't actually help: what makes a value an "IEEE floating point number"? I'm guessing it is a constant function which indicates conformance of the _type_ to a particular standard), when I found a number of mismatches between the documentation and the behaviour.

  • The documentation for scaleFloat says "multiplies a floating point number by an integer power of the radix". But it doesn't do this:
floatRadix (1/0)
--> 2

1/0 * 2^^(-1)
--> Infinity

scaleFloat (-1) (1/0)
--> 8.98846567431158e307

In this case, I consider the documentation correct and the implementation wrong: scaleFloat should behave similarly to C's scalbln.

  • The documentation for exponent says "the second component of decodeFloat".
decodeFloat 5
--> (5629499534213120,-50)

exponent 5
--> 3

In this case, it is probably just the documentation that is wrong.

  • The documentation for encodeFloat says "performs the inverse of decodeFloat".
id $ 0/0
--> NaN

uncurry encodeFloat . decodeFloat $ 0/0
--> -Infinity

In this case, I'm not sure which is wrong.

Change History (8)

comment:1 Changed 10 years ago by igloo

Milestone: 6.14.1
Priority: normalhigh

Thanks for the report.

comment:2 Changed 9 years ago by simonmar

Owner: set to igloo

Ian, I think the first two are doc bugs and the third issue is a duplicate of #3134.

comment:3 Changed 9 years ago by draconx

The first is an implementation issue, I think. To avoid surprises, scaleFloat _should_ correspond to the scaleB operation defined in the IEEE standard.

Specifically: "scaleB(x, N) is x * bN for integral values N [b is the floating point radix]. The result is computed as if the exact product were formed and then rounded to the destination format, subject to the applicable rounding-direction attribute."

In particular:

scaleFloat 0  x = x
scaleFloat n ±0 = ±0
scaleFloat n ±∞ = ±∞

(none of these identities are satisfied by the current implementation of scaleFloat).

comment:4 Changed 9 years ago by igloo

Milestone: 7.0.17.0.2

comment:5 Changed 9 years ago by igloo

Milestone: 7.0.27.2.1

comment:6 Changed 8 years ago by daniel.is.fischer

Owner: changed from igloo to daniel.is.fischer

I'm taking over since it's now my department. We have the scaleFloat fix, I'm going to change the docs for exponent and encodeFloat/decodeFloat, then the priority can be lowered. Before changing the behaviour of decodeFloat, I'll ask on libraries what behaviour is preferred with respect to NaN, Infinity and -0.0.

comment:7 Changed 8 years ago by daniel.is.fischer

Status: newmerge

Docs updated in changeset:6f898989f50427fc11135d3b408ca5995a3bc09f and changeset:fd19a7c3ef2ce00950f619db537d51318f0b02f8

Since it's docs only, I think it should be merged in the 7.2 branch even though that's close to release.

Regarding the behaviour of decodeFloat, I think it's enough to leave #3134 open.

comment:8 Changed 8 years ago by igloo

Milestone: 7.2.17.4.1
Resolution: fixed
Status: mergeclosed

Didn't make it in time for 7.2.1, and we won't be making a 7.2.2.

Note: See TracTickets for help on using tickets.