-
Notifications
You must be signed in to change notification settings - Fork 183
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[Documentation] Tolerance handling in checked_exp_with_tolerance
method
#587
Comments
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. |
Thanks for the answer.
I understand the role of tolerance and think it is a very intuitive API. ProposalIf the idea is that Alternative 1Change the return type to signal that the result is not within the tolerance level specified.
to
where Alternative 2A different approach would be to accept a |
Hi! Thanks for the crate!
This request concerns the desired documentation about the handling of tolerance.
The method
checked_exp_with_tolerance
is the only one that accepts a tolerance in therust_decimal::MathematicalOps
trait.The current documentation for
checked_exp_with_tolerance
says the following.The tolerance being a "hint" does not imply any guarantee for the computation.
In the implementation of
Decimal
, a fixed-length factorial expansion is used, which is very reasonable.Would you consider adding some words about the guarantees one can make about the tolerance?
Even guarantees within a range of
Decimal
would be appreciated.(I know precision guarantees are hard, so thanks for considering this request.)
The text was updated successfully, but these errors were encountered: