Function rcutils_string_map_get_next_key

Function Documentation

const char *rcutils_string_map_get_next_key(const rcutils_string_map_t *string_map, const char *key)

Get the next key in the map, unless NULL is given, then get the first key.

This function allows you iteratively get each key in the map.

If NULL is given for the key, then the first key in the map is returned. If that returned key if given to the this function, then the next key in the map is returned. If there are no more keys in the map or if the given key is not in the map, NULL is returned.

The order of the keys in the map is arbitrary and if the map is modified between calls to this function the behavior is undefined. If the map is modifeid then iteration should begin again by passing NULL to get the first key again.

This function operates based on the address of the pointer, you cannot pass a copy of a key to get the next key.

Example:

printf("keys in the map:\n");
const char * current_key = rcutils_string_map_get_next_key(&map, NULL);
while (current_key) {
  printf("  - %s\n", current_key);
  current_key = rcutils_string_map_get_next_key(&map, current_key);
}

NULL can also be returned if NULL is given for the string_map or if the string_map is invalid.

Parameters:

  • string_map – [in] rcutils_string_map_t to be queried

  • key – [in] NULL to get the first key or the previous key to get the next

Returns:

value for the given key if successful, or

Returns:

NULL for invalid arguments, or

Returns:

NULL if the string map is invalid, or

Returns:

NULL if key not found, or

Returns:

NULL if there are no more keys in the map, or

Returns:

NULL if an unknown error occurs.