[perl #17075] sprintf: '%.[num](g|G)' documentation incorrect
Allen Smith
> # New Ticket Created by Allen Smith
> # Please include the string: [perl #17075]
> # in the subject line of all future correspondence about this issue.
> # <URL: http://rt.perl.org/rt2/Ticket/Display.html?id=17075 >
>
> sprintf perlfunc.pod documentation (Perl-6.9.0 patch # 17875):
That should, of course, be 5.9.0...
> %g a floating-point number, in %e or %f notation
>
> [...]
>
> =item precision, or maximum width
[...]
> Either the documentation or the code needs to be corrected.
I am, incidentally, guessing that the documentation is probably what people
will want changed. However, this is still something to keep in mind if one
wishes to, say, increase the standardization of 'g|G' going to 'e|E' across
different machines (I would not be surprised if the rules for it were
different on Windows, VMS, etcetera).
-Allen
--
Allen Smith http://cesario.rutgers.edu/easmith/
September 11, 2001 A Day That Shall Live In Infamy II
"They that can give up essential liberty to obtain a little temporary
safety deserve neither liberty nor safety." - Benjamin Franklin
Allen Smith
# Please include the string: [perl #17075]
# in the subject line of all future correspondence about this issue.
# <URL: http://rt.perl.org/rt2/Ticket/Display.html?id=17075 >
sprintf perlfunc.pod documentation (Perl-6.9.0 patch # 17875):
%g a floating-point number, in %e or %f notation
[...]
=item precision, or maximum width
You can specify a precision (for numeric conversions) or a maximum
width (for string conversions) by specifying a C<.> followed by a number.
For floating point formats, this specifies the number of decimal places
to show (the default being 6), eg:
# these examples are subject to system-specific variation
printf '<%f>', 1; # prints "<1.000000>"
printf '<%.1f>', 1; # prints "<1.0>"
printf '<%.0f>', 1; # prints "<1>"
printf '<%e>', 10; # prints "<1.000000e+01>"
printf '<%.1e>', 10; # prints "<1.0e+01>"
However, '%.[num](g|G)' converts into the same thing for c's sprintf, and:
.prec An optional entry that consists of a period (.) followed by either
zero or more decimal digits, or an asterisk (*), or an asterisk
followed by one or more decimal digits and a $. It specifies the
minimum number of digits to appear for the d, i, o, u, x, and X
conversions, the number of digits to appear after the decimal-point
character for the b, B, e, E, and f conversions, the maximum number
of significant digits for the g and G conversions, or the maximum
number of characters to be written from a string for an s
conversion. For other conversions, the behavior is undefined. If
only a period is specified, the precision is taken as zero.
from the IRIX manpage on sprintf. The ANSI C standard (according to
http://www.thinkage.ca/english/gcos/expl/c/lib/printf.html) states:
The Precision Field
The precision field is a dot '.' followed by a non-negative decimal
integer. Its meaning depends on the "type" field as given below.
* If the "type" is 'd', 'o', 'u', 'x' or 'X', the precision number is
the smallest number of digits that may appear in the output value. If
necessary, the number will be padded on the left with leading
zeros. If the precision number is 0 or the field is just a '.' with
no number following, an output value of 0 will result in no
characters being printed.
* If the "type" is 'e', 'E', or 'f', the precision number is the number
of digits printed after the decimal point. If the precision number is
0 or the field is just a '.' with no number following, no decimal
point is printed.
* If the "type" is 'g' or 'G', the precision number is the maximum
number of significant digits to be printed. If no precision field is
specified, six significant digits are printed.
* If the "type" is 's', the precision number gives the maximum number
of characters to be printed.
* If the "type" is an 'h', 'hh', 'l' or 'L' type, the precision field
has the same effect as it has for the type without the 'h', 'hh', 'l'
or 'L'.
* If the "type" is '_e', '_E', '_f', or '_F', the precision number is
the number of digits printed after the decimal point. If no precision
is specified, the width will dictate the precision. If no width is
specified either, the value will be printed to full precision.
* If the "type" is '_g' or '_G', the precision is the maximum number of
significant digits to be printed. If no precision field is specified,
all significant digits are printed.
Either the documentation or the code needs to be corrected.
-Allen
h...@crypt.org
: * If the "type" is 'g' or 'G', the precision number is the maximum
: number of significant digits to be printed. If no precision field is
: specified, six significant digits are printed.
:Either the documentation or the code needs to be corrected.
I think the documentation is simply wrong. Patches welcome. :)
Hugo
Allen Smith
Umm... yes.
> Patches welcome. :)
I hope the below looks OK... I think I managed to compact the information
together without losing clarity, but would like feedback from people who
aren't native readers of English on how clear it is.
-Allen
--- perlfunc.pod.old Fri Aug 30 17:10:09 2002
+++ perlfunc.pod Mon Sep 9 17:06:21 2002
@@ -4973,8 +4973,8 @@
You can specify a precision (for numeric conversions) or a maximum
width (for string conversions) by specifying a C<.> followed by a number.
-For floating point formats, this specifies the number of decimal places
-to show (the default being 6), eg:
+For floating point formats, with the exception of 'g' and 'G', this specifies
+the number of decimal places to show (the default being 6), eg:
# these examples are subject to system-specific variation
printf '<%f>', 1; # prints "<1.000000>"
@@ -4983,6 +4983,18 @@
printf '<%e>', 10; # prints "<1.000000e+01>"
printf '<%.1e>', 10; # prints "<1.0e+01>"
+For 'g' and 'G', this specifies the maximum number of digits to show,
+including prior to the decimal point as well as after it, eg:
+
+ # these examples are subject to system-specific variation
+ printf '<%g>', 1; # prints "<1>"
+ printf '<%.10g>', 1; # prints "<1>"
+ printf '<%g>', 100; # prints "<100>"
+ printf '<%.1g>', 100; # prints "<1e+02>"
+ printf '<%.2g>', 100.01; # prints "<1e+02>"
+ printf '<%.5g>', 100.01; # prints "<100.01>"
+ printf '<%.4g>', 100.01; # prints "<100>"
+
For integer conversions, specifying a precision implies that the
output of the number itself should be zero-padded to this width:
@@ -5010,23 +5022,49 @@
=item size
For numeric conversions, you can specify the size to interpret the
-number as using C<l>, C<h>, C<V>, C<q>, C<L> or C<ll>. For integer
-conversions, numbers are usually assumed to be whatever the default
-integer size is on your platform (usually 32 or 64 bits), but you
-can override this to use instead one of the standard C types, as
-supported by the compiler used to build Perl:
+number as using C<l>, C<h>, C<V>, C<q>, C<L>, or C<ll>. For integer
+conversions (C<d u o x X b i D U O>), numbers are usually assumed to be
+whatever the default integer size is on your platform (usually 32 or 64
+bits), but you can override this to use instead one of the standard C types,
+as supported by the compiler used to build Perl:
l interpret integer as C type "long" or "unsigned long"
h interpret integer as C type "short" or "unsigned short"
- q, L or ll interpret integer as C type "long long" or "unsigned long long"
- (if your platform supports such a type, else it is an error)
+ q, L or ll interpret integer as C type "long long", "unsigned long long".
+ or "quads" (typically 64-bit integers)
-For floating point conversions, numbers are usually assumed to be
-the default floating point size on your platform (double or long double),
-but you can force 'long double' with C<q>, C<L> or C<ll> if your
-platform supports them.
+The last will produce errors if Perl does not understand "quads" in your
+installation. (This requires that either the platform natively supports quads
+or Perl was specifically compiled to support quads.) You can find out
+whether your Perl supports quads via L<Config>:
-The size specifier 'V' has no effect for Perl code, but it supported
+ use Config;
+ ($Config{use64bitint} eq 'define' || $Config{longsize} >= 8) &&
+ print "quads\n";
+
+For floating point conversions (C<e f g E F G>), numbers are usually assumed
+to be the default floating point size on your platform (double or long double),
+but you can force 'long double' with C<q>, C<L>, or C<ll> if your
+platform supports them. You can find out whether your Perl supports long
+doubles via L<Config>:
+
+ use Config;
+ $Config{d_longdbl} eq 'define' && print "long doubles\n";
+
+You can find out whether Perl considers 'long double' to be the default
+floating point size to use on your platform via L<Config>:
+
+ use Config;
+ ($Config{uselongdouble} eq 'define') &&
+ print "long doubles by default\n";
+
+It can also be the case that long doubles and doubles are the same thing:
+
+ use Config;
+ ($Config{doublesize} == $Config{longdblsize}) &&
+ print "doubles are long doubles\n";
+
+The size specifier C<V> has no effect for Perl code, but it is supported
for compatibility with XS code; it means 'use the standard size for
a Perl integer (or floating-point number)', which is already the
default for Perl code.
@@ -5067,44 +5105,6 @@
If C<use locale> is in effect, the character used for the decimal
point in formatted real numbers is affected by the LC_NUMERIC locale.
See L<perllocale>.
-
-If Perl understands "quads" (64-bit integers) (this requires
-either that the platform natively support quads or that Perl
-be specifically compiled to support quads), the characters
-
- d u o x X b i D U O
-
-print quads, and they may optionally be preceded by
-
- ll L q
-
-For example
-
- %lld %16LX %qo
-
-You can find out whether your Perl supports quads via L<Config>:
-
- use Config;
- ($Config{use64bitint} eq 'define' || $Config{longsize} == 8) &&
- print "quads\n";
-
-If Perl understands "long doubles" (this requires that the platform
-support long doubles), the flags
-
- e f g E F G
-
-may optionally be preceded by
-
- ll L
-
-For example
-
- %llf %Lg
-
-You can find out whether your Perl supports long doubles via L<Config>:
-
- use Config;
- $Config{d_longdbl} eq 'define' && print "long doubles\n";
=item sqrt EXPR
Rafael Garcia-Suarez
> I hope the below looks OK... I think I managed to compact the information
> together without losing clarity, but would like feedback from people who
> aren't native readers of English on how clear it is.
I can understand it ;-)
> --- perlfunc.pod.old Fri Aug 30 17:10:09 2002
> +++ perlfunc.pod Mon Sep 9 17:06:21 2002
[...]
> +platform supports them. You can find out whether your Perl supports long
> +doubles via L<Config>:
> +
> + use Config;
> + $Config{d_longdbl} eq 'define' && print "long doubles\n";
For this kind of examples, I tend to prefer the command-line version
perl -V:d_longdbl
but this may be less clear.
Allen Smith
> Allen Smith wrote:
> > I hope the below looks OK... I think I managed to compact the information
> > together without losing clarity, but would like feedback from people who
> > aren't native readers of English on how clear it is.
>
> I can understand it ;-)
Good :-} although perhaps p5p is not quite the right place to ask given
likely background knowledge of respondents...
> > --- perlfunc.pod.old Fri Aug 30 17:10:09 2002
> > +++ perlfunc.pod Mon Sep 9 17:06:21 2002
> [...]
> > +platform supports them. You can find out whether your Perl supports long
> > +doubles via L<Config>:
> > +
> > + use Config;
> > + $Config{d_longdbl} eq 'define' && print "long doubles\n";
>
> For this kind of examples, I tend to prefer the command-line version
> perl -V:d_longdbl
> but this may be less clear.
I was mainly copying what was done before; on the simple "is it defined or
not" tests, I'm happy with it either way. Anyone have a strong opinion on
the subject (with reasons, please!)?
-Allen
h...@crypt.org
:--- perlfunc.pod.old Fri Aug 30 17:10:09 2002
:+++ perlfunc.pod Mon Sep 9 17:06:21 2002
:@@ -4973,8 +4973,8 @@
:
: You can specify a precision (for numeric conversions) or a maximum
: width (for string conversions) by specifying a C<.> followed by a number.
:-For floating point formats, this specifies the number of decimal places
:-to show (the default being 6), eg:
:+For floating point formats, with the exception of 'g' and 'G', this specifies
:+the number of decimal places to show (the default being 6), eg:
If I've read things right, the original needs more correction than that:
[eEgG] all specify the number of significant digits, only [fF] specify
the number of decimal places. So for [eE], the precision always specifies
one more than the number of decimal places.
:-The size specifier 'V' has no effect for Perl code, but it supported
:+ use Config;
:+ ($Config{use64bitint} eq 'define' || $Config{longsize} >= 8) &&
:+ print "quads\n";
I notice we have a 'd_longlong' as well; I think this should be shown
(as a parallel to the 'd_longdbl' referred to below) to determine
whether the system is capable of handling quads. The use of 'longsize'
above seems wrong - that describes the size of a (long), not of a
(long long).
Hugo
Nicholas Clark
> "Allen Smith" <eas...@beatrice.rutgers.edu> wrote:
> :-The size specifier 'V' has no effect for Perl code, but it supported
> :+ use Config;
> :+ ($Config{use64bitint} eq 'define' || $Config{longsize} >= 8) &&
> :+ print "quads\n";
>
> I notice we have a 'd_longlong' as well; I think this should be shown
> (as a parallel to the 'd_longdbl' referred to below) to determine
> whether the system is capable of handling quads. The use of 'longsize'
> above seems wrong - that describes the size of a (long), not of a
> (long long).
IIRC on an alpha sizeof(long) is 8, so there is (or should be quad) support
even when long long isn't used. Based on what Jarkko has said, I don't think
it will matter on an alpha because the common compiler also provides long long
(also 8 bytes) but a strict C89 compiler on such a platform (Cray?) may well
not provide long long (but have an 8 byte long)
So possibly we need both.
Nicholas Clark
--
Even better than the real thing: http://nms-cgi.sourceforge.net/
Allen Smith
> On Sat, Sep 14, 2002 at 12:45:38PM +0200, h...@crypt.org wrote:
> > "Allen Smith" <eas...@beatrice.rutgers.edu> wrote:
>
> > :-The size specifier 'V' has no effect for Perl code, but it supported
> > :+ use Config;
> > :+ ($Config{use64bitint} eq 'define' || $Config{longsize} >= 8) &&
> > :+ print "quads\n";
> >
> > I notice we have a 'd_longlong' as well; I think this should be shown
> > (as a parallel to the 'd_longdbl' referred to below) to determine
> > whether the system is capable of handling quads. The use of 'longsize'
> > above seems wrong - that describes the size of a (long), not of a
> > (long long).
>
> IIRC on an alpha sizeof(long) is 8, so there is (or should be quad)
> support even when long long isn't used. Based on what Jarkko has said, I
> don't think it will matter on an alpha because the common compiler also
> provides long long (also 8 bytes)
True. This is the same on IRIX with cc -64.
> but a strict C89 compiler on such a platform (Cray?) may well
> not provide long long (but have an 8 byte long)
Yes. IRIX's compiler is capable of being told to compile in -ansi mode,
which will result in problems with 'long long' - both warnings and, more
importantly, that __int64_t and __uint64_t are structs, not long longs.
> So possibly we need both.
Looks that way. How about:
if ($Config{use64bitint} eq 'define' || $Config{longsize} >= 8 ||
($Config{d_longlong} eq 'define' &&
$Config{longlongsize} >= 8)) {
or something like that?
-Allen
Allen Smith
> "Allen Smith" <eas...@beatrice.rutgers.edu> wrote:
> :--- perlfunc.pod.old Fri Aug 30 17:10:09 2002
> :+++ perlfunc.pod Mon Sep 9 17:06:21 2002
> :@@ -4973,8 +4973,8 @@
> :
> : You can specify a precision (for numeric conversions) or a maximum
> : width (for string conversions) by specifying a C<.> followed by a number.
> :-For floating point formats, this specifies the number of decimal places
> :-to show (the default being 6), eg:
> :+For floating point formats, with the exception of 'g' and 'G', this specifies
> :+the number of decimal places to show (the default being 6), eg:
>
> If I've read things right, the original needs more correction than that:
> [eEgG] all specify the number of significant digits,
Urr... if that's what you've read, then this may depend on the C library
implementing sprintf:
.prec An optional entry that consists of a period (.) followed by either
zero or more decimal digits, or an asterisk (*), or an asterisk
followed by one or more decimal digits and a $. It specifies the
minimum number of digits to appear for the d, i, o, u, x, and X
conversions, the number of digits to appear after the decimal-point
character for the b, B, e, E, and f conversions, the maximum number
of significant digits for the g and G conversions, or the maximum
number of characters to be written from a string for an s
conversion. For other conversions, the behavior is undefined. If
only a period is specified, the precision is taken as zero.
What do other manpages say?
Benjamin Goldberg
[snip]
> if ($Config{use64bitint} eq 'define' || $Config{longsize} >= 8 ||
> ($Config{d_longlong} eq 'define' &&
> $Config{longlongsize} >= 8)) {
>
> or something like that?
I haven't been closely following this thread, so I'm not *entirely* sure
what's being tested for :) but would the following work?
if( eval { pack 'Q' } ) {
Just a guess.
--
Announcement in the Zoo:
"Please don't scare the ostriches! Cement floor!"
h...@crypt.org
:> If I've read things right, the original needs more correction than that:
:> [eEgG] all specify the number of significant digits,
:
:Urr... if that's what you've read, then this may depend on the C library
:implementing sprintf:
Hmm, I thought I'd read that on the manpage under Linux on my home
machine, but checking on my laptop here (OS/X) and on crypt.org (Linux)
they both agree with your original text; I'll check again when I get
back home in a week or so, but I probably simply misread it.
Hugo
h...@crypt.org
Note that we have the 'l' modifier for longs; I think the quad issue
should be relevant for (long long) whatever the size, rather than for
(sizeof(someinttype) > 8) whatever the type. Of course, that may not
conform to our current reality.
Hugo
Nicholas Clark
> Nicholas Clark <ni...@unfortu.net> wrote:
> :IIRC on an alpha sizeof(long) is 8, so there is (or should be quad) support
> :even when long long isn't used. Based on what Jarkko has said, I don't think
> :it will matter on an alpha because the common compiler also provides long long
> :(also 8 bytes) but a strict C89 compiler on such a platform (Cray?) may well
> :not provide long long (but have an 8 byte long)
> :
> :So possibly we need both.
>
> Note that we have the 'l' modifier for longs; I think the quad issue
> should be relevant for (long long) whatever the size, rather than for
> (sizeof(someinttype) > 8) whatever the type. Of course, that may not
> conform to our current reality.
You've been gotcha'd! :-( [It's far far too complex]
l A signed long value.
L An unsigned long value.
(This 'long' is _exactly_ 32 bits, which may differ from
what a local C compiler calls 'long'. If you want
native-length longs, use the '!' suffix.)
I think l!,L! were what you meant to write.
perl6 needs to sort this out, and make distinction between a set for C types,
and particular byte lengths. (possibly with endian choice suffixes, as nN for
16,32 bits contradicts the lL for signed, unsigned). Not that this is on
topic.
I've now lost track of what the original thread was about, and how your
comment follows on from it. Sorry.
Allen Smith
> On Sun, Sep 15, 2002 at 07:35:39AM +0200, h...@crypt.org wrote:
> > Nicholas Clark <ni...@unfortu.net> wrote:
>
> > >IIRC on an alpha sizeof(long) is 8, so there is (or should be quad)
> > >support even when long long isn't used. Based on what Jarkko has said,
> > >I don't think it will matter on an alpha because the common compiler
> > >also provides long long (also 8 bytes) but a strict C89 compiler on
> > >such a platform (Cray?) may well not provide long long (but have an 8
> > >byte long)
> > >
> > >So possibly we need both.
> >
> > Note that we have the 'l' modifier for longs; I think the quad issue
> > should be relevant for (long long) whatever the size, rather than for
> > (sizeof(someinttype) > 8) whatever the type. Of course, that may not
> > conform to our current reality.
>
> You've been gotcha'd! :-( [It's far far too complex]
Yes...
> l A signed long value.
> L An unsigned long value.
> (This 'long' is _exactly_ 32 bits, which may differ from
> what a local C compiler calls 'long'. If you want
> native-length longs, use the '!' suffix.)
>
> I think l!,L! were what you meant to write.
>
> perl6 needs to sort this out, and make distinction between a set for C types,
> and particular byte lengths. (possibly with endian choice suffixes, as nN for
> 16,32 bits contradicts the lL for signed, unsigned).
Yes. There are additional concerns with things like PDL and its PDL_Long
(which is set to be whichever of 'int' and 'long' are 4 bytes), PDL_Short
(automatically 'short' at the moment), etcetera...
> I've now lost track of what the original thread was about, and how your
> comment
That's Hugo's comment?
> follows on from it. Sorry.
The original thread is regarding that the sprintf perlfunc.pod
documentation is incorrect on the interpretation of the precision argument
for [g|G]. In the course of correcting that, I noted that it seemed to
currently be (confusingly) repeating itself twice regarding sizes et al, at
least in the bleadperl version.
h...@crypt.org
:I hope the below looks OK... I think I managed to compact the information
:together without losing clarity, but would like feedback from people who
:aren't native readers of English on how clear it is.
Thanks, applied as #17987, and apologies for the delay.
Nicholas, perhaps you could check over the Config references to see
whether any changes are needed: this is the sprintf section of
perlfunc.pod.
Hugo
Nicholas Clark
I can't see anything wrong with them, and all code runs and produces the
expect results on various different perls
Nicholas Clark