[skip-ci] clarify behavior and rounding precision limitations of FindBin

[ferdymercury]

This Pull request:

Changes or fixes:

See https://root-forum.cern.ch/t/bug-or-feature-in-ttree-draw/62862/16

Related: #17689

[guitargeek]

Does this maybe interfere with #14105, where I have made some suggestions to improve the numerical stability of FindBin()? That PR is kind of stuck, because then we would also have to improve other functions like GetBinLowEdge and GetBinHighEdge to be consistent. And changing the numeric behavior is always a risk for backwards compatibility, even if it goes in the right direction :|

We need to check whether the example TAxis(1, -1., 0.).FindBin(-1e-17) still wrongly returns the overflow bin even with the other PR merged. Thank we can merge this PR without having to worry that it gets invalidated by #14105.

[ferdymercury]

Thanks for the feedback!

We need to check whether the example TAxis(1, -1., 0.).FindBin(-1e-17) still wrongly returns the overflow bin even with the other PR merged.

I checked with that PR you have mentioned, and it still returns the wrong bin.
So it does not really interfere with the other pull request. This PR would be just documenting the current (and potentially future) behaviour.

See reproducer with the other PR:

      double x = -1e-17;
      const double fXmin = -1.;
      const double fXmax = 0.;
      const int fNbins = 1;
      // shift x and fXmax by fXmin:
      x = x - fXmin;
      const double b = fXmax - fXmin;
      const double s = fNbins * x; // scaled version of x
      double m = std::floor(s / b);
      // iterative correction in case of floating point errors due to floating point division
      while (m * b > s) // if left bin boundary is greater then x, decrement
         m = m - 1;
      while ((m + 1) * b <= s) //if right bin boundary is smaller or equal, increment
         m = m + 1;
      cout << 1 + Int_t(m) << endl;

If we cast everything to long-double, then the same issue appears a bit later, at -1e-20, both in the current master implementation as well as in the referenced PR.

[guitargeek]

Thanks for the PR and following up to my comment! The PR looks good to me.