Another doc improvement

[simgrid.git] / src / xbt / dynar.c

diff --git a/src/xbt/dynar.c b/src/xbt/dynar.c
index ede8618..4e89515 100644 (file)
--- a/src/xbt/dynar.c
+++ b/src/xbt/dynar.c
@@ -40,13 +40,13 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(xbt_dyn,xbt,"Dynamic arrays");
            xbt_assert1(dynar->used,              \
                        "dynar %p contains nothing",(void*)dynar)
 
-static _XBT_INLINE 
+static XBT_INLINE 
 void _xbt_clear_mem(void * const ptr,
                     const unsigned long length) {
   memset(ptr, 0, length);
 }
 
-static _XBT_INLINE
+static XBT_INLINE
 void
 _xbt_dynar_expand(xbt_dynar_t const dynar,
                    const int          nb) {
@@ -80,7 +80,7 @@ _xbt_dynar_expand(xbt_dynar_t const dynar,
   }
 }
 
-static _XBT_INLINE
+static XBT_INLINE
 void *
 _xbt_dynar_elm(const xbt_dynar_t  dynar,
                const unsigned long idx) {
@@ -90,7 +90,7 @@ _xbt_dynar_elm(const xbt_dynar_t  dynar,
   return data + idx*elmsize;
 }
 
-static _XBT_INLINE
+static XBT_INLINE
 void
 _xbt_dynar_get_elm(void  * const       dst,
                     const xbt_dynar_t  dynar,
@@ -100,7 +100,7 @@ _xbt_dynar_get_elm(void  * const       dst,
   memcpy(dst, elm, dynar->elmsize);
 }
 
-static _XBT_INLINE
+static XBT_INLINE
 void
 _xbt_dynar_put_elm(const xbt_dynar_t  dynar,
                     const unsigned long idx,
@@ -187,6 +187,29 @@ xbt_dynar_reset(xbt_dynar_t const dynar) {
 /*  dynar->data = NULL;*/
 }
 
+/**
+ * \brief Shrink the dynar by removing empty slots at the end of the internal array
+ * \param dynar a dynar
+ * \param empty_slots_wanted number of empty slots you want to keep at the end of the
+ * internal array for further insertions
+ * 
+ * Reduces the internal array size of the dynar to the number of elements plus
+ * \a empty_slots_wanted.
+ * After removing elements from the dynar, you can call this function to make
+ * the dynar use less memory.
+ * Set \a empty_slots_wanted to zero to reduce the dynar internal array as much
+ * as possible.
+ * Note that if \a empty_slots_wanted is greater than the array size, the internal
+ * array is not expanded and nothing is done.
+ */
+void xbt_dynar_shrink(xbt_dynar_t dynar, int empty_slots_wanted) {
+  int size_wanted = dynar->used + empty_slots_wanted;
+  if (size_wanted < dynar->size) {
+    dynar->size = size_wanted;
+    dynar->data = xbt_realloc(dynar->data, sizeof(void*) * dynar->size);
+  }
+}
+
 /** @brief Destructor
  * 
  * \param dynar poor victim
@@ -358,6 +381,10 @@ xbt_dynar_insert_at(xbt_dynar_t  const dynar,
  *
  * Get the Nth element of a dynar, removing it from the dynar and moving
  * all subsequent values to one position left in the dynar.
+ * 
+ * If the object argument of this function is a non-null pointer, the removed 
+ * element is copied to this address. If not, the element is freed using the 
+ * free_f function passed at dynar creation.
  */
 void
 xbt_dynar_remove_at(xbt_dynar_t  const dynar,