SimGrid: Dynar as a regular array

SimGrid 3.10 Versatile Simulation of Distributed Systems

- Home page
- Online documentation
- Dev's Corner

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions
Dynar as a regular array
Dynar: generic dynamic array

## Functions
void | xbt_dynar_get_cpy (const xbt_dynar_t dynar, const unsigned long idx, void *const dst)
| Retrieve a copy of the Nth element of a dynar.
void | xbt_dynar_set (xbt_dynar_t dynar, const int idx, const void *src)
| Set the Nth element of a dynar (expanded if needed). Previous value at this position is NOT freed.
void | xbt_dynar_replace (xbt_dynar_t dynar, const unsigned long idx, const void *object)
| Set the Nth element of a dynar (expanded if needed). Previous value is freed.
void | xbt_dynar_insert_at (xbt_dynar_t const dynar, const int idx, const void *src)
| Set the Nth dynar's element, expanding the dynar and sliding the previous values to the right.
void | xbt_dynar_remove_at (xbt_dynar_t const dynar, const int idx, void *const dst)
| Remove the Nth dynar's element, sliding the previous values to the left.
void | xbt_dynar_remove_n_at (xbt_dynar_t const dynar, const unsigned int n, const int idx)
| Remove a slice of the dynar, sliding the rest of the values to the left.
unsigned int | xbt_dynar_search (xbt_dynar_t const dynar, void *elem)
| Returns the position of the element in the dynar.
signed int | xbt_dynar_search_or_negative (xbt_dynar_t const dynar, void *const elem)
| Returns the position of the element in the dynar (or -1 if not found)
int | xbt_dynar_member (xbt_dynar_t const dynar, void *elem)
| Returns a boolean indicating whether the element is part of the dynar.
void | xbt_dynar_sort (xbt_dynar_t const dynar, int_f_cpvoid_cpvoid_t compar_fn)
| Sorts a dynar according to the function `compar_fn`
void | xbt_dynar_three_way_partition (xbt_dynar_t const dynar, int_f_pvoid_t color)
| Sorts a dynar according to their color assuming elements can have only three colors. Since there are only three colors, it is linear and much faster than a classical sort. See for example http://en.wikipedia.org/wiki/Dutch_national_flag_problem.
void * | xbt_dynar_to_array (xbt_dynar_t dynar)
| Transform a dynar into a NULL terminated array. The dynar won't be usable afterwards.

## Detailed Description

## Function Documentation

void xbt_dynar_get_cpy | ( | const xbt_dynar_t | dynar,
|  | const unsigned long | idx,
|  | void *const | dst
| ) |  |

Retrieve a copy of the Nth element of a dynar.

Parameters

  | dynar | information dealer
  | idx | index of the slot we want to retrieve
  [out] | dst | where to put the result to.

void xbt_dynar_set | ( | xbt_dynar_t | dynar,
|  | const int | idx,
|  | const void *const | src
| ) |  |

Set the Nth element of a dynar (expanded if needed). Previous value at this position is NOT freed.

Parameters

  dynar | information dealer
  idx | index of the slot we want to modify
  src | What will be feeded to the dynar

If you want to free the previous content, use xbt_dynar_replace().

void xbt_dynar_replace | ( | xbt_dynar_t | dynar,
|  | const unsigned long | idx,
|  | const void *const | object
| ) |  |

Set the Nth element of a dynar (expanded if needed). Previous value is freed.

Parameters

  dynar |
  idx |
  object | Set the Nth element of a dynar, expanding the dynar if needed, AND DO free the previous value at this position. If you don't want to free the previous content, use xbt_dynar_set().

void xbt_dynar_insert_at | ( | xbt_dynar_t const | dynar,
|  | const int | idx,
|  | const void *const | src
| ) |  |

Set the Nth dynar's element, expanding the dynar and sliding the previous values to the right.

Set the Nth element of a dynar, expanding the dynar if needed, and moving the previously existing value and all subsequent ones to one position right in the dynar.

void xbt_dynar_remove_at | ( | xbt_dynar_t const | dynar,
|  | const int | idx,
|  | void *const | object
| ) |  |

Remove the Nth dynar's element, sliding the previous values to the left.

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_n_at | ( | xbt_dynar_t const | dynar,
|  | const unsigned int | n,
|  | const int | idx
| ) |  |

Remove a slice of the dynar, sliding the rest of the values to the left.

This function removes an n-sized slice that starts at element idx. It is equivalent to xbt_dynar_remove_at with a NULL object argument if n equals to 1.

Each of the removed elements is freed using the free_f function passed at dynar creation.

unsigned int xbt_dynar_search | ( | xbt_dynar_t const | dynar,
|  | void *const | elem
| ) |  |

Returns the position of the element in the dynar.

Beware that if your dynar contains pointed values (such as strings) instead of scalar, this function compares the pointer value, not what's pointed. The only solution to search for a pointed value is then to write the foreach loop yourself:

signed int position = -1;
xbt_dynar_foreach(dynar, iter, elem) {
if (!memcmp(elem, searched_element, sizeof(*elem))) {
position = iter;
break;
}
}

Raises not_found_error if not found. If you have less than 2 millions elements, you probably want to use xbt_dynar_search_or_negative() instead, so that you don't have to TRY/CATCH on element not found.

signed int xbt_dynar_search_or_negative | ( | xbt_dynar_t const | dynar,
|  | void *const | elem
| ) |  |

Returns the position of the element in the dynar (or -1 if not found)

Beware that if your dynar contains pointed values (such as strings) instead of scalar, this function is probably not what you want. Check the documentation of xbt_dynar_search() for more info.

Note that usually, the dynar indices are unsigned integers. If you have more than 2 million elements in your dynar, this very function will not work (but the other will).

int xbt_dynar_member | ( | xbt_dynar_t const | dynar,
|  | void *const | elem
| ) |  |

Returns a boolean indicating whether the element is part of the dynar.

Beware that if your dynar contains pointed values (such as strings) instead of scalar, this function is probably not what you want. Check the documentation of xbt_dynar_search() for more info.

void xbt_dynar_sort | ( | xbt_dynar_t | dynar,
|  | int_f_cpvoid_cpvoid_t | compar_fn
| ) |  |

Sorts a dynar according to the function `compar_fn`

Parameters

  dynar | the dynar to sort
  compar_fn | comparison function of type (int (compar_fn*) (void*) (void*)).

Remark: if the elements stored in the dynar are structures, the compar_fn function has to retrieve the field to sort first.

void xbt_dynar_three_way_partition | ( | xbt_dynar_t const | dynar,
|  | int_f_pvoid_t | color
| ) |  |

Sorts a dynar according to their color assuming elements can have only three colors. Since there are only three colors, it is linear and much faster than a classical sort. See for example http://en.wikipedia.org/wiki/Dutch_national_flag_problem.

Parameters

  dynar | the dynar to sort
  color | the color function of type (int (compar_fn*) (void*) (void*)). The return value of color is assumed to be 0, 1, or 2.

At the end of the call, elements with color 0 are at the beginning of the dynar, elements with color 2 are at the end and elements with color 1 are in the middle.

Remark: if the elements stored in the dynar are structures, the color function has to retrieve the field to sort first.

void* xbt_dynar_to_array | ( | xbt_dynar_t | dynar | ) |

Transform a dynar into a NULL terminated array. The dynar won't be usable afterwards.

Parameters

  dynar | the dynar to transform