sv.h: outdated comment block re: what each SV type can store

[richardleach]

Description

A comment block towards the top of sv.h says:

...
C<SVt_NULL> can only hold undef.  C<SVt_IV> can hold undef, an integer, or a
reference.  (C<SVt_RV> is an alias for C<SVt_IV>, which exists for backward
compatibility.)  C<SVt_NV> can hold any of those or a double.  C<SVt_PV> can only
hold C<undef> or a string.  C<SVt_PVIV> is a superset of C<SVt_PV> and C<SVt_IV>.
C<SVt_PVNV> is similar.  C<SVt_PVMG> can hold anything C<SVt_PVNV> can hold, but it
can, but does not have to, be blessed or magical.

Two things seems amiss when reading that:

1. PVs can hold undef, a string, or a reference. It seems like a simple comment update is needed here?
2. It reads like an NV can hold undef, an integer, a reference, or a double. However, Perl_sv_setsv_flags seems to only account for it holding either undef or a double.

e.g. perl -MDevel::Peek -e 'my $y = 3.3; $y = {}; Dump($y)' reveals that $y is upgraded to a PVNV to store the reference, but if NV's can store references, surely no upgrade should be required?

So I'm unclear here whether the comment block needs updating to match the realities of the implementation, or the implementation needs updating so that NVs actually can store integers and references.

Perl configuration
Applies to blead and at least the past few stable releases.

[jkeenan]

A comment block towards the top of sv.h says:

...
C<SVt_NULL> can only hold undef.  C<SVt_IV> can hold undef, an integer, or a
reference.  (C<SVt_RV> is an alias for C<SVt_IV>, which exists for backward
compatibility.)  C<SVt_NV> can hold any of those or a double.  C<SVt_PV> can only
hold C<undef> or a string.  C<SVt_PVIV> is a superset of C<SVt_PV> and C<SVt_IV>.
C<SVt_PVNV> is similar.  C<SVt_PVMG> can hold anything C<SVt_PVNV> can hold, but it
can, but does not have to, be blessed or magical.

For reference, this starts at line 68 of sv.h:
https://github.com/Perl/perl5/blob/blead/sv.h#L68

[iabyn]

On Fri, Jan 13, 2023 at 12:28:33PM -0800, Richard Leach wrote: Two things seems amiss when reading that: 1. PVs can hold `undef`, a string, or a **reference**. It seems like a simple comment update is needed here?

Agreed, the docs need fixing.

2. It reads like an NV can hold undef, an integer, a reference, or a double. However, `Perl_sv_setsv_flags` seems to only account for it holding either undef or a double. e.g. `perl -MDevel::Peek -e 'my $y = 3.3; $y = {}; Dump($y)'` reveals that `$y` is upgraded to a PVNV to store the reference, but if NV's can store references, surely no upgrade should be required? So I'm unclear here whether the comment block needs updating to match the realities of the implementation, or the implementation needs updating so that NVs actually *can* store integers and references.

In builds where NVSIZE <= IVSIZE: NVs - like IVs - do the bodiless trick, where no SV body is allocated and sv_any instead points back to itself with a suitable offset, so that sv->sv_any->xiv_u.xivu_iv sv->sv_any->xnv_u.xnv_nv both actually end up accessing sv_->sv_u.svu_iv This trick is also used for storing RVs in headless SVt_IVs; but as far as I'm aware, the trick isn't used for storing RVs in headless SVt_NVs; a full PVNV body is allocated. So currently the docs need fixing. The code could probably be updated to do the headless trick for an NV upgraded to ROK, but it seems like a rare use case and probably not worth the trouble.

…

-- The Enterprise's efficient long-range scanners detect a temporal vortex distortion in good time, allowing it to be safely avoided via a minor course correction. -- Things That Never Happen in "Star Trek" #21