Skip to content
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 for Printf's format "%g" looks imprecise or incorrect #7507

Closed
vicuna opened this issue Mar 22, 2017 · 7 comments
Closed

Documentation for Printf's format "%g" looks imprecise or incorrect #7507

vicuna opened this issue Mar 22, 2017 · 7 comments
Assignees

Comments

@vicuna
Copy link

vicuna commented Mar 22, 2017

Original bug ID: 7507
Reporter: @Armael
Assigned to: @Octachron
Status: resolved (set by @Octachron on 2017-05-08T21:18:54Z)
Resolution: fixed
Priority: normal
Severity: minor
Fixed in version: 4.06.0 +dev/beta1/beta2/rc1
Category: documentation

Bug description

In stdlib/printf.mli, the documentation for the %g format states:

  • [g] or [G]: convert a floating-point argument to decimal notation, in style [f] or [e], [E] (whichever is more compact).

However:

  • [Printf.printf "%f" 1.] prints "1.000000"
  • [Printf.printf "%e" 1.] prints "1.000000e+00"
  • [Printf.printf "%g" 1.] prints "1", which corresponds to neither "%f" or "%e".

This seems to indicate that the documentation for %g is quite vague, at best.

@vicuna
Copy link
Author

vicuna commented Mar 22, 2017

Comment author: @gasche

I have bad news for you: OCaml does not implement %g itself, it delegates to the libc's %g format semantics (see: "man 3 printf"). This means that you will get inconsistent results across platforms and that giving a precise and correct specification is unlikely to succeed.

@vicuna
Copy link
Author

vicuna commented Mar 22, 2017

Comment author: @Armael

Could the documentation refer to the libc's semantics, then?

@vicuna
Copy link
Author

vicuna commented Mar 24, 2017

Comment author: @xavierleroy

Quoting from the glibc man pages:

          The  double argument is converted in style f or e (or F or E for
          G conversions).  The precision specifies the number of  signifi?
          cant  digits.   If the precision is missing, 6 digits are given;
          if the precision is zero, it is treated as 1.  Style e  is  used
          if  the  exponent from its conversion is less than -4 or greater
          than or equal to the precision.  Trailing zeros are removed from
          the  fractional part of the result; a decimal point appears only
          if it is followed by at least one digit.

So, the summary in the OCaml documentation is not too bad. If we really want, we could add a sentence about trailing zeros possibly removed.

@vicuna
Copy link
Author

vicuna commented Mar 24, 2017

Comment author: @Octachron

Reading the OCaml documentation, I would think that the most surprising part is the elision of the decimal point which does happen for neither %f, %e or %E. Should I document this point?

@vicuna
Copy link
Author

vicuna commented Mar 24, 2017

Comment author: @gasche

Follow your heart.

@vicuna
Copy link
Author

vicuna commented May 8, 2017

Comment author: @Octachron

The corresponding github PR, directly inspired from the C90 standard description, is here #1163 .

Armael, do you wish to be cited in the changelog?

@vicuna
Copy link
Author

vicuna commented May 8, 2017

Comment author: @Armael

No, don't bother. Thanks for taking care of this!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants