Structure and array derived types are assigned no value when they are allocated. As a best practice, you should assign some value to them before use; in the case of structured types with non-nullable fields, it is required. In either case, once a reference to a derived type is shared, it may no longer be modified.
rad/adr.h defines array-access macros that behave like the following prototypes:
int adr_array_size(adr_data_t *array); adr_data_t *adr_array_get(adr_data_t *array, int index);
adr_array_size returns the number of elements in array. adr_array_get returns the index element of array. The adr_data_t returned by adr_array_get is valid as long as the caller retains its reference to array; if it is needed longer, the caller should take a hold on the adr_data_t (see adr_data_t Type). If the index element of array has not been set, the behavior of adr_array_get is undefined.
The following functions modify arrays:
int adr_array_add(adr_data_t *array, adr_data_t * value);
adr_array_add adds value to the end of array. As described in adr_data_t Type, the caller's reference to value is transferred to the array. adr_array_add might need to allocate memory and can therefore fail. When adr_array_add succeeds, it returns 0. When adr_array_add fails, it will return 1 and array will be marked invalid. For more information, see Validating adr_data_t Values.
void adr_array_remove(adr_data_t *array, int index);
adr_array_remove removes the index element from array. The array's reference count on the element at index is released, possibly resulting in its deallocation. All elements following index in array are shifted to the next lower position in the array, for example, element index+1 is moved to index. The behavior of adr_array_remove is undefined if index is greater than or equal to the size of array as returned by adr_array_size.
int adr_array_vset(adr_data_t *array, int index, adr_data_t * value);
adr_array_vset sets the index element of array to value. If an element was previously at index, the reference on that element held by the array is released. adr_array_vset may need to allocate memory and can therefore fail. When adr_array_vset succeeds, it returns 0. When adr_array_vset fails, it will return 1 and array will be marked invalid. For more information, see Validating adr_data_t Values.
The primary interface for accessing an adr_data_t structure is adr_struct_get:
adr_data_t *adr_struct_get(adr_data_t *struct, const char *field);
adr_struct_get returns the value of the field named field. If the field is nullable and has no value or if the field hasn't been given a value (that is the structure was incompletely initialized), adr_struct_get returns NULL. The adr_data_t returned by adr_struct_get is valid as long as the caller retains its reference to struct. If it is needed longer the caller should take a hold on the adr_data_t. If struct does not have a field named field, the behavior of adr_struct_get is undefined.
The primary interface for writing to an adr_data_t structure is adr_struct_set:
void adr_struct_set(adr_data_t *struct, const char *field, adr_data_t *value);
adr_struct_set writes value to the field named field. If field previously had a value, the reference on that value held by the structure is released. If struct does not have a field named field, or if the type of value does not match that of the specified field the behavior of adr_struct_set is undefined.