From: David Mitchell <davem@iabyn.com>
Date: Sun, 29 Mar 2009 21:03:13 +0000 (+0100)
Subject: provide minimal documentation for the MUTABLE_*() macros
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=cf3f0ffbff208944549640df283e3008d1b83d77;p=p5sagit%2Fp5-mst-13.2.git

provide minimal documentation for the MUTABLE_*() macros
---

diff --git a/handy.h b/handy.h
index 26a41a5..9e8f50a 100644
--- a/handy.h
+++ b/handy.h
@@ -48,6 +48,15 @@ Null SV pointer. (No longer available when C<PERL_CORE> is defined.)
 #define TRUE (1)
 #define FALSE (0)
 
+/* The MUTABLE_*() macros cast pointers to the types shown, in such a way
+ * (compiler permitting) that casting away const-ness will give a warning;
+ * e.g.:
+ *
+ * const SV *sv = ...;
+ * AV *av1 = (AV*)sv;        <== BAD:  the const has been silently cast away
+ * AV *av2 = MUTABLE_AV(sv); <== GOOD: it may warn
+ */
+
 #if defined(__GNUC__) && !defined(PERL_GCC_BRACE_GROUPS_FORBIDDEN)
 #  define MUTABLE_PTR(p) ({ void *_p = (p); _p; })
 #else