Re: sprintf: fix and docs

Message-Id: <200207172236.g6HMaKU16388@crypt.compulink.co.uk>

p4raw-id: //depot/perl@17614

1 files changed, 32 insertions, 1 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 0652b4edbb..40e2dd0491 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -4952,7 +4952,7 @@ the join string using eg C<*2$v>:
 Arguments are usually formatted to be only as wide as required to
 display the given value. You can override the width by putting
 a number here, or get the width from the next argument (with C<*>)
-or from a specified argument (with eg C<2$>):
+or from a specified argument (with eg C<*2$>):
 
   printf '<%s>', "a";       # prints "<a>"
   printf '<%6s>', "a";      # prints "<     a>"
@@ -5025,6 +5025,37 @@ 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.
 
+=item order of arguments
+
+Normally, sprintf takes the next unused argument as the value to
+format for each format specification. If the format specification
+uses C<*> to require additional arguments, these are consumed from
+the argument list in the order in which they appear in the format
+specification I<before> the value to format. Where an argument is
+specified using an explicit index, this does not affect the normal
+order for the arguments (even when the explicitly specified index
+would have been the next argument in any case).
+
+So:
+
+  printf '<%*.*s>', $a, $b, $c;
+
+would use C<$a> for the width, C<$b> for the precision and C<$c>
+as the value to format, while:
+
+  print '<%*1$.*s>', $a, $b;
+
+would use C<$a> for the width and the precision, and C<$b> as the
+value to format.
+
+Here are some more examples - beware that when using an explicit
+index, the C<$> may need to be escaped:
+
+  printf "%2\$d %d\n",    12, 34;		# will print "34 12\n"
+  printf "%2\$d %d %d\n", 12, 34;		# will print "34 12 34\n"
+  printf "%3\$d %d %d\n", 12, 34, 56;		# will print "56 12 34\n"
+  printf "%2\$*3\$d %d\n", 12, 34, 3;		# will print " 34 12\n"
+
 =back
 
 If C<use locale> is in effect, the character used for the decimal