Skip to content

Commit

Permalink
perlapi: Combine all forms of sv_derived_from into one group
Browse files Browse the repository at this point in the history
Having one group containing the descriptions of all closely related
functions makes the pod more compact and makes maintenance easier; fixes
only need to be applied in one place.  And it encourages the
documentation authors to compare and contrast the variants, paying
closer attention to the subtle differences between them.

And it is easier for the reader to choose the variant that is best for
their current purpose, rather than hopping around the file, unsure if
the current text is identical to that found elsewhere, or if there is a
subtle nuance (or three).
derived_from
  • Loading branch information
khwilliamson committed Jun 26, 2024
1 parent f0a6b06 commit 402a017
Showing 1 changed file with 22 additions and 35 deletions.
57 changes: 22 additions & 35 deletions universal.c
Original file line number Diff line number Diff line change
Expand Up @@ -123,20 +123,33 @@ S_sv_derived_from_svpvn(pTHX_ SV *sv, SV *namesv, const char * name, const STRLE
/*
=for apidoc_section $SV
=for apidoc sv_derived_from_pvn
=for apidoc sv_derived_from
=for apidoc_item sv_derived_from_hv
=for apidoc_item sv_derived_from_pv
=for apidoc_item sv_derived_from_pvn
=for apidoc_item sv_derived_from_sv
Returns a boolean indicating whether the SV is derived from the specified class
I<at the C level>. To check derivation at the Perl level, call C<isa()> as a
normal Perl method.
These each return a boolean indicating whether C<sv> is derived from the
specified class I<at the C level>. To check derivation at the Perl level, call
C<isa()> as a normal Perl method.
Currently, the only significant value for C<flags> is SVf_UTF8.
In C<sv_derived_from_hv>, the class name is C<HvNAME(hv)> (which would
presumably represent a stash). Its UTF8ness is C<HvNAMEUTF8(hv)>.
=cut
In C<sv_derived_from> and C<sv_derived_from_pv>, the class name is given by
C<name>, which is a NUL-terminated C string. In C<sv_derived_from>, the name
is never considered to be encoded as UTF-8.
The remaining forms differ only in how the class name is specified;
they all have a C<flags> parameter. Currently, the only significant value for
which is C<SVf_UTF8> to indicate that the class name is encoded as such.
=for apidoc sv_derived_from_sv
In C<sv_derived_from_sv>, the class name is extracted from C<namesv>.
This is the preferred form. The class name is considered to be in UTF-8 if
C<namesv> is marked as such.
Exactly like L</sv_derived_from_pvn>, but takes the name string in the form
of an SV instead of a string/length pair. This is the advised form.
In C<sv_derived_from_pvn>, C<len> gives the length of C<name>, so the latter
may contain embedded NUL characters.
=cut
Expand All @@ -149,30 +162,13 @@ Perl_sv_derived_from_sv(pTHX_ SV *sv, SV *namesv, U32 flags)
return sv_derived_from_svpvn(sv, namesv, NULL, 0, flags);
}

/*
=for apidoc sv_derived_from
Exactly like L</sv_derived_from_pv>, but doesn't take a C<flags> parameter.
=cut
*/

bool
Perl_sv_derived_from(pTHX_ SV *sv, const char *const name)
{
PERL_ARGS_ASSERT_SV_DERIVED_FROM;
return sv_derived_from_svpvn(sv, NULL, name, strlen(name), 0);
}

/*
=for apidoc sv_derived_from_pv
Exactly like L</sv_derived_from_pvn>, but takes a nul-terminated string
instead of a string/length pair.
=cut
*/


bool
Perl_sv_derived_from_pv(pTHX_ SV *sv, const char *const name, U32 flags)
Expand All @@ -188,15 +184,6 @@ Perl_sv_derived_from_pvn(pTHX_ SV *sv, const char *const name, const STRLEN len,
return sv_derived_from_svpvn(sv, NULL, name, len, flags);
}

/*
=for apidoc sv_derived_from_hv
Exactly like L</sv_derived_from_pvn>, but takes the name string as the
C<HvNAME> of the given HV (which would presumably represent a stash).
=cut
*/

bool
Perl_sv_derived_from_hv(pTHX_ SV *sv, HV *hv)
{
Expand Down

0 comments on commit 402a017

Please sign in to comment.