Commit 9b8de3f5 authored by Vladimír Čunát's avatar Vladimír Čunát

lib/generic/{array,pack}: improve documentation

parent 3aacb950
......@@ -104,25 +104,28 @@ static inline void array_std_free(void *baton, void *p)
/** Zero-initialize the array. */
#define array_init(array) ((array).at = NULL, (array).len = (array).cap = 0)
/** Free and zero-initialize the array. */
/** Free and zero-initialize the array (plain malloc/free). */
#define array_clear(array) \
array_clear_mm(array, array_std_free, NULL)
/** @internal Clear array with a callback. */
/** Make the array empty and free pointed-to memory.
* Mempool usage: pass mm_free and a knot_mm_t* . */
#define array_clear_mm(array, free, baton) \
(free)((baton), (array).at), array_init(array)
/**
* Reserve capacity up to 'n' bytes.
* @return 0 if success, <0 on failure
*/
/** Reserve capacity for at least n elements.
* @return 0 if success, <0 on failure */
#define array_reserve(array, n) \
array_reserve_mm(array, n, array_std_reserve, NULL)
/** @internal Reserve capacity using callback. */
/** Reserve capacity for at least n elements.
* Mempool usage: pass kr_memreserve and a knot_mm_t* .
* @return 0 if success, <0 on failure */
#define array_reserve_mm(array, n, reserve, baton) \
(reserve)((baton), (char **) &(array).at, sizeof((array).at[0]), (n), &(array).cap)
/**
* Push value at the end of the array, resize it if necessary.
* Push value at the end of the array, resize it if necessary (malloc/free).
* @note May fail if the capacity is not reserved.
* @return element index on success, <0 on failure
*/
......
......@@ -75,21 +75,31 @@ typedef array_t(uint8_t) pack_t;
/** Zero-initialize the pack. */
#define pack_init(pack) \
array_init(pack)
/** Free and the pack. */
/** Make the pack empty and free pointed-to memory (plain malloc/free). */
#define pack_clear(pack) \
array_clear(pack)
/** @internal Clear pack with a callback. */
/** Make the pack empty and free pointed-to memory.
* Mempool usage: pass mm_free and a knot_mm_t* . */
#define pack_clear_mm(pack, free, baton) \
array_clear_mm((pack), (free), (baton))
/** Incrementally reserve objects in the pack. */
/** Reserve space for *additional* objects in the pack (plain malloc/free).
* @return 0 if success, <0 on failure */
#define pack_reserve(pack, objs_count, objs_len) \
pack_reserve_mm((pack), (objs_count), (objs_len), array_std_reserve, NULL)
/** @internal Reservation with a callback. */
/** Reserve space for *additional* objects in the pack.
* Mempool usage: pass kr_memreserve and a knot_mm_t* .
* @return 0 if success, <0 on failure */
#define pack_reserve_mm(pack, objs_count, objs_len, reserve, baton) \
array_reserve_mm((pack), (pack).len + (sizeof(pack_objlen_t)*(objs_count) + (objs_len)), (reserve), (baton))
/** Return pointer to first packed object. */
#define pack_head(pack) \
((pack).len > 0 ? &((pack).at[0]) : NULL)
/** Return pack end pointer. */
#define pack_tail(pack) \
&((pack).at[(pack).len])
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment