Function rcutils_hash_map_get_next_key_and_data

Function Documentation

rcutils_ret_t rcutils_hash_map_get_next_key_and_data(const rcutils_hash_map_t *hash_map, const void *previous_key, void *key, void *data)

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

This function allows you to iteratively get each key/value pair in the hash_map.

If NULL is given for the previous_key, then the first key in the hash_map is returned. If that returned key is given as the previous_key for the next call to this function, then the next key in the hash_map is returned. If there are no more keys in the hash_map or if the given key is not in the hash_map, an error will be returned.

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

Attribute

Adherence

Allocates Memory

No

Thread-Safe

No

Uses Atomics

No

Lock-Free

Yes

Example: 

printf("entries in the hash_map:\n");
int key = 0, data = 0;
rcutils_ret_t status = rcutils_hash_map_get_next_key(&hash_map, NULL, &key, &data);
while (RCUTILS_RET_OK == status) {
  printf("%i: %i\n", key, data);
  status = rcutils_hash_map_get_next_key(&hash_map, &key, &key, &data);
}

Parameters:

  • hash_map – [in] rcutils_hash_map_t to be queried

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

  • key – [out] A copy of the next key in the sequence

  • data – [out] A copy of the next data in the sequence

Returns:

RCUTILS_RET_OK if successful, or

Returns:

RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or

Returns:

RCUTILS_RET_NOT_INITIALIZED if the hash_map is invalid, or

Returns:

RCUTILS_RET_NOT_FOUND if the previous_key doesn’t exist in the map, or

Returns:

RCUTILS_RET_HASH_MAP_NO_MORE_ENTRIES if there is no more data beyound the previous_key, or

Returns:

RCUTILS_RET_ERROR if an unknown error occurs.