Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

perlapi: Combine all sv_catpv() forms into one group #22435

Merged
merged 1 commit into from
Jul 29, 2024
+67 −71
Merged

perlapi: Combine all sv_catpv() forms into one group #22435

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 18 additions & 26 deletions handy.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -389,22 +389,6 @@ a string/length pair.
Like C<newSVpvn_share>, 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<sv_catpvn_flags>, but takes a literal string instead
of a string/length pair.

=for apidoc Am|void|sv_catpvs_nomg|SV* sv|"literal string"
Like C<sv_catpvn_nomg>, but takes a literal string instead of
a string/length pair.

=for apidoc Am|void|sv_catpvs|SV* sv|"literal string"
Like C<sv_catpvn>, but takes a literal string instead of a
string/length pair.

=for apidoc Am|void|sv_catpvs_mg|SV* sv|"literal string"
Like C<sv_catpvn_mg>, 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<sv_setref_pvn>, but takes a literal string instead of
a string/length pair.
Expand Down Expand Up @@ -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))

Expand Down
78 changes: 33 additions & 45 deletions sv.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<len> bytes of the string beginning at C<ptr> onto the
end of the string which is in C<dsv>. The caller must make sure C<ptr>
contains at least C<len> bytes.
These each concatenate a string onto the end of the string which is in C<dsv>.
They differ in how the catenated string is specified and in the handling of
magic and UTF-8ness.

For all but C<sv_catpvn_flags>, 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<pvs> forms, the catenated string is a C language string literal,
enclosed in double quotes.

They differ in that:
In the C<pvn> forms, C<sstr> points to the first byte of the string to
concatenate, and an additional parameter, C<len>, specifies the number of
bytes to copy. Hence, C<sstr> may contain embedded-NUL characters.
The caller must make sure C<sstr> contains at least C<len> bytes.

C<sv_catpvn_mg> performs both 'get' and 'set' magic on C<dsv>.
In the plain C<pv> forms, the catenated string is a C language NUL-terminated
string.

C<sv_catpvn> performs only 'get' magic.
The C<_mg> forms perform both 'get' and 'set' magic on C<dsv>.

C<sv_catpvn_nomg> skips all magic.
The C<_nomg> forms skip all magic.

C<sv_catpvn_flags> has an extra C<flags> parameter which allows you to specify
any combination of magic handling (using C<SV_GMAGIC> and/or C<SV_SMAGIC>) and
to also override the UTF-8 handling. By supplying the C<SV_CATBYTES> flag, the
The other forms perform only 'get' magic.

The C<_flags> forms have an extra parameter, C<flags>, which allows you to also
override the UTF-8 handling. By supplying the C<SV_CATBYTES> flag, the
appended string is interpreted as plain bytes; by supplying instead the
C<SV_CATUTF8> flag, it will be interpreted as UTF-8, and the C<dsv> will be
C<SV_CATUTF8> flag, it will be interpreted as UTF-8, and C<dsv> will be
upgraded to UTF-8 if necessary.

C<sv_catpvn>, C<sv_catpvn_mg>, and C<sv_catpvn_nomg> are implemented
in terms of C<sv_catpvn_flags>.
C<sv_catpvn_nomg_maybeutf8> has an extra boolean parameter, C<is_utf8>, which
if C<true> indicates that C<sstr> 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<dsv> has the UTF-8 status set.

=for apidoc Amnh||SV_CATUTF8
=for apidoc Amnh||SV_CATBYTES
Expand Down Expand Up @@ -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<NUL>-terminated string C<sstr> 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<sv_catpv_mg> performs both 'get' and 'set' magic.

C<sv_catpv> performs only 'get' magic.

C<sv_catpv_nomg> skips all magic.

C<sv_catpv_flags> has an extra C<flags> parameter which allows you to specify
any combination of magic handling (using C<SV_GMAGIC> and/or C<SV_SMAGIC>), and
to also override the UTF-8 handling. By supplying the C<SV_CATUTF8> flag, the
appended string is forced to be interpreted as UTF-8; by supplying instead the
C<SV_CATBYTES> 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)
{
Expand Down
16 changes: 16 additions & 0 deletions sv.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) \
Expand Down Expand Up @@ -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)

Expand Down
Loading