lavu/mem: extend documentation for av_dynarray_add()
authorStefano Sabatini <stefasab@gmail.com>
Wed, 24 Apr 2013 22:06:13 +0000 (00:06 +0200)
committerStefano Sabatini <stefasab@gmail.com>
Tue, 7 May 2013 23:39:12 +0000 (01:39 +0200)
In particular, mention the fact that the amortized element addition cost
is constant.

libavutil/mem.h

index 02395b7..861029a 100644 (file)
@@ -199,9 +199,20 @@ void av_freep(void *ptr);
 /**
  * Add an element to a dynamic array.
  *
- * @param tab_ptr Pointer to the array.
- * @param nb_ptr  Pointer to the number of elements in the array.
- * @param elem    Element to be added.
+ * The array to grow is supposed to be an array of pointers to
+ * structures, and the element to add must be a pointer to an already
+ * allocated structure.
+ *
+ * The array is reallocated when its sizes reaches powers of 2.
+ * Therefore, the amortized cost of adding an element is constant.
+ *
+ * In case of success, the pointer to the array is updated in order to
+ * point to the new grown array, and the number pointed to by nb_ptr
+ * is incremented.
+ *
+ * @param tab_ptr pointer to the array to grow
+ * @param nb_ptr  pointer to the number of elements in the array
+ * @param elem    element to add
  */
 void av_dynarray_add(void *tab_ptr, int *nb_ptr, void *elem);