This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.

Dynamic Arrays

lib/array.h and lib/array-decl.h describes Dovecot's type-safe dynamic arrays. Trying to add wrong typed elements gives a compiler warning.

Declaring

Arrays can be declared in two ways:

  1. Directly: ARRAY_DEFINE(array_name, array_type);. For example: ARRAY_DEFINE(numbers, int); or ARRAY_DEFINE(foos, struct foo);

  2. Via predefined type: ARRAY_DEFINE_TYPE(foo, struct foo); ... ARRAY_TYPE(foo) foos;

The main reason to define a type for an array is to be able to pass the array as a function parameter, like:

void func(ARRAY_TYPE(foo) *foos) { .. }

Trying to do the same with ARRAY_DEFINE() will generate a compiler warning. lib/array-decl.h defines several commonly used types.

Initializing

Arrays are typically initialized by calling i_array_init(), p_array_init() or t_array_init() depending on where you want to allocate the memory from. Arrays are internally handled as buffers, so the initial size is just multiplied by element size and passed to buffer_create_dynamic().

Example:

ARRAY_DEFINE(foo, struct foo *);

i_array_init(&foo, 32); /* initialize array with 32 elements until it needs to be grown */

Arrays can be freed with array_free(), but this isn't necessary if the memory gets freed by other means (i.e. it was allocated from alloconly-pool or data stack).

Writing

Reading

array_idx(array, idx) returns pointer to given index in array. The index must already exist, otherwise the call assert-crashes. This call adds extra overhead for accessing arrays though, so usually it's better to just get list of all elements and access them directly:

data = array_get(&array, &count);

You can also iterate through the whole array easily:

const char *str;

array_foreach(&string_array, str) {
  /* str changes in each iteration */
}

There's also array_foreach_modifiable() to get the data without const.

Unsafe Read/Write

Functions below have similar problems to [[Design/Buffer|buffer]'s *_unsafe() functions. Memory returned by them must not be accessed after calls to other array_*() modifying functions, because they may reallocate the array elsewhere in memory.

Others

Design/Arrays (last edited 2010-02-10 16:24:08 by amprx01x)