From: Phil Carmody <phil@dovecot.fi>
Date: Mon, 5 Jan 2015 20:15:07 +0000 (+0200)
Subject: lib: array - explain implications of ARRAY_TYPE() in comment
X-Git-Tag: 2.2.16.rc1~172
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fe08c73b0bf87bfa3bfb2d3df5dc9845113e0cf3;p=thirdparty%2Fdovecot%2Fcore.git

lib: array - explain implications of ARRAY_TYPE() in comment
If you use ARRAY_TYPE() to pass an array around, then you must also
use ARRAY_TYPE() to define the array itself, ARRAY() will no longer do.

Reported-by: Arnt Gulbrandsen <arnt@gulbrandsen.priv.no>
Signed-off-by: Phil Carmody <phil@dovecot.fi>
---

diff --git a/src/lib/array.h b/src/lib/array.h
index 84b6726762..865567bf48 100644
--- a/src/lib/array.h
+++ b/src/lib/array.h
@@ -20,14 +20,22 @@
 
    If you want to pass an array as a parameter to a function, you'll need to
    create a type for the array using ARRAY_DEFINE_TYPE() and use the type in
-   the parameter using ARRAY_TYPE().
+   the parameter using ARRAY_TYPE(). Any arrays that you want to be passing
+   around, such as structure members as in the above example, must also be
+   defined using ARRAY_TYPE() too, rather than ARRAY().
 
    Example:
 
    ARRAY_DEFINE_TYPE(foo, struct foo);
-   void do_foo(ARRAY_TYPE(foo) *bars) {
-	struct foo *foo = array_idx(bars, 0);
+   void do_foo(ARRAY_TYPE(foo) *foos) {
+	struct foo *foo = array_idx(foos, 0);
    }
+   struct foo_manager {
+        ARRAY_TYPE(foo) foos; // pedantically, ARRAY(struct foo) is a different type
+   };
+   // ...
+        do_foo(&my_foo_manager->foos); // No compiler warning about mismatched types
+
 */
 #include "array-decl.h"
 #include "buffer.h"