Add isClose, a replacement for approxEqual

[ghost]

This is a replacement for PR #7187, because I had to remove my old account on GitHub.

My original comment was:

As suggested in PR #7173, I wrote a new version of approxEqual (called isClose to avoid naming conflicts), which is based on the thoughts given in [1]. The purpose of both functions is the same, namely providing a utility for comparing floating point numbers. This is necessary, because operations on floating point numbers inevitably produce rounding errors and therefore cannot be compared reasonable using ==.

The main difference is, that this function has much stronger default values for the error allowed, based on the capabilities of the used floating point type. This helps in catching errors, especially as approxEqual is mainly used in unittests. This addresses issue #15881. Together with PR #7180 this can be considered a fix for that issue.

The new function is furthermore symmetric, to avoid users being confused or have to remember the order of the operands. This addresses issue #15763.

After this PR has been approved I think, it would be wise to continue with the following roadmap:

1. replace all occurences of approxEqual in Phobos by isClose. With one exception, approxEqual is only used in unittests. The exception is secantMethod in std/numerical.d.
2. deprecate approxEqual in favour of isClose. (I don't know if I'm in the position to deprecate anything, nor to ask for it, but I think, this would be a good idea in the long-run.)
3. After some time, remove approxEqual alltogether.

[1] https://www.python.org/dev/peps/pep-0485/

[dlang-bot]

Thanks for your pull request and interest in making D better, @berni44! We are looking forward to reviewing it, and you should be hearing from a maintainer soon.
Please verify that your PR follows this checklist:

• My PR is fully covered with tests (you can see the coverage diff by visiting the details link of the codecov check)
• My PR is as minimal as possible (smaller, focused PRs are easier to review than big ones)
• I have provided a detailed rationale explaining my changes
• New or modified functions have Ddoc comments (with Params: and Returns:)

Please see CONTRIBUTING.md for more information.

---

If you have addressed all reviews or aren't sure how to proceed, don't hesitate to ping us with a simple comment.

Bugzilla references

Your PR doesn't reference any Bugzilla issue.

If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog.

Testing this PR locally

If you don't have a local development environment setup, you can use Digger to test this PR:

dub fetch digger
dub run digger -- build "master + phobos#7241"

[thewilsonator]

Sorry for missing this.

[ghost]

Don't worry. It's not that important to me (else I would have pinged) - I thought, it might be a problem, because a new name is introduced.

Patches are on the way.

[thewilsonator]

Thanks.

[thewilsonator]

Otherwise looks good.

[quickfur]

This is a pretty significant change, and IMO notable enough to be included in the release notes. Can you submit a follow-up PR to add the corresponding file in changelog/ describing this change? (We're still using that for generating release notes, right?)

[ghost]

I'm currently working on replacing all occurences of approxEqual in Phobos with corresponding calls to isClose; see #7340. Essentially I'm through, but from my first try I remember, that some tests in std.complex failed on 32bit computers, because the calculation of log() is less accurate. I have to experiment a little with the autotesters to get that right but maybe I'll manage to still finish that this year. :-)

After that PR has been accepted, I plan to file another, which deprecates approxEqual and adds a changelog-entry (I actually planed to ask if I should do so, but thanks to your post now I know I should :-) ). OK?

[jondegenhardt]

CommonDefaultFor needs to be public and documented if it used as the default value in a public API. Currently it has visibility in the math package, not public visibility.

In this case, not having it exposed means that callers cannot provide the default for the maxRelDiff parameter if they only want to change the maxAbsDiff parameter.