SimGrid: Cursors on dictionaries

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
Data Structures | Macros | Functions
Cursors on dictionaries
Dict: generic dictionnary

## Data Structures
struct | s_xbt_dict_cursor
| Cursor on dictionaries (opaque type) More...

## Macros
#define | xbt_dict_foreach(dict, cursor, key, data)

## Functions
xbt_dict_cursor_t | xbt_dict_cursor_new (const xbt_dict_t dict)
| Creator.
void | xbt_dict_cursor_free (xbt_dict_cursor_t *cursor)
| Destructor.
void | xbt_dict_cursor_rewind (xbt_dict_cursor_t cursor)
| Reinitialize the cursor. Mandatory after removal or add in dict.
char * | xbt_dict_cursor_get_key (xbt_dict_cursor_t cursor)
| Get current key.
void * | xbt_dict_cursor_get_data (xbt_dict_cursor_t cursor)
| Get current data.
void | xbt_dict_cursor_set_data (xbt_dict_cursor_t cursor, void *data, void_f_pvoid_t free_ctn)
| Set current data.
void | xbt_dict_cursor_first (const xbt_dict_t dict, xbt_dict_cursor_t *cursor)
| Create the cursor if it does not exists. Rewind it in any case.
void | xbt_dict_cursor_step (xbt_dict_cursor_t cursor)
| Move to the next element.
int | xbt_dict_cursor_get_or_free (xbt_dict_cursor_t *cursor, char **key, void **data)
| Get current data, or free the cursor if there is no data left.

## Detailed Description

    Don't get impressed, there is a lot of functions here, but traversing a
    dictionary is immediate with the xbt_dict_foreach macro.
    You only need the other functions in rare cases (they are not used directly in SG itself).

    Here is an example (assuming that the dictionary contains strings, ie
    that the <tt>data</tt> argument of xbt_dict_set was always a null-terminated char*):

    xbt_dict_cursor_t cursor=NULL;
     char *key,*data;

     xbt_dict_foreach(dict,cursor,key,data) {
        printf("   - Seen:  %s->%s\n",key,data);
     }

Warning
  Do not add or remove entries to the cache while traversing !!

## Macro Definition Documentation

#define xbt_dict_foreach | ( |  | dict,
|  |  | cursor,
|  |  | key,
|  |  | data
| ) |  |

    @param dict a \ref xbt_dict_t iterator
    @param cursor an \ref xbt_dict_cursor_t used as cursor
    @param key a char*
    @param data a void** output

Note
  An example of usage:
  xbt_dict_cursor_t cursor = NULL;
  char *key;
  char *data;
  xbt_dict_foreach(head, cursor, key, data) {
  printf("Key %s with data %s\n",key,data);
  }

## Function Documentation

xbt_dict_cursor_t xbt_dict_cursor_new | ( | const xbt_dict_t | dict | ) |

Creator.

Parameters

  dict | the dict

void xbt_dict_cursor_free | ( | xbt_dict_cursor_t * | cursor | ) |

Destructor.

Parameters

  cursor | poor victim

char* xbt_dict_cursor_get_key | ( | xbt_dict_cursor_t | cursor | ) |

Get current key.

Parameters

  cursor,: | the cursor

Returns
  the current key

void* xbt_dict_cursor_get_data | ( | xbt_dict_cursor_t | cursor | ) |

Get current data.

Parameters

  cursor | the cursor

Returns
  the current data

void xbt_dict_cursor_set_data | ( | xbt_dict_cursor_t | cursor,
|  | void * | data,
|  | void_f_pvoid_t | free_ctn
| ) |  |

Set current data.

Parameters

  cursor | the cursor
  data | the new data
  free_ctn | the function to free the new data

void xbt_dict_cursor_first | ( | const xbt_dict_t | dict,
|  | xbt_dict_cursor_t * | cursor
| ) |  |

Create the cursor if it does not exists. Rewind it in any case.

Parameters

  | dict | on what to let the cursor iterate
  [out] | cursor | dest address

int xbt_dict_cursor_get_or_free | ( | xbt_dict_cursor_t * | cursor,
|  | char ** | key,
|  | void ** | data
| ) |  |

Get current data, or free the cursor if there is no data left.

Returns
  true if it's ok, false if there is no more data