additional doc resulting from discussions with kenenbek

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

diff --git a/src/xbt/dynar.c b/src/xbt/dynar.c
index 006ea0d..a62e51f 100644 (file)
--- a/src/xbt/dynar.c
+++ b/src/xbt/dynar.c
@@ -562,11 +562,29 @@ inline void xbt_dynar_cursor_rm(xbt_dynar_t dynar, unsigned int *const cursor)
 
 /** @brief Sorts a dynar according to the function <tt>compar_fn</tt>
  *
- * \param dynar the dynar to sort
- * \param compar_fn comparison function of type (int (compar_fn*) (void*) (void*)).
+ * This function simply apply the classical qsort(3) function to the data stored in the dynar.
+ * You should thus refer to the libc documentation, or to some online tutorial on how to write
+ * a comparison function. Here is a quick example if you have integers in your dynar:
  *
- * Remark: if the elements stored in the dynar are structures, the compar_fn function has to retrieve the field to sort
- * first.
+ * @verbatim
+ * int cmpfunc (const void * a, const void * b) {
+ *   int intA = *(int*)a;
+ *   int intB = *(int*)b;
+ *   return intA - intB;
+ * }
+ * @endverbatim
+ *
+ * and now to sort a dynar of MSG hosts depending on their speed:
+ * @verbatim
+ * int cmpfunc(const MSG_host_t a, const MSG_host_t b) {
+ *   MSG_host_t hostA = *(MSG_host_t*)a;
+ *   MSG_host_t hostB = *(MSG_host_t*)b;
+ *   return MSG_host_get_speed(hostA) - MSG_host_get_speed(hostB);
+ * }
+ * @endverbatim
+ *
+ * \param dynar the dynar to sort
+ * \param compar_fn comparison function of type (int (compar_fn*) (const void*) (const void*)).
  */
 inline void xbt_dynar_sort(xbt_dynar_t dynar, int_f_cpvoid_cpvoid_t compar_fn)
 {
@@ -1029,27 +1047,27 @@ XBT_TEST_UNIT("string", test_dynar_string, "Dynars of strings")
   d = xbt_dynar_new(sizeof(char *), &xbt_free_ref);
   /* 1. Populate the dynar */
   for (cpt = 0; cpt < NB_ELEM; cpt++) {
-    sprintf(buf, "%d", cpt);
+    snprintf(buf,1023, "%d", cpt);
     s1 = xbt_strdup(buf);
     xbt_dynar_push(d, &s1);
   }
   for (cpt = 0; cpt < NB_ELEM; cpt++) {
-    sprintf(buf, "%d", cpt);
+    snprintf(buf,1023, "%d", cpt);
     s1 = xbt_strdup(buf);
     xbt_dynar_replace(d, cpt, &s1);
   }
   for (cpt = 0; cpt < NB_ELEM; cpt++) {
-    sprintf(buf, "%d", cpt);
+    snprintf(buf,1023, "%d", cpt);
     s1 = xbt_strdup(buf);
     xbt_dynar_replace(d, cpt, &s1);
   }
   for (cpt = 0; cpt < NB_ELEM; cpt++) {
-    sprintf(buf, "%d", cpt);
+    snprintf(buf,1023, "%d", cpt);
     s1 = xbt_strdup(buf);
     xbt_dynar_replace(d, cpt, &s1);
   }
   for (cpt = 0; cpt < NB_ELEM; cpt++) {
-    sprintf(buf, "%d", cpt);
+    snprintf(buf,1023, "%d", cpt);
     xbt_dynar_shift(d, &s2);
     xbt_test_assert(!strcmp(buf, s2), "The retrieved value is not the same than the injected one (%s!=%s)", buf, s2);
     free(s2);
@@ -1061,18 +1079,18 @@ XBT_TEST_UNIT("string", test_dynar_string, "Dynars of strings")
   xbt_test_add("==== Unshift, traverse and pop %d strings", NB_ELEM);
   d = xbt_dynar_new(sizeof(char **), &xbt_free_ref);
   for (cpt = 0; cpt < NB_ELEM; cpt++) {
-    sprintf(buf, "%d", cpt);
+    snprintf(buf,1023, "%d", cpt);
     s1 = xbt_strdup(buf);
     xbt_dynar_unshift(d, &s1);
   }
   /* 2. Traverse the dynar with the macro */
   xbt_dynar_foreach(d, iter, s1) {
-    sprintf(buf, "%u", NB_ELEM - iter - 1);
+    snprintf(buf,1023, "%u", NB_ELEM - iter - 1);
     xbt_test_assert(!strcmp(buf, s1), "The retrieved value is not the same than the injected one (%s!=%s)", buf, s1);
   }
   /* 3. Traverse the dynar with the macro */
   for (cpt = 0; cpt < NB_ELEM; cpt++) {
-    sprintf(buf, "%d", cpt);
+    snprintf(buf,1023, "%d", cpt);
     xbt_dynar_pop(d, &s2);
     xbt_test_assert(!strcmp(buf, s2), "The retrieved value is not the same than the injected one (%s!=%s)", buf, s2);
     free(s2);
@@ -1085,32 +1103,32 @@ XBT_TEST_UNIT("string", test_dynar_string, "Dynars of strings")
   xbt_test_add("==== Push %d strings, insert %d strings in the middle, shift everything", NB_ELEM, NB_ELEM / 5);
   d = xbt_dynar_new(sizeof(char *), &xbt_free_ref);
   for (cpt = 0; cpt < NB_ELEM; cpt++) {
-    sprintf(buf, "%d", cpt);
+    snprintf(buf,1023, "%d", cpt);
     s1 = xbt_strdup(buf);
     xbt_dynar_push(d, &s1);
   }
   for (cpt = 0; cpt < NB_ELEM / 5; cpt++) {
-    sprintf(buf, "%d", cpt);
+    snprintf(buf,1023, "%d", cpt);
     s1 = xbt_strdup(buf);
     xbt_dynar_insert_at(d, NB_ELEM / 2, &s1);
   }
 
   for (cpt = 0; cpt < NB_ELEM / 2; cpt++) {
-    sprintf(buf, "%d", cpt);
+    snprintf(buf,1023, "%d", cpt);
     xbt_dynar_shift(d, &s2);
     xbt_test_assert(!strcmp(buf, s2),
                      "The retrieved value is not the same than the injected one at the begining (%s!=%s)", buf, s2);
     free(s2);
   }
   for (cpt = (NB_ELEM / 5) - 1; cpt >= 0; cpt--) {
-    sprintf(buf, "%d", cpt);
+    snprintf(buf,1023, "%d", cpt);
     xbt_dynar_shift(d, &s2);
     xbt_test_assert(!strcmp(buf, s2),
                      "The retrieved value is not the same than the injected one in the middle (%s!=%s)", buf, s2);
     free(s2);
   }
   for (cpt = NB_ELEM / 2; cpt < NB_ELEM; cpt++) {
-    sprintf(buf, "%d", cpt);
+    snprintf(buf,1023, "%d", cpt);
     xbt_dynar_shift(d, &s2);
     xbt_test_assert(!strcmp(buf, s2), "The retrieved value is not the same than the injected one at the end (%s!=%s)",
                      buf, s2);
@@ -1123,12 +1141,12 @@ XBT_TEST_UNIT("string", test_dynar_string, "Dynars of strings")
   xbt_test_add("==== Push %d strings, remove %d-%d. free the rest", NB_ELEM, 2 * (NB_ELEM / 5), 4 * (NB_ELEM / 5));
   d = xbt_dynar_new(sizeof(char *), &xbt_free_ref);
   for (cpt = 0; cpt < NB_ELEM; cpt++) {
-    sprintf(buf, "%d", cpt);
+    snprintf(buf,1023, "%d", cpt);
     s1 = xbt_strdup(buf);
     xbt_dynar_push(d, &s1);
   }
   for (cpt = 2 * (NB_ELEM / 5); cpt < 4 * (NB_ELEM / 5); cpt++) {
-    sprintf(buf, "%d", cpt);
+    snprintf(buf,1023, "%d", cpt);
     xbt_dynar_remove_at(d, 2 * (NB_ELEM / 5), &s2);
     xbt_test_assert(!strcmp(buf, s2), "Remove a bad value. Got %s, expected %s", s2, buf);
     free(s2);