Edit File: Design.Arrays.txt
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> [Design.Buffers.txt], 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 ------- * 'array_append(array, data, count)' is the most common way to add data to arrays * 'array_append_array(dest, src)' * 'array_insert(array, idx, data, count)' * 'array_delete(array, idx, count)' * 'array_idx_set(array, idx, data)' replaces (or adds) data to given index * 'array_idx_clear(array, idx)' clears given index by writing NULs to it * 'array_append_space(array, count)' 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. * 'array_append_space(array)' * 'array_insert_space(array, idx)' * 'array_get_modifiable(array, &count)' * 'array_idx_modifiable(array, idx)' Others ------ * 'array_cmp(array1, array2)' compares two arrays * 'array_reverse(array)' reverses all elements in an array * 'array_sort(array, cmp_func)' is a wrapper for 'qsort()' adding also type safety. The parameters in cmp_func should be the same type as the array, instead of 'const void *'. * 'array_bsearch(array, key, cmp_func)' is a wrapper for 'bsearch()' also adding type safety, just like 'array_sort()'. (This file was created from the wiki on 2019-02-05 04:42)
Back to File Manager