Document differences between `Ix`'s `inRange` and `UniformRange`'s `isInRange`

[RyanGlScott]

When upgrading a package of mine to support random-1.3.0, I needed to add an implementation of isInRange to a UniformRange instance in order to make it typecheck. There already existed an Ix instance for the same type, and the Ix class offers a very similar-looking inRange method. As such, I was tempted to define isInRange in the UniformRange instance like so:

instance UniformRange T where
  ...
  isInRange = inRange

I later discovered that this is incorrect! This is because UniformRange's isInRange requires the ranges to be symmetric, i.e.,

isInRange (lo, hi) x == isInRange (hi, lo) x

But this law does not necessarily hold for Ix's inRange. This can be seen in the UniformRange and Ix instances for Int:

λ> isInRange (1, 0 :: Int) 0 -- UniformRange
True
λ> inRange (1, 0 :: Int) 0 -- Ix
False

There might be other differences between isInRange and inRange that I am not aware of, but this was one of the more prominent ones that I discovered. I worry that others may fall into the same pitfall. Would you be willing to document these differences in the Haddocks for isInRange to make them more obvious?

[lehins]

Would you be willing to document these differences in the Haddocks for isInRange to make them more obvious?

I am always in favor of more accurate documentation 🙂

@Bodigrim Do you have any comments about this and maybe you would like to take a stab at it, since you'll be the most familiar with isInRange specifics.

[Bodigrim]

The decision to treat (lo, hi) equivalently to (hi, lo) was taken before me, primarily to make uniformRM total. I don't remember any other potential peculiarities of isInRange.

Tangentially, there seems to be something off with haddocks: https://hackage.haskell.org/package/random-1.2.1.3/docs/System-Random-Stateful.html#t:UniformRange does list uniformRM as a member of UniformRange (the only one at that moment), but https://hackage.haskell.org/package/random-1.3.0/docs/System-Random-Stateful.html#t:UniformRange does not list any members at all.

[RyanGlScott]

Tangentially, there seems to be something off with haddocks: https://hackage.haskell.org/package/random-1.2.1.3/docs/System-Random-Stateful.html#t:UniformRange does list uniformRM as a member of UniformRange (the only one at that moment), but https://hackage.haskell.org/package/random-1.3.0/docs/System-Random-Stateful.html#t:UniformRange does not list any members at all.

Hm, perhaps this is a Haddock bug. UniformRange is exported in two different parts of System.Random.Stateful's export list. It is exported directly by name (as UniformRange(..), which also exports its class methods), and it is also indirectly re-exported via the module System.Random export, which does not re-export the class methods. The Haddocks for random-1.2.1.3 combines the two exports into a single one in the HTML output, but the Haddocks for random-1.3.0 do not. (If you Ctrl-F for UniformRange in the random-1.3.0 Haddocks, you will see two entries for UniformRange, one with class members and one without.)