Dynar: generic dynamic array

Detailed Description

DynArr are dynamically sized vector which may contain any type of variables.

These are the SimGrid version of the dynamically size arrays, which all C programmer recode one day or another.

For performance concerns, the content of DynArr must be homogeneous (in contrary to dictionnaries – see the Dict: generic dictionnary section). You thus have to provide the function which will be used to free the content at structure creation (of type void_f_pvoid_t).

Deprecated:

If you are using C++, you might want to use std::vector instead.

Example with scalar

  xbt_test_add("==== Traverse the empty dynar");
  xbt_dynar_t d = xbt_dynar_new(sizeof(int), nullptr);
  xbt_dynar_foreach(d, cursor, i) {
    xbt_die( "Damnit, there is something in the empty dynar");
  }
  xbt_dynar_free(&d);           /* This code is used both as example and as regression test, so we try to */
  xbt_dynar_free(&d);           /* free the struct twice here to check that it's ok, but freeing  it only once */
  /* in your code is naturally the way to go outside a regression test */

  xbt_test_add("==== Push %d int, set them again 3 times, traverse them, shift them", NB_ELEM);
  /* Populate_ints [doxygen cruft] */
  /* 1. Populate the dynar */
  d = xbt_dynar_new(sizeof(int), nullptr);
  for (int cpt = 0; cpt < NB_ELEM; cpt++) {
    xbt_dynar_push_as(d, int, cpt);     /* This is faster (and possible only with scalars) */
    /* xbt_dynar_push(d,&cpt);       This would also work */
    xbt_test_log("Push %d, length=%lu", cpt, xbt_dynar_length(d));
  }

  /* 2. Traverse manually the dynar */
  for (cursor = 0; cursor < NB_ELEM; cursor++) {
    int* iptr = (int*)xbt_dynar_get_ptr(d, cursor);
  /* 1. Populate the dynar */
  for (int cpt = 0; cpt < NB_ELEM; cpt++) {
    xbt_dynar_insert_at(d, cpt, &cpt);
    xbt_test_log("Push %d, length=%lu", cpt, xbt_dynar_length(d));
  }

  /* 3. Traverse the dynar */
  int cpt;
  xbt_dynar_foreach(d, cursor, cpt) {
    xbt_test_assert(cursor == (unsigned int) cpt, "The retrieved value is not the same than the injected one (%u!=%d)", cursor, cpt);
  }
  /* end_of_traversal */

Example with pointed data

Note that if you use dynars to store pointed data, the xbt_dynar_search(), xbt_dynar_search_or_negative() and xbt_dynar_member() won't be for you. Instead of comparing your pointed elements, they compare the pointer to them. See the documentation of xbt_dynar_search() for more info.

Modules
	Dynar constructor and destructor
	Dynar as a regular array
	Dynar miscellaneous functions
	Perl-like use of dynars
	Direct manipulation to the dynars content
	Those functions do not retrieve the content, but only their address.
	Speed optimized access to dynars of scalars
	While the other functions use a memcpy to retrieve the content into the user provided area, those ones use a regular affectation.
	Cursors on dynar
	Cursors are used to iterate over the structure.