Clarify SvPVbyteFOO docs

These all croak if the SV string is in UTF-8 containing wide characters.

diff --git a/sv.c b/sv.c
index 49ee5cd..a5a3b4a 100644 (file)
--- a/sv.c
+++ b/sv.c
@@ -3308,8 +3308,9 @@ Perl_sv_copypv_flags(pTHX_ SV *const dsv, SV *const ssv, const I32 flags)
 =for apidoc sv_2pvbyte
 
 Return a pointer to the byte-encoded representation of the SV, and set C<*lp>
-to its length.  May cause the SV to be downgraded from UTF-8 as a
-side-effect.
+to its length.  If the SV is marked as being encoded as UTF-8, it will
+downgrade it to a byte string as a side-effect, if possible.  If the SV cannot
+be downgraded, this croaks.
 
 Usually accessed via the C<SvPVbyte> macro.
 
@@ -10146,7 +10147,7 @@ Perl_sv_pvn_force_flags(pTHX_ SV *const sv, STRLEN *const lp, const I32 flags)
 =for apidoc sv_pvbyten_force
 
 The backend for the C<SvPVbytex_force> macro.  Always use the macro
-instead.
+instead.  If the SV cannot be downgraded from UTF-8, this croaks.
 
 =cut
 */

diff --git a/sv.h b/sv.h
index 22e8391..490cab4 100644 (file)
--- a/sv.h
+++ b/sv.h
@@ -1641,10 +1641,12 @@ Like C<SvPVutf8_or_null>, but does not process get magic.
 Like C<SvPV_nolen>, but converts C<sv> to UTF-8 first if necessary.
 
 =for apidoc Am|char*|SvPVbyte_force|SV* sv|STRLEN len
-Like C<SvPV_force>, but converts C<sv> to byte representation first if necessary.
+Like C<SvPV_force>, but converts C<sv> to byte representation first if
+necessary.  If the SV cannot be downgraded from UTF-8, this croaks.
 
 =for apidoc Am|char*|SvPVbyte|SV* sv|STRLEN len
-Like C<SvPV>, but converts C<sv> to byte representation first if necessary.
+Like C<SvPV>, but converts C<sv> to byte representation first if necessary.  If
+the SV cannot be downgraded from UTF-8, this croaks.
 
 =for apidoc Am|char*|SvPVbyte_nomg|SV* sv|STRLEN len
 Like C<SvPVbyte>, but does not process get magic.
@@ -1656,7 +1658,8 @@ Like C<SvPVbyte>, but when C<sv> is undef, returns C<NULL>.
 Like C<SvPVbyte_or_null>, but does not process get magic.
 
 =for apidoc Am|char*|SvPVbyte_nolen|SV* sv
-Like C<SvPV_nolen>, but converts C<sv> to byte representation first if necessary.
+Like C<SvPV_nolen>, but converts C<sv> to byte representation first if
+necessary.  If the SV cannot be downgraded from UTF-8, this croaks.
 
 =for apidoc Am|char*|SvPVutf8x_force|SV* sv|STRLEN len
 Like C<SvPV_force>, but converts C<sv> to UTF-8 first if necessary.
@@ -1671,12 +1674,12 @@ otherwise.
 =for apidoc Am|char*|SvPVbytex_force|SV* sv|STRLEN len
 Like C<SvPV_force>, but converts C<sv> to byte representation first if necessary.
 Guarantees to evaluate C<sv> only once; use the more efficient C<SvPVbyte_force>
-otherwise.
+otherwise.  If the SV cannot be downgraded from UTF-8, this croaks.
 
 =for apidoc Am|char*|SvPVbytex|SV* sv|STRLEN len
 Like C<SvPV>, but converts C<sv> to byte representation first if necessary.
 Guarantees to evaluate C<sv> only once; use the more efficient C<SvPVbyte>
-otherwise.
+otherwise.  If the SV cannot be downgraded from UTF-8, this croaks.
 
 =for apidoc Am|U32|SvIsCOW|SV* sv
 Returns a U32 value indicating whether the SV is Copy-On-Write (either shared