From: Chip Salzenberg Date: Wed, 23 Apr 1997 23:48:51 +0000 (+1200) Subject: Document new {,s}printf() behavior X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=74a7701791a30556a92328b89e5a00414a4ce4a3;p=p5sagit%2Fp5-mst-13.2.git Document new {,s}printf() behavior --- diff --git a/pod/perldelta.pod b/pod/perldelta.pod index 70d2216..178812d 100644 --- a/pod/perldelta.pod +++ b/pod/perldelta.pod @@ -238,9 +238,32 @@ emulating, and always flushes before (un)locking. =item printf and sprintf -now support "%i" as a synonym for "%d", and the "h" modifier. -So "%hi" means "short integer in decimal", and "%ho" means -"unsigned short integer as octal". +Perl now implements these functions itself; it doesn't use the C +library function sprintf() any more, except for floating-point +numbers, and even then only known flags are allowed. As a result, it +is now possible to know which conversions and flags will work, and +what they will do. + +The new conversions in Perl's sprintf() are: + + %i a synonym for %d + %p a pointer (the address of the Perl value, in hexadecimal) + %n special: B into the next variable in the parameter + list the number of characters printed so far + +The new flags that go between the C<%> and the conversion are: + + # prefix octal with "0", hex with "0x" + h interpret integer as C type "short" or "unsigned short" + V interpret integer as Perl's standard integer type + +Also, where a number would appear in the flags, an asterisk ("*") may +be used instead, in which case Perl uses the next item in the +parameter list as the given number (that is, as the field width or +precision). If a field width obtained through "*" is negative, it has +the same effect as the '-' flag: left-justification. + +See L for a complete list of conversion and flags. =item keys as an lvalue diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 51de42b..913f6f8 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -3090,15 +3090,77 @@ L, and L.) =item sprintf FORMAT, LIST -Returns a string formatted by the usual printf conventions of the C -language. See L or L on your system for details. -(The * character for an indirectly specified length is not -supported, but you can get the same effect by interpolating a variable -into the pattern.) If C is -in effect, the character used for the decimal point in formatted real numbers -is affected by the LC_NUMERIC locale. See L. -Some C libraries' implementations of sprintf() can -dump core when fed ludicrous arguments. +Returns a string formatted by the usual printf conventions of the +C library function sprintf(). See L or L +on your system for an explanation of the general principles. + +Perl does all of its own sprintf() formatting -- it emulates the C +function sprintf(), but it doesn't use it (except for floating-point +numbers, and even then only the standard modifiers are allowed). As a +result, any non-standard extensions in your local sprintf() are not +available from Perl. + +Perl's sprintf() permits the following universally-known conversions: + + %% a percent sign + %c a character with the given number + %s a string + %d a signed integer, in decimal + %u an unsigned integer, in decimal + %o an unsigned integer, in octal + %x an unsigned integer, in hexadecimal + %e a floating-point number, in scientific notation + %f a floating-point number, in fixed decimal notation + %g a floating-point number, in %e or %f notation + +In addition, Perl permits the following ANSI-invented conversions: + + %i a synonym for %d + %X like %x, but using upper-case letters + %E like %e, but using an upper-case "E" + %G like %g, but with an upper-case "E" (if applicable) + %p a pointer (outputs the Perl value's address in hexadecimal) + %n special: B into the next variable in the parameter + list the number of characters printed so far + +Finally, for backward (and we do mean "backward") compatibility, +Perl permits these nonstandard but unaccountably popular conversions: + + %D a synonym for %ld + %U a synonym for %lu + %O a synonym for %lo + %F a synonym for %f + +Perl permits the following universally-known flags between the C<%> +and the conversion letter: + + space prefix positive number with a space + + prefix positive number with a plus sign + - left-justify within the field + 0 use zeros, not spaces, to right-justify + number minimum field width + .number "precision": digits after decimal point for floating-point, + max length for string, minimum length for integer + l interpret integer as C type "long" or "unsigned long" + +In addition, Perl permits the following ANSI-invented flags: + + # prefix octal with "0", hex with "0x" + h interpret integer as C type "short" or "unsigned short" + +Finally, there is one Perl-specific flag: + + V interpret integer as Perl's standard integer type + +Where a number would appear in the flags, an asterisk ("*") may be +used instead, in which case Perl uses the next item in the parameter +list as the given number (that is, as the field width or precision). +If a field width obtained through "*" is negative, it has the same +effect as the '-' flag: left-justification. + +If C is in effect, the character used for the decimal +point in formatted real numbers is affected by the LC_NUMERIC locale. +See L. =item sqrt EXPR