[Documentation] Tolerance handling in `checked_exp_with_tolerance` method about rust-decimal

[paupino]

Yes, great point! Documentation is one area that can always be improved.

In lieu of updating the docs, the short answer is that the tolerance provides the acceptable range in which we can consider the result correct. The lower the tolerance, the more accurate the result, however it also means it may be a slower calculation. We're effectively allowing us to configure how deep into the "series" that we need to go before achieving an acceptable result.

Of course the reverse of this, the higher the tolerance, the more inexact the result is going to potentially be. That said, for some simple applications, this may be fine.

So in terms of guarantees, tolerance is kind of like specifying that the result is going to be within 0 <= x <= tolerance of the final answer OR has reached the end of the series due to not being able to represent a more granular result within Decimal (yet!!!). Because of the latter (i.e. end of the series), it's difficult to make a strong guarantee right now, but hopefully it helps.

[saona-raimundo]

Thanks for the answer.

So in terms of guarantees, tolerance is kind of like specifying that the result is going to be within 0 <= x <= tolerance of the final answer OR has reached the end of the series due to not being able to represent a more granular result within Decimal (yet!!!). Because of the latter (i.e. end of the series), it's difficult to make a strong guarantee right now, but hopefully it helps.

I understand the role of tolerance and think it is a very intuitive API.
But, as a (maybe not so well-informed) user, I expect that a given tolerance specified in Decimal will translate to an actual error guarantee (which is not the case and it is very hard to do).

Proposal

If the idea is that tolerance is really just a hint, and no formal guarantee will be given, I suggest renaming the input tolerance to tolerance_hint and adding to the documentation that no guarantee is given in the result of the computation.

Alternative 1

Change the return type to signal that the result is not within the tolerance level specified.
From

fn checked_exp_with_tolerance(&self, tolerance: Decimal) -> Option<Decimal>

to

fn checked_exp_with_tolerance(&self, tolerance: Decimal) -> Result<Decimal, ToleranceError>

where ToleranceError has variants: Overflow and OutOfRange (or similar).

Alternative 2

A different approach would be to accept a tolerance_level: usize parameter (renamed cutoff or something else) that specifies the number of terms in the expansion used in the computation.
But honestly, I do not know how useful this would be, and accepting any usize is also a problem because the terms of the series are finite, so one can not use the same approach to deal with any usize as a cutoff limit.