documenting SCALAR gotcha

Message-id: <20031207154116.GA825@ethan>

p4raw-id: //depot/perl@21865

diff --git a/pod/perltie.pod b/pod/perltie.pod
index 327af04..30a0b1d 100644 (file)
--- a/pod/perltie.pod
+++ b/pod/perltie.pod
@@ -768,6 +768,12 @@ the hash is inside an iteration. If this isn't the case, FIRSTKEY is
 called, and the result will be a false value if FIRSTKEY returns the empty
 list, true otherwise.
 
+However, you should B<not> blindly rely on perl always doing the right 
+thing. Particularly, perl will mistakenly return true when you clear the 
+hash by repeatedly calling DELETE until it is empty. You are therefore 
+advised to supply your own SCALAR method when you want to be absolutely 
+sure that your hash behaves nicely in scalar context.
+
 In our example we can just call C<scalar> on the underlying hash
 referenced by C<$self-E<gt>{LIST}>: