rcutils  master
C API providing common utilities and data structures.
hash_map.h
Go to the documentation of this file.
1 // Copyright 2018-2019 Open Source Robotics Foundation, Inc.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef RCUTILS__TYPES__HASH_MAP_H_
16 #define RCUTILS__TYPES__HASH_MAP_H_
17 
18 #ifdef __cplusplus
19 extern "C"
20 {
21 #endif
22 
23 #include <string.h>
24 
25 #include "rcutils/allocator.h"
27 #include "rcutils/macros.h"
29 
30 struct rcutils_hash_map_impl_t;
31 
33 {
34  struct rcutils_hash_map_impl_t * impl;
36 
38 
42 typedef size_t (* rcutils_hash_map_key_hasher_t)(
43  const void * // key to hash
44 );
45 
47 
55  const void *, // val1
56  const void * // val2
57 );
58 
65 #define HASH_MAP_VALIDATE_HASH_MAP(map) \
66  RCUTILS_CHECK_ARGUMENT_FOR_NULL(map, RCUTILS_RET_INVALID_ARGUMENT); \
67  if (NULL == map->impl) { \
68  RCUTILS_SET_ERROR_MSG("map is not initialized"); \
69  return RCUTILS_RET_NOT_INITIALIZED; \
70  }
71 
73 
78 size_t
79 rcutils_hash_map_string_hash_func(const void * key_str);
80 
82 
87 int
88 rcutils_hash_map_string_cmp_func(const void * val1, const void * val2);
89 
91 /*
92  * This function returns an empty and zero initialized hash_map struct.
93  * All hash maps should be initialized with this or manually initialized
94  * before being used.
95  *
96  * <hr>
97  * Attribute | Adherence
98  * ------------------ | -------------
99  * Allocates Memory | No
100  * Thread-Safe | No
101  * Uses Atomics | No
102  * Lock-Free | Yes
103  *
104  * Example:
105  * ```c
106  * // Do not do this:
107  * // rcutils_hash_map_t foo;
108  * // rcutils_hash_map_fini(&foo); // undefined behavior!
109  *
110  * // Do this instead:
111  * rcutils_hash_map_t bar = rcutils_get_zero_initialized_hash_map();
112  * rcutils_hash_map_fini(&bar); // ok
113  * ```
114  * */
119 
121 
171  rcutils_hash_map_t * hash_map,
172  size_t initial_capacity,
173  size_t key_size,
174  size_t data_size,
175  rcutils_hash_map_key_hasher_t key_hashing_func,
176  rcutils_hash_map_key_cmp_t key_cmp_func,
177  const rcutils_allocator_t * allocator);
178 
180 
201 
203 
229 rcutils_hash_map_get_capacity(const rcutils_hash_map_t * hash_map, size_t * capacity);
230 
232 
255 rcutils_hash_map_get_size(const rcutils_hash_map_t * hash_map, size_t * size);
256 
258 
283 rcutils_hash_map_set(rcutils_hash_map_t * hash_map, const void * key, const void * value);
284 
286 
310 rcutils_hash_map_unset(rcutils_hash_map_t * hash_map, const void * key);
311 
313 
334 bool
335 rcutils_hash_map_key_exists(const rcutils_hash_map_t * hash_map, const void * key);
336 
338 
362 rcutils_hash_map_get(const rcutils_hash_map_t * hash_map, const void * key, void * data);
363 
365 
412  const rcutils_hash_map_t * hash_map,
413  const void * previous_key,
414  void * key,
415  void * data);
416 
417 
418 #ifdef __cplusplus
419 }
420 #endif
421 
422 #endif // RCUTILS__TYPES__HASH_MAP_H_
bool rcutils_hash_map_key_exists(const rcutils_hash_map_t *hash_map, const void *key)
Get whether or not a key exists.
rcutils_ret_t rcutils_hash_map_init(rcutils_hash_map_t *hash_map, size_t initial_capacity, size_t key_size, size_t data_size, rcutils_hash_map_key_hasher_t key_hashing_func, rcutils_hash_map_key_cmp_t key_cmp_func, const rcutils_allocator_t *allocator)
Initialize a rcutils_hash_map_t, allocating space for given capacity.
int(* rcutils_hash_map_key_cmp_t)(const void *, const void *)
The function signature for a key comparison function.
Definition: hash_map.h:54
int rcutils_ret_t
Definition: rcutils_ret.h:23
size_t(* rcutils_hash_map_key_hasher_t)(const void *)
The function signature for a key hashing function.
Definition: hash_map.h:42
rcutils_ret_t rcutils_hash_map_get_size(const rcutils_hash_map_t *hash_map, size_t *size)
Get the current size of the hash_map.
struct rcutils_hash_map_impl_t * impl
Definition: hash_map.h:34
Definition: hash_map.h:32
#define RCUTILS_PUBLIC_TYPE
Definition: visibility_control.h:51
rcutils_hash_map_t rcutils_get_zero_initialized_hash_map()
Return an empty hash_map struct.
Encapsulation of an allocator.
Definition: allocator.h:45
struct rcutils_hash_map_t rcutils_hash_map_t
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.
rcutils_ret_t rcutils_hash_map_get(const rcutils_hash_map_t *hash_map, const void *key, void *data)
Get value given a key.
size_t rcutils_hash_map_string_hash_func(const void *key_str)
A hashing function for a null terminated c string.
int rcutils_hash_map_string_cmp_func(const void *val1, const void *val2)
A comparison function for a null terminated c string.
#define RCUTILS_WARN_UNUSED
Definition: macros.h:24
#define RCUTILS_PUBLIC
Definition: visibility_control.h:48
rcutils_ret_t rcutils_hash_map_set(rcutils_hash_map_t *hash_map, const void *key, const void *value)
Set a key value pair in the hash_map, increasing capacity if necessary.
rcutils_ret_t rcutils_hash_map_get_capacity(const rcutils_hash_map_t *hash_map, size_t *capacity)
Get the current capacity of the hash_map.
rcutils_ret_t rcutils_hash_map_unset(rcutils_hash_map_t *hash_map, const void *key)
Unset a key value pair in the hash_map.
rcutils_ret_t rcutils_hash_map_fini(rcutils_hash_map_t *hash_map)
Finalize the previously initialized hash_map struct.