Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
corrections, improvements, notes modified or added, unimplemented fea… 
…tures marked NYI (after testing on late model rakudo)
  • Loading branch information
@tbrowder
tbrowder committed Aug 31, 2016
1 parent 8cfffc2 commit 8acb21b
Showing 1 changed file with 42 additions and 41 deletions.
83 changes: 42 additions & 41 deletions doc/Type/Str.pod6
View file
Expand Up @@ -339,10 +339,10 @@ Directives guide the use (if any) of the arguments. When a directive
(other than C<%>) is used, it indicates how the next argument
passed is to be formatted into the string to be created.
NOTE: The information below is for a fully functioning C<sprintf> implementation which hasn't been
achieved yet due, in part, to Rakudo issues with native uint64 types. The following section will
be annotated to indicate what parts do NOT yet work properly after a thorough test is made of
each example below.
NOTE: The information below is for a fully functioning C<sprintf>
implementation which hasn't been achieved yet due, in part, to Rakudo
issues with native uint64 types. Formats or features not yet
implemented are marked NYI.
The directives are:
Expand Down Expand Up @@ -392,10 +392,10 @@ no-ops (the semantics are still being determined).
=begin table
h interpret integer as native "short" (typically int16)
l interpret integer as native "long" (typically int32 or int64)
ll interpret integer as native "long long" (typically int64)
L interpret integer as native "long long" (typically uint64)
q interpret integer as native "quads" (typically int64 or larger)
NYI l interpret integer as native "long" (typically int32 or int64)
NYI ll interpret integer as native "long long" (typically int64)
NYI L interpret integer as native "long long" (typically uint64)
NYI q interpret integer as native "quads" (typically int64 or larger)
=end table
Expand All @@ -419,7 +419,7 @@ One or more of:
space prefix non-negative number with a space
+ prefix non-negative number with a plus sign
- left-justify within the field
0 use zeros, not spaces, to right-justify
0 use leading zeros, not spaces, for required padding
# ensure the leading "0" for any octal,
prefix non-zero hexadecimal with "0x" or "0X",
prefix non-zero binary with "0b" or "0B"
Expand Down Expand Up @@ -450,9 +450,9 @@ is ignored:
When the C<#> flag and a precision are given in the C<%o> conversion, the
precision is incremented if it's necessary for the leading "0":
sprintf '<%#.5o>', 012; # "<00012>"
sprintf '<%#.5o>', 012; # "<000012>"
sprintf '<%#.5o>', 012345; # "<012345>"
sprintf '<%#.0o>', 0; # "<0>"
sprintf '<%#.0o>', 0; # "<>" # zero precision results in no output!
=head3 vector flag
Expand All @@ -462,13 +462,13 @@ format to each integer in turn, then joins the resulting strings with
a separator (a dot, C<'.'>, by default). This can be useful for
displaying ordinal values of characters in arbitrary strings:
sprintf "%vd", "AB\x{100}"; # "65.66.256"
sprintf "version is v%vd\n", $^V; # Perl 6's version
NYI sprintf "%vd", "AB\x{100}"; # "65.66.256"
NYI sprintf "version is v%vd\n", $^V; # Perl 6's version
You can also explicitly specify the argument number to use for the
join string using something like C<*2$v>; for example:
sprintf '%*4$vX %*4$vX %*4$vX', # 3 IPv6 addresses
NYI sprintf '%*4$vX %*4$vX %*4$vX', # 3 IPv6 addresses
@addr[1..3], ":";
=head3 (minimum) width
Expand All @@ -478,11 +478,11 @@ 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 (e.g., with C<*2$>):
sprintf "<%s>", "a"; # "<a>"
sprintf "<%6s>", "a"; # "< a>"
sprintf "<%*s>", 6, "a"; # "< a>"
sprintf '<%*2$s>', "a", 6; # "< a>"
sprintf "<%2s>", "long"; # "<long>" (does not truncate)
sprintf "<%s>", "a"; # "<a>"
sprintf "<%6s>", "a"; # "< a>"
sprintf "<%*s>", 6, "a"; # "< a>"
NYI sprintf '<%*2$s>', "a", 6; # "< a>"
sprintf "<%2s>", "long"; # "<long>" (does not truncate)
If a field width obtained through C<*> is negative, it has the same
effect as the C<-> flag: left-justification.
Expand Down Expand Up @@ -519,12 +519,15 @@ For integer conversions, specifying a precision implies that the
output of the number itself should be zero-padded to this width, where
the C<0> flag is ignored:
sprintf '<%.6d>', 1; # "<000001>"
sprintf '<%+.6d>', 1; # "<+000001>"
sprintf '<%-10.6d>', 1; # "<000001 >"
sprintf '<%10.6d>', 1; # "< 000001>"
sprintf '<%010.6d>', 1; # "< 000001>"
sprintf '<%+10.6d>', 1; # "< +000001>"
(Note that this feature currenly works for unsigned integer conversions, but not
for signed integer.)
NYI sprintf '<%.6d>', 1; # "<000001>"
NYI sprintf '<%+.6d>', 1; # "<+000001>"
NYI sprintf '<%-10.6d>', 1; # "<000001 >"
NYI sprintf '<%10.6d>', 1; # "< 000001>"
NYI sprintf '<%010.6d>', 1; # "< 000001>"
NYI sprintf '<%+10.6d>', 1; # "< +000001>"
sprintf '<%.6x>', 1; # "<000001>"
sprintf '<%#.6x>', 1; # "<0x000001>"
sprintf '<%-10.6x>', 1; # "<000001 >"
Expand All @@ -543,8 +546,8 @@ from a specified argument (e.g., with C<.*2$>):
sprintf '<%.6x>', 1; # "<000001>"
sprintf '<%.*x>', 6, 1; # "<000001>"
sprintf '<%.*2$x>', 1, 6; # "<000001>"
sprintf '<%6.*2$x>', 1, 4; # "< 0001>"
NYI sprintf '<%.*2$x>', 1, 6; # "<000001>"
NYI sprintf '<%6.*2$x>', 1, 4; # "< 0001>"
If a precision obtained through C<*> is negative, it counts as having
no precision at all:
Expand All @@ -567,6 +570,8 @@ 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 6:
(Note: None of the following have been implemented.)
hh interpret integer as C type "char" or "unsigned
char"
h interpret integer as C type "short" or
Expand Down Expand Up @@ -594,12 +599,13 @@ the next argument.
So:
sprintf "<%*.*s>", $a, $b, $c;
my $a = 5; my $b = 2; my $c = 'net';
sprintf "<%*.*s>", $a, $b, $c; # < ne>
uses C<$a> for the width, C<$b> for the precision, and C<$c> as the value to
format; while:
sprintf '<%*1$.*s>', $a, $b;
NYI sprintf '<%*1$.*s>', $b, 'b';
would use C<$a> for the width and precision and C<$b> as the value to format.
Expand All @@ -609,21 +615,16 @@ index, the C<$> may need escaping:
sprintf "%2\$d %d\n", 12, 34; # "34 12\n"
sprintf "%2\$d %d %d\n", 12, 34; # "34 12 34\n"
sprintf "%3\$d %d %d\n", 12, 34, 56; # "56 12 34\n"
sprintf "%2\$*3\$d %d\n", 12, 34, 3; # " 34 12\n"
sprintf "%*1\$.*f\n", 4, 5, 10; # "5.0000\n"
NYI sprintf "%2\$*3\$d %d\n", 12, 34, 3; # " 34 12\n"
NYI sprintf "%*1\$.*f\n", 4, 5, 10; # "5.0000\n"
=comment TODO: document effects of locale
Other examples:
=for code :skip-test
sprintf "%ld a big number, %lld a bigger number\n", 4294967295, 4294967296;
NYI sprintf "%ld a big number", 4294967295;
NYI sprintf "%%lld a bigger number", 4294967296;
sprintf('%c', 97); # a
sprintf("%.2f", 1.969); # 1.97
sprintf("%+.3f", 3.141592); # +3.142
Expand All @@ -634,9 +635,9 @@ Special case: 'sprintf("<b>%s</b>\n", "Perl 6")' will not work, but
one of the following will:
=for code :skip-test
sprintf Q:b "<b>%s</b>\n", "Perl 6";
sprintf "<b>\%s</b>\n", "Perl 6";
sprintf "<b>%s\</b>\n", "Perl 6";
sprintf Q:b "<b>%s</b>\n", "Perl 6"; # "<b>Perl 6</b>\n"
sprintf "<b>\%s</b>\n", "Perl 6"; # "<b>Perl 6</b>\n"
sprintf "<b>%s\</b>\n", "Perl 6"; # "<b>Perl 6</b>\n"
=head2 method starts-with
Expand Down

0 comments on commit 8acb21b

Please sign in to comment.