Manipulating Array adr_data_t Values

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 the reference is needed longer duration, 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.