/* $Id$ */
-/* a generic DYNamic ARray */
+/* a generic DYNamic ARray implementation. */
-/* Copyright (c) 2004 Martin Quinson. All rights reserved. */
+/* Copyright (c) 2003, 2004 Martin Quinson. All rights reserved. */
/* This program is free software; you can redistribute it and/or modify it
* under the terms of the license (GNU LGPL) which comes with this package. */
+#include "portable.h" /* SIZEOF_MAX */
#include "xbt/misc.h"
#include "xbt/sysdep.h"
#include "xbt/log.h"
#include "xbt/dynar.h"
#include <sys/types.h>
+
+
XBT_LOG_NEW_DEFAULT_SUBCATEGORY(dynar,xbt,"Dynamic arrays");
typedef struct xbt_dynar_s {
if (old_data) {
memcpy(new_data, old_data, used_length);
_xbt_clear_mem(old_data, old_length);
- xbt_free(old_data);
+ free(old_data);
}
_xbt_clear_mem(new_data + used_length, new_length - used_length);
memcpy(elm, src, elmsize);
}
-/**
- * xbt_dynar_new:
- * @elm_size: size of each element in the dynar
- * @free_func: function to call each time we want to get rid of an element (or NULL if nothing to do).
+/** @brief Constructor
+ *
+ * \param elmsize size of each element in the dynar
+ * \param free_f function to call each time we want to get rid of an element (or NULL if nothing to do).
*
* Creates a new dynar. If a free_func is provided, the elements have to be
* pointer of pointer. That is to say that dynars can contain either base
return dynar;
}
-/**
- * xbt_dynar_free_container:
- * @dynar: poor victim
+/** @brief Destructor of the structure not touching to the content
+ *
+ * \param dynar poor victim
*
- * kilkil a dynar BUT NOT its content. Ie, the array is freed, but not what
- * its contain points to.
+ * kilkil a dynar BUT NOT its content. Ie, the array is freed, but the content
+ * is not touched (the \a free_f function is not used)
*/
void
xbt_dynar_free_container(xbt_dynar_t *dynar) {
if ((*dynar)->data) {
_xbt_clear_mem((*dynar)->data, (*dynar)->size);
- xbt_free((*dynar)->data);
+ free((*dynar)->data);
}
_xbt_clear_mem(*dynar, sizeof(s_xbt_dynar_t));
- xbt_free(*dynar);
+ free(*dynar);
*dynar=NULL;
}
}
-/**
- * xbt_dynar_reset:
- * @dynar: who to squeeze
+/** @brief Frees the content and set the size to 0
*
- * Frees the content and set the size to 0
+ * \param dynar who to squeeze
*/
void
xbt_dynar_reset(xbt_dynar_t const dynar) {
}
if (dynar->data)
- xbt_free(dynar->data);
+ free(dynar->data);
dynar->size = 0;
dynar->used = 0;
dynar->data = NULL;
}
-/**
- * xbt_dynar_free:
- * @dynar: poor victim
+/** @brief Destructor
+ *
+ * \param dynar poor victim
*
* kilkil a dynar and its content
*/
}
}
-/**
- * xbt_dynar_length:
- * @dynar: the dynar we want to mesure
- *
- * Returns the count of elements in a dynar
+/** @brief Count of dynar's elements
+ *
+ * \param dynar the dynar we want to mesure
*/
unsigned long
xbt_dynar_length(const xbt_dynar_t dynar) {
return (dynar ? (unsigned long) dynar->used : (unsigned long)0);
}
-/**
- * xbt_dynar_get_cpy:
- * @dynar: information dealer
- * @idx: index of the slot we want to retrive
- * @dst: where to pu the result to.
+/** @brief Retrieve a copy of the Nth element of a dynar.
*
- * Retrieve a copy of the Nth element of a dynar.
+ * \param dynar information dealer
+ * \param idx index of the slot we want to retrive
+ * \param[out] dst where to put the result to.
*/
void
xbt_dynar_get_cpy(const xbt_dynar_t dynar,
_xbt_dynar_get_elm(dst, dynar, idx);
}
-/**
- * xbt_dynar_get_ptr:
- * @dynar: information dealer
- * @idx: index of the slot we want to retrive
- * @dst: where to pu the result to.
+/** @brief Retrieve a pointer to the Nth element of a dynar.
*
- * Retrieve the Nth element of a dynar. Warning, the returned value is the actual content of
- * the dynar. Make a copy before fooling with it.
+ * \param dynar information dealer
+ * \param idx index of the slot we want to retrieve
+ * \return the \a idx-th element of \a dynar.
+ *
+ * \warning The returned value is the actual content of the dynar.
+ * Make a copy before fooling with it.
*/
void*
xbt_dynar_get_ptr(const xbt_dynar_t dynar,
return _xbt_dynar_elm(dynar, idx);
}
-/**
- * xbt_dynar_set:
- * @dynar:
- * @idx:
- * @src: What will be feeded to the dynar
+/** @brief Set the Nth element of a dynar (expended if needed). Previous value at this position is NOT freed
+ *
+ * \param dynar information dealer
+ * \param idx index of the slot we want to modify
+ * \param src What will be feeded to the dynar
*
- * Set the Nth element of a dynar, expanding the dynar if needed, BUT NOT freeing
- * the previous value at this position. If you want to free the previous content,
- * use xbt_dynar_replace().
+ * If you want to free the previous content, use xbt_dynar_replace().
*/
void
xbt_dynar_set(xbt_dynar_t dynar,
_xbt_dynar_put_elm(dynar, idx, src);
}
-/**
- * xbt_dynar_replace:
- * @dynar:
- * @idx:
- * @object:
+/** @brief Set the Nth element of a dynar (expended if needed). Previous value is freed
+ *
+ * \param dynar
+ * \param idx
+ * \param 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
xbt_dynar_set(dynar, idx, object);
}
-/**
- * xbt_dynar_insert_at_ptr:
+/** @brief Make room for a new element, and return a pointer to it
*
- * Make room for a new element in the dynar, and return a pointer to
- * its position. You can then use regular affectation to set its value
- * instead of relying on the slow memcpy
+ * You can then use regular affectation to set its value instead of relying
+ * on the slow memcpy. This is what xbt_dynar_insert_at_as() does.
*/
void *
xbt_dynar_insert_at_ptr(xbt_dynar_t const dynar,
- const int idx) {
+ const int idx) {
__sanity_check_dynar(dynar);
__sanity_check_idx(idx);
}
}
-/**
- * xbt_dynar_insert_at:
- * @dynar:
- * @idx:
- * @src: What will be feeded to the dynar
- *
+/** @brief Set the Nth dynar's element, expending 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_insert_at(xbt_dynar_t const dynar,
- const int idx,
- const void * const src) {
+ const int idx,
+ const void * const src) {
/* checks done in xbt_dynar_insert_at_ptr */
memcpy(xbt_dynar_insert_at_ptr(dynar,idx),
dynar->elmsize);
}
-/**
- * xbt_dynar_remove_at:
- * @dynar:
- * @idx:
- * @object:
+/** @brief 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.
}
}
-/**
- * xbt_dynar_push_ptr:
- *
- * Make room at the end of the dynar for a new element, and return a pointer to it
+/** @brief Make room at the end of the dynar for a new element, and return a pointer to it.
+ *
+ * You can then use regular affectation to set its value instead of relying
+ * on the slow memcpy. This is what xbt_dynar_push_as() does.
*/
void *
xbt_dynar_push_ptr(xbt_dynar_t const dynar) {
return xbt_dynar_insert_at_ptr(dynar, dynar->used);
}
-/**
- * xbt_dynar_push:
- * @dynar:
- * @src:
- *
- * Add an element at the end of the dynar
- */
+/** @brief Add an element at the end of the dynar */
void
xbt_dynar_push(xbt_dynar_t const dynar,
const void * const src) {
xbt_dynar_insert_at(dynar, dynar->used, src);
}
-/**
- * xbt_dynar_pop_ptr:
- * @dynar:
- * @dst:
+/** @brief Mark the last dynar's element as unused and return a pointer to it.
*
- * Make the last element of the dynar as unused and return a pointer to it.
+ * You can then use regular affectation to set its value instead of relying
+ * on the slow memcpy. This is what xbt_dynar_pop_as() does.
*/
void *
xbt_dynar_pop_ptr(xbt_dynar_t const dynar) {
return _xbt_dynar_elm(dynar,dynar->used);
}
-/**
- * xbt_dynar_pop:
- * @dynar:
- * @dst:
- *
- * Get and remove the last element of the dynar
- */
+/** @brief Get and remove the last element of the dynar */
void
xbt_dynar_pop(xbt_dynar_t const dynar,
void * const dst) {
xbt_dynar_remove_at(dynar, dynar->used-1, dst);
}
-/**
- * xbt_dynar_unshift:
- * @dynar:
- * @src:
+/** @brief Add an element at the begining of the dynar.
*
- * Add an element at the begining of the dynar (rather long, Use
- * xbt_dynar_push() when possible)
+ * This is less efficient than xbt_dynar_push()
*/
void
xbt_dynar_unshift(xbt_dynar_t const dynar,
xbt_dynar_insert_at(dynar, 0, src);
}
-/**
- * xbt_dynar_shift:
- * @dynar:
- * @dst:
+/** @brief Get and remove the first element of the dynar.
*
- * Get and remove the first element of the dynar (rather long, Use
- * xbt_dynar_pop() when possible)
+ * This is less efficient than xbt_dynar_pop()
*/
void
xbt_dynar_shift(xbt_dynar_t const dynar,
xbt_dynar_remove_at(dynar, 0, dst);
}
-/**
- * xbt_dynar_map:
- * @dynar:
- * @operator:
+/** @brief Apply a function to each member of a dynar
*
- * Apply a function to each member of a dynar (this function may change the
- * value of the element itself, but should not mess with the dynar).
+ * The mapped function may change the value of the element itself,
+ * but should not mess with the structure of the dynar.
*/
void
xbt_dynar_map(const xbt_dynar_t dynar,
__sanity_check_dynar(dynar);
{
- char elm[64];
+ char elm[SIZEOF_MAX];
const unsigned long used = dynar->used;
unsigned long i = 0;
}
}
-/**
- * xbt_dynar_cursor_first:
- *
- * Put the cursor at the begining of the dynar. (actually, one step before
- * the begining, so that you can iterate over the dynar with a for loop).
- *
- * Dynar cursor are as dumb as possible. If you insert or remove elements
- * from the dynar between the creation and end, you'll fuck up your
- * cursors.
+/** @brief Put the cursor at the begining of the dynar.
*
+ * Actually, the cursor is set one step before the begining, so that you
+ * can iterate over the dynar with a for loop.
*/
void
xbt_dynar_cursor_first(const xbt_dynar_t dynar,
- int * const cursor) {
+ int * const cursor) {
DEBUG1("Set cursor on %p to the first position",(void*)dynar);
*cursor = 0;
}
-/**
- * xbt_dynar_cursor_step:
- *
- * Move the cursor to the next value (and return true), or return false.
- */
+/** @brief Move the cursor to the next value */
void
xbt_dynar_cursor_step(const xbt_dynar_t dynar,
int * const cursor) {
(*cursor)++;
}
-/**
- * xbt_dynar_cursor_get:
- *
- * Get the current value of the cursor
- */
+/** @brief Get the data currently pointed by the cursor */
int
xbt_dynar_cursor_get(const xbt_dynar_t dynar,
int * const cursor,
}
-/**
- * xbt_dynar_cursor_rm:
- * @dynar:
- * @cursor:
+/** @brief Removes and free the entry pointed by the cursor
*
- * Remove (free) the entry pointed by the cursor, for use in the middle of a foreach
+ * This function can be used while traversing without problem.
*/
void xbt_dynar_cursor_rm(xbt_dynar_t dynar,
int * const cursor) {
dst=xbt_malloc(dynar->elmsize);
xbt_dynar_remove_at(dynar,(*cursor)--,dst);
(dynar->free_f)(dst);
- xbt_free(dst);
+ free(dst);
} else {
DEBUG0("Ok, we dont care about the element without free function");
xbt_dynar_remove_at(dynar,(*cursor)--,NULL);
