diff --git a/handy.h b/handy.h index f2f2c12731fb..4ac4dacca45b 100644 --- a/handy.h +++ b/handy.h @@ -389,22 +389,6 @@ a string/length pair. Like C, but takes a literal string instead of a string/length pair and omits the hash parameter. -=for apidoc Am|void|sv_catpvs_flags|SV* sv|"literal string"|I32 flags -Like C, but takes a literal string instead -of a string/length pair. - -=for apidoc Am|void|sv_catpvs_nomg|SV* sv|"literal string" -Like C, but takes a literal string instead of -a string/length pair. - -=for apidoc Am|void|sv_catpvs|SV* sv|"literal string" -Like C, but takes a literal string instead of a -string/length pair. - -=for apidoc Am|void|sv_catpvs_mg|SV* sv|"literal string" -Like C, but takes a literal string instead of a -string/length pair. - =for apidoc Am|SV *|sv_setref_pvs|SV *const rv|const char *const classname|"literal string" Like C, but takes a literal string instead of a string/length pair. @@ -435,16 +419,24 @@ Perl_xxx(aTHX_ ...) form for any API calls where it's used. #define newSVpvs_flags(str,flags) \ Perl_newSVpvn_flags(aTHX_ STR_WITH_LEN(str), flags) #define newSVpvs_share(str) Perl_newSVpvn_share(aTHX_ STR_WITH_LEN(str), 0) -#define sv_catpvs_flags(sv, str, flags) \ - Perl_sv_catpvn_flags(aTHX_ sv, STR_WITH_LEN(str), flags) -#define sv_catpvs_nomg(sv, str) \ - Perl_sv_catpvn_flags(aTHX_ sv, STR_WITH_LEN(str), 0) -#define sv_catpvs(sv, str) \ - Perl_sv_catpvn_flags(aTHX_ sv, STR_WITH_LEN(str), SV_GMAGIC) -#define sv_catpvs_mg(sv, str) \ - Perl_sv_catpvn_flags(aTHX_ sv, STR_WITH_LEN(str), SV_GMAGIC|SV_SMAGIC) -#define sv_setpvs(sv, str) Perl_sv_setpvn(aTHX_ sv, STR_WITH_LEN(str)) -#define sv_setpvs_mg(sv, str) Perl_sv_setpvn_mg(aTHX_ sv, STR_WITH_LEN(str)) + +/* +=for apidoc_defn Am|void|sv_catpvs_flags|SV * const dsv|"literal string"|I32 flags +=for apidoc_defn Am|void|sv_catpvs_nomg|SV * const dsv|"literal string" +=for apidoc_defn Am|void|sv_catpvs|SV * const dsv|"literal string" +=for apidoc_defn Am|void|sv_catpvs_mg|SV * const dsv|"literal string" +=cut +*/ +#define sv_catpvs_flags(dsv, str, flags) \ + Perl_sv_catpvn_flags(aTHX_ dsv, STR_WITH_LEN(str), flags) +#define sv_catpvs_nomg(dsv, str) \ + Perl_sv_catpvn_flags(aTHX_ dsv, STR_WITH_LEN(str), 0) +#define sv_catpvs(dsv, str) \ + Perl_sv_catpvn_flags(aTHX_ dsv, STR_WITH_LEN(str), SV_GMAGIC) +#define sv_catpvs_mg(dsv, str) \ + Perl_sv_catpvn_flags(aTHX_ dsv, STR_WITH_LEN(str), SV_GMAGIC|SV_SMAGIC) +#define sv_setpvs(dsv, str) Perl_sv_setpvn(aTHX_ dsv, STR_WITH_LEN(str)) +#define sv_setpvs_mg(dsv, str) Perl_sv_setpvn_mg(aTHX_ dsv, STR_WITH_LEN(str)) #define sv_setref_pvs(rv, classname, str) \ Perl_sv_setref_pvn(aTHX_ rv, classname, STR_WITH_LEN(str)) diff --git a/sv.c b/sv.c index 6da92cb26d1e..40668b09f760 100644 --- a/sv.c +++ b/sv.c @@ -5605,35 +5605,52 @@ Perl_sv_chop(pTHX_ SV *const sv, const char *const ptr) } /* -=for apidoc sv_catpvn +=for apidoc sv_catpv +=for apidoc_item sv_catpv_flags +=for apidoc_item sv_catpv_mg +=for apidoc_item sv_catpv_nomg +=for apidoc_item sv_catpvn =for apidoc_item sv_catpvn_flags =for apidoc_item sv_catpvn_mg =for apidoc_item sv_catpvn_nomg +=for apidoc_item sv_catpvn_nomg_maybeutf8 +=for apidoc_item sv_catpvs +=for apidoc_item sv_catpvs_flags +=for apidoc_item sv_catpvs_mg +=for apidoc_item sv_catpvs_nomg -These concatenate the C bytes of the string beginning at C onto the -end of the string which is in C. The caller must make sure C -contains at least C bytes. +These each concatenate a string onto the end of the string which is in C. +They differ in how the catenated string is specified and in the handling of +magic and UTF-8ness. -For all but C, 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. +In the C forms, the catenated string is a C language string literal, +enclosed in double quotes. -They differ in that: +In the C forms, C points to the first byte of the string to +concatenate, and an additional parameter, C, specifies the number of +bytes to copy. Hence, C may contain embedded-NUL characters. +The caller must make sure C contains at least C bytes. -C performs both 'get' and 'set' magic on C. +In the plain C forms, the catenated string is a C language NUL-terminated +string. -C performs only 'get' magic. +The C<_mg> forms perform both 'get' and 'set' magic on C. -C skips all magic. +The C<_nomg> forms skip all magic. -C has an extra C parameter which allows you to specify -any combination of magic handling (using C and/or C) and -to also override the UTF-8 handling. By supplying the C flag, the +The other forms perform only 'get' magic. + +The C<_flags> forms have an extra parameter, C, which allows you to also +override the UTF-8 handling. By supplying the C flag, the appended string is interpreted as plain bytes; by supplying instead the -C flag, it will be interpreted as UTF-8, and the C will be +C flag, it will be interpreted as UTF-8, and C will be upgraded to UTF-8 if necessary. -C, C, and C are implemented -in terms of C. +C has an extra boolean parameter, C, which +if C indicates that C is encoded in UTF-8; otherwise not. + +For all other forms, the string appended is assumed to be valid UTF-8 +if and only if the C has the UTF-8 status set. =for apidoc Amnh||SV_CATUTF8 =for apidoc Amnh||SV_CATBYTES @@ -5732,35 +5749,6 @@ Perl_sv_catsv_flags(pTHX_ SV *const dsv, SV *const sstr, const I32 flags) } } -/* -=for apidoc sv_catpv -=for apidoc_item sv_catpv_flags -=for apidoc_item sv_catpv_mg -=for apidoc_item sv_catpv_nomg - -These concatenate the C-terminated string C onto the end of the -string which is in the SV. -If the SV has the UTF-8 status set, then the bytes appended should be -valid UTF-8. - -They differ only in how they handle magic: - -C performs both 'get' and 'set' magic. - -C performs only 'get' magic. - -C skips all magic. - -C has an extra C parameter which allows you to specify -any combination of magic handling (using C and/or C), and -to also override the UTF-8 handling. By supplying the C flag, the -appended string is forced to be interpreted as UTF-8; by supplying instead the -C flag, it will be interpreted as just bytes. Either the SV or -the string appended will be upgraded to UTF-8 if necessary. - -=cut -*/ - void Perl_sv_catpv(pTHX_ SV *const dsv, const char *sstr) { diff --git a/sv.h b/sv.h index b435f44345aa..97c2973e9e0c 100644 --- a/sv.h +++ b/sv.h @@ -2207,6 +2207,14 @@ immediately written again. #define sv_utf8_upgrade_nomg(sv) sv_utf8_upgrade_flags(sv, 0) #define sv_utf8_downgrade(sv, fail_ok) sv_utf8_downgrade_flags(sv, fail_ok, SV_GMAGIC) #define sv_utf8_downgrade_nomg(sv, fail_ok) sv_utf8_downgrade_flags(sv, fail_ok, 0) +/* +=for apidoc_defn Am|void|sv_catpvn_nomg|NN SV * const dsv \ + |NULLOK const char * sstr \ + |const STRLEN len +=for apidoc_defn Am|void|sv_catpv_nomg|NN SV * const dsv \ + |NULLOK const char * sstr +=cut +*/ #define sv_catpvn_nomg(dsv, sstr, slen) sv_catpvn_flags(dsv, sstr, slen, 0) #define sv_catpv_nomg(dsv, sstr) sv_catpv_flags(dsv, sstr, 0) #define sv_setsv(dsv, ssv) \ @@ -2262,6 +2270,14 @@ immediately written again. sv_utf8_upgrade(nsv); \ sv_catsv_nomg(dsv, nsv); \ } STMT_END + +/* +=for apidoc_defn Adm|void|sv_catpvn_nomg_maybeutf8|NN SV * const dsv \ + |NN const char *sstr \ + |const STRLEN len \ + |const I32 flags +=cut +*/ #define sv_catpvn_nomg_maybeutf8(dsv, sstr, len, is_utf8) \ sv_catpvn_flags(dsv, sstr, len, (is_utf8)?SV_CATUTF8:SV_CATBYTES)