[DOC PATCH] pod/perlguts.pod

From: "Marcus Holland-Moritz" <mhx-perl@gmx.net>
Message-ID: <004a01c357a3$c71f9f50$0c2f1fac@R2D2>

p4raw-id: //depot/perl@20388

1 files changed, 54 insertions, 0 deletions

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 9a411e1597..b763dfea9a 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -202,6 +202,8 @@ you can call:
 
 The scalar C<undef> value is stored in an SV instance called C<PL_sv_undef>.
 Its address can be used whenever an C<SV*> is needed.
+However, you have to be careful when using C<&PL_sv_undef> as a value in AVs
+or HVs (see L<AVs, HVs and undefined values>).
 
 There are also the two values C<PL_sv_yes> and C<PL_sv_no>, which contain
 boolean TRUE and FALSE values, respectively.  Like C<PL_sv_undef>, their
@@ -489,6 +491,58 @@ reference count of the stored C<val>, which is the caller's responsibility.
 If these functions return a NULL value, the caller will usually have to
 decrement the reference count of C<val> to avoid a memory leak.
 
+=head2 AVs, HVs and undefined values
+
+Sometimes you have to store undefined values in AVs or HVs. Although
+this may be a rare case, it can be tricky. That's because you're
+used to using C<&PL_sv_undef> if you need an undefined SV.
+
+For example, intuition tells you that this XS code:
+
+    AV *av = newAV();
+    av_store( av, 0, &PL_sv_undef );
+
+is equivalent to this Perl code:
+
+    my @av;
+    $av[0] = undef;
+
+Unfortunately, this isn't true. AVs use C<&PL_sv_undef> as a marker
+for indicating that an array element has not yet been initialized.
+Thus, C<exists $av[0]> would be true for the above Perl code, but
+false for the array generated by the XS code.
+
+Other problems can occur when storing C<&PL_sv_undef> in HVs:
+
+    hv_store( hv, "key", 3, &PL_sv_undef, 0 );
+
+This will indeed make the value C<undef>, but if you try to modify
+the value of C<key>, you'll get the following error:
+
+    Modification of non-creatable hash value attempted
+
+In perl 5.8.0, C<&PL_sv_undef> was also used to mark placeholders
+in restricted hashes. This caused such hash entries not to appear
+when iterating over the hash or when checking for the keys
+with the C<hv_exists> function.
+
+You can run into similar problems when you store C<&PL_sv_true> or
+C<&PL_sv_false> into AVs or HVs. Trying to modify such elements
+will give you the following error:
+
+    Modification of a read-only value attempted
+
+To make a long story short, you can use the special variables
+C<&PL_sv_undef>, C<&PL_sv_true> and C<&PL_sv_false> with AVs and
+HVs, but you have to make sure you know what you're doing.
+
+Generally, if you want to store an undefined value in an AV
+or HV, you should not use C<&PL_sv_undef>, but rather create a
+new undefined value using the C<newSV> function, for example:
+
+    av_store( av, 42, newSV(0) );
+    hv_store( hv, "foo", 3, newSV(0), 0 );
+
 =head2 References
 
 References are a special type of scalar that point to other data types