dovecot-2.2: lib: array - explain implications of ARRAY_TYPE() i...

[dovecot at dovecot.org]

details:   http://hg.dovecot.org/dovecot-2.2/rev/17ec2a11cf44
changeset: 18134:17ec2a11cf44
user:      Phil Carmody <phil at dovecot.fi>
date:      Mon Jan 05 22:15:07 2015 +0200
description:
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 at gulbrandsen.priv.no>
Signed-off-by: Phil Carmody <phil at dovecot.fi>

diffstat:

 src/lib/array.h |  14 +++++++++++---
 1 files changed, 11 insertions(+), 3 deletions(-)

diffs (29 lines):

diff -r fa815914dce6 -r 17ec2a11cf44 src/lib/array.h
--- a/src/lib/array.h	Mon Jan 05 22:13:59 2015 +0200
+++ b/src/lib/array.h	Mon Jan 05 22:15:07 2015 +0200
@@ -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"