This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlguts: Revise pod of UTF8f
authorKarl Williamson <khw@cpan.org>
Thu, 7 Nov 2019 20:32:18 +0000 (13:32 -0700)
committerKarl Williamson <khw@cpan.org>
Thu, 7 Nov 2019 20:45:31 +0000 (13:45 -0700)
This is really about strings.  SVs are more conveniently printed using
SVf.

pod/perlguts.pod

index b05c424..43aaff5 100644 (file)
@@ -2717,19 +2717,24 @@ whatever the compiler has.
 If you are printing addresses of pointers, use UVxf combined
 with PTR2UV(), do not use %lx or %p.
 
-=head2 Formatted Printing of SvPVs
+=head2 Formatted Printing of Strings
 
 If you just want the bytes printed in a NUL-terminated string, you can
 just use C<%s> (assuming they are all printables).  But if there is a
 possibility the value will be encoded as UTF-8, you should instead use
-the C<UTF8f> format.  And as its parameter, use the C<UTF8fARG()> macro.
-Below is a general example using the SV C<err_msg> which is known to
-contain a string and not need magic handling:
-
- Perl_croak(aTHX_ "This croaked because: %" UTF8f "\n",
-                  UTF8fARG(SvUTF8(err_msg),
-                           SvCUR(err_msg),
-                           SvPVX(err_msg)));
+the C<UTF8f> format.  And as its parameter, use the C<UTF8fARG()> macro:
+
+ chr * msg;
+
+ /* U+2018: \xE2\x80\x98 LEFT SINGLE QUOTATION MARK
+    U+2019: \xE2\x80\x99 RIGHT SINGLE QUOTATION MARK */
+ if (can_utf8)
+   msg = "\xE2\x80\x98Uses fancy quotes\xE2\x80\x99";
+ else
+   msg = "'Uses simple quotes'";
+
+ Perl_croak(aTHX_ "The message is: %" UTF8f "\n",
+                  UTF8fARG(can_utf8, strlen(msg), msg));
 
 The first parameter to C<UTF8fARG> is a boolean: 1 if the string is in
 UTF-8; 0 if bytes.