X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/e6692e68ddfe1ef3234cacab53edb44277ae4405..749ea30edef7311180cd8449a1ff449ea5d47b93:/include/xbt/dynar.h diff --git a/include/xbt/dynar.h b/include/xbt/dynar.h index 062e9442d6..5f1df3bb8a 100644 --- a/include/xbt/dynar.h +++ b/include/xbt/dynar.h @@ -14,69 +14,149 @@ BEGIN_DECL() -/** \brief Dictionnary data type - \ingroup XBT_dynar -*/ -typedef struct xbt_dynar_s *xbt_dynar_t; +/** \addtogroup XBT_dynar + * + * For performance concerns, the content of DynArr must be homogeneous (in + * contrary to dictionnaries -- see the \ref XBT_dict section). You thus + * have to provide the function which will be used to free the content at + * structure creation (of type void_f_ppvoid_t or void_f_pvoid_t). + * + * \section XBT_dynar_exscal Example with scalar + * \dontinclude dynar_int.c + * + * \skip Vars_decl + * \skip dyn + * \until iptr + * \skip Populate_ints + * \skip dyn + * \until end_of_traversal + * \skip shifting + * \skip val + * \until xbt_dynar_free + * + * \section XBT_dynar_exptr Example with pointed data + * \dontinclude dynar_string.c + * + * \skip doxygen_first_cruft + * \skip f + * \until xbt_init + * \skip Populate_str + * \skip dyn + * \until } + * \skip macro + * \until dynar_free + * \skip xbt_exit + * \until } + * @{ + */ + +/** @name 1. Constructor/destructor + * @{ + */ + /** \brief Dynar data type (opaque type) */ + typedef struct xbt_dynar_s *xbt_dynar_t; -xbt_dynar_t xbt_dynar_new(unsigned long elm_size, - void_f_pvoid_t *free_func); -void xbt_dynar_free(xbt_dynar_t *dynar); -void xbt_dynar_free_container(xbt_dynar_t *dynar); + /** \brief Pointer to a function freeing a pointed data */ + typedef void (void_f_ppvoid_t)(void**); + /** \brief Pointer to a function freeing some data */ + typedef void (void_f_pvoid_t) (void*); -unsigned long xbt_dynar_length(const xbt_dynar_t dynar); -void xbt_dynar_reset(xbt_dynar_t dynar); + xbt_dynar_t xbt_dynar_new(unsigned long elm_size, + void_f_pvoid_t *free_func); + void xbt_dynar_free(xbt_dynar_t *dynar); + void xbt_dynar_free_container(xbt_dynar_t *dynar); + unsigned long xbt_dynar_length(const xbt_dynar_t dynar); + void xbt_dynar_reset(xbt_dynar_t dynar); -/* regular array functions */ -void xbt_dynar_get_cpy(const xbt_dynar_t dynar, int idx, void *const dst); -void *xbt_dynar_get_ptr(const xbt_dynar_t dynar, - const int idx); +/** @name 2. regular array functions + * @{ + */ -#define xbt_dynar_get_as(dynar,idx,type) *(type*)xbt_dynar_get_ptr(dynar,idx) + void xbt_dynar_get_cpy(const xbt_dynar_t dynar, int idx, void *const dst); -void xbt_dynar_set(xbt_dynar_t dynar, int idx, const void *src); -void xbt_dynar_replace(xbt_dynar_t dynar, - int idx, const void *object); - -/* perl array function */ - -void xbt_dynar_insert_at(xbt_dynar_t dynar, - int idx, const void *src); -void xbt_dynar_remove_at(xbt_dynar_t dynar, - int idx, void *object); -void xbt_dynar_push (xbt_dynar_t dynar, const void *src); -void xbt_dynar_pop (xbt_dynar_t dynar, void *const dst); -void xbt_dynar_unshift (xbt_dynar_t dynar, const void *src); -void xbt_dynar_shift (xbt_dynar_t dynar, void *const dst); -void xbt_dynar_map (const xbt_dynar_t dynar, void_f_pvoid_t *operator); - -/* speed-optimized versions */ -void *xbt_dynar_insert_at_ptr(xbt_dynar_t const dynar, - const int idx); -void *xbt_dynar_push_ptr(xbt_dynar_t dynar); -void *xbt_dynar_pop_ptr(xbt_dynar_t dynar); - -#define xbt_dynar_insert_at_as(dynar,idx,type,value) *(type*)xbt_dynar_insert_at_ptr(dynar,idx)=value -#define xbt_dynar_push_as(dynar,type,value) *(type*)xbt_dynar_push_ptr(dynar)=value -#define xbt_dynar_pop_as(dynar,type) *(type*)xbt_dynar_pop_ptr(dynar) - - -/* cursor functions */ -void xbt_dynar_cursor_first (const xbt_dynar_t dynar, int *cursor); -void xbt_dynar_cursor_step (const xbt_dynar_t dynar, int *cursor); -int xbt_dynar_cursor_get (const xbt_dynar_t dynar, int *cursor, void *whereto); - - -/** - \brief Dynar iterator - \ingroup XBT_dynar - * xbt_dynar_foreach: - * \param _dynar what to iterate over - * \param _cursor an integer used as cursor - * \param _data + void xbt_dynar_set(xbt_dynar_t dynar, int idx, const void *src); + void xbt_dynar_replace(xbt_dynar_t dynar, int idx, const void *object); + + void xbt_dynar_insert_at(xbt_dynar_t dynar, int idx, const void *src); + void xbt_dynar_remove_at(xbt_dynar_t dynar, int idx, void *object); + +/** @} */ +/** @name 2. Perl-like functions + * @{ + */ + + void xbt_dynar_push (xbt_dynar_t dynar, const void *src); + void xbt_dynar_pop (xbt_dynar_t dynar, void *const dst); + void xbt_dynar_unshift (xbt_dynar_t dynar, const void *src); + void xbt_dynar_shift (xbt_dynar_t dynar, void *const dst); + void xbt_dynar_map (const xbt_dynar_t dynar, void_f_pvoid_t *operator); + +/** @} */ +/** @name 3. Manipulating pointers to the content + * + * Those functions do not retrive the content, but only their address. + * + * @{ + */ + + void *xbt_dynar_get_ptr(const xbt_dynar_t dynar, const int idx); + void *xbt_dynar_insert_at_ptr(xbt_dynar_t const dynar, const int idx); + void *xbt_dynar_push_ptr(xbt_dynar_t dynar); + void *xbt_dynar_pop_ptr(xbt_dynar_t dynar); + +/** @} */ +/** @name 4. Speed optimized functions for scalars + * + * While the other functions use a memcpy to retrive the content into the + * user provided area, those ones use a regular affectation. It only works + * for scalar values, but should be a little faster. + * + * @{ + */ + + /** @brief Quick retrieval of scalar content + * @hideinitializer */ +# define xbt_dynar_get_as(dynar,idx,type) \ + *(type*)xbt_dynar_get_ptr(dynar,idx) + /** @brief Quick insertion of scalar content + * @hideinitializer */ +# define xbt_dynar_insert_at_as(dynar,idx,type,value) \ + *(type*)xbt_dynar_insert_at_ptr(dynar,idx)=value + /** @brief Quick insertion of scalar content + * @hideinitializer */ +# define xbt_dynar_push_as(dynar,type,value) \ + *(type*)xbt_dynar_push_ptr(dynar)=value + /** @brief Quick insertion of scalar content + * @hideinitializer */ +# define xbt_dynar_pop_as(dynar,type) \ + *(type*)xbt_dynar_pop_ptr(dynar) + +/** @} */ +/** @name 5. Cursors on DynArr + * + * Cursors are used to iterate over the structure. Never add elements to the + * DynArr during the traversal. To remove elements, use the + * xbt_dynar_cursor_rm() function + * + * @{ + */ + + void xbt_dynar_cursor_first (const xbt_dynar_t dynar, int *cursor); + void xbt_dynar_cursor_step (const xbt_dynar_t dynar, int *cursor); + int xbt_dynar_cursor_get (const xbt_dynar_t dynar, int *cursor, + void *whereto); + void xbt_dynar_cursor_rm(xbt_dynar_t dynar, + int *const cursor); + + +/** @brief Iterates over the whole dynar. + * + * @param _dynar what to iterate over + * @param _cursor an integer used as cursor + * @param _data + * @hideinitializer * - * Iterates over the whole dynar. * \note An example of usage: * \code xbt_dynar_t dyn; @@ -91,14 +171,9 @@ xbt_dynar_foreach (dyn,cpt,str) { for (xbt_dynar_cursor_first(_dynar,&(_cursor)) ; \ xbt_dynar_cursor_get(_dynar,&(_cursor),&_data) ; \ xbt_dynar_cursor_step(_dynar,&(_cursor)) ) -/* - for (xbt_dynar_length(_dynar) && (_xbt_dynar_cursor_first(_dynar,&_cursor), \ - 1); \ - xbt_dynar_length(_dynar) && xbt_dynar_cursor_get(_dynar,&_cursor,&_data); \ - xbt_dynar_cursor_step(_dynar,&_cursor)) -*/ -void xbt_dynar_cursor_rm(xbt_dynar_t dynar, - int *const cursor); + END_DECL() + +/* @} */ #endif /* _XBT_DYNAR_H */