Document failure conditions

[jangler]

As someone new to this crate, I've had a lot of questions about when operations can fail. Like: why can a fraction have a None numerator or denominator? When might conversion to floats fail, and why can this happen if Fraction is advertised as a drop-in float replacement? When can NaNs arise? So far I haven't found the answers to these questions in the documentation, although I've been able to answer some of them with the source code. If I missed something please let me know!

[dnsl48]

Hi @jangler, thank you for the feedback!
You are indeed correct, we can do a lot better on the documentation side of things.

why can a fraction have a None numerator or denominator?

That is usually the case for Inf/NaN values, which have no valid numerator/denominator.

When might conversion to floats fail

There are multiple scenarios. Mostly if the underlying types don't have enough memory to represent values in a lossless way. E.g. could be for a fraction like 1/3, or when using too small data types (e.g. u8) which can't hold the values for relevant calculations.

Fraction is advertised as a drop-in float replacement

Indeed, this is the original idea for the crate, to have a lossless alternative. Half of the crate design decisions stem from the idea of having a lossless type. Other decisions are from having as much compatibility with float type as reasonable. Thus, we support NaN/Inf, but also aspire having lossless math with granular control over stack-vs-heap memory allocations. E.g. float is a Copy type, so having a drop-in type might require Fraction to implement Copy in some scenarios. This is achievable with Fraction via some trade-offs. On the other hand, having a heap allocation for infinite precision and big numbers is also possible, but obviously, losing Copy semantics and leveraging heap allocations.
Thus, this crate approach is to let users choose the trade-offs for their particular scenario.

So far I haven't found the answers to these questions in the documentation

Good point. Let's keep this issue open as a reminder to add better docs. I will try to prioritise this as well. Of course, any contributions are most welcome too!