Apify SV_CATBYTES and SV_CATUTF8

When I added them I was not sure at the time whether they would be
stable or whether they might need to be changed.  They seem pretty
stable now, and they are extremely useful, so make them part
of the API.

1 files changed, 8 insertions, 2 deletions

diff --git a/sv.c b/sv.c
index cd77099af4..8f46c19e9a 100644
--- a/sv.c
+++ b/sv.c
@@ -5387,8 +5387,14 @@ Handles 'get' magic, but not 'set' magic.  See C<sv_catpvn_mg>.
 =for apidoc sv_catpvn_flags
 
 Concatenates the string onto the end of the string which is in the SV.  The
-C<len> indicates number of bytes to copy.  If the SV has the UTF-8
-status set, then the bytes appended should be valid UTF-8.
+C<len> indicates number of bytes to copy.
+
+By default, the string appended is assumed to be valid UTF-8 if the SV has
+the UTF-8 status set, and a string of bytes otherwise.  One can force the
+appended string to be interpreted as UTF-8 by supplying the C<SV_CATUTF8>
+flag, and as bytes by supplying the C<SV_CATBYTES> flag; the SV or the
+string appended will be upgraded to UTF-8 if necessary.
+
 If C<flags> has the C<SV_SMAGIC> bit set, will
 C<mg_set> on C<dsv> afterwards if appropriate.
 C<sv_catpvn> and C<sv_catpvn_nomg> are implemented