rcutils  master
C API providing common utilities and data structures.
string_array.h
Go to the documentation of this file.
1 // Copyright 2017 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 
16 
17 #ifndef RCUTILS__TYPES__STRING_ARRAY_H_
18 #define RCUTILS__TYPES__STRING_ARRAY_H_
19 
20 #ifdef __cplusplus
21 extern "C"
22 {
23 #endif
24 
25 #include <string.h>
26 
27 #include "rcutils/allocator.h"
28 #include "rcutils/error_handling.h"
29 #include "rcutils/macros.h"
30 #include "rcutils/qsort.h"
31 #include "rcutils/types/rcutils_ret.h"
32 #include "rcutils/visibility_control.h"
33 
35 typedef struct RCUTILS_PUBLIC_TYPE rcutils_string_array_t
36 {
38  size_t size;
39 
41  char ** data;
42 
44  rcutils_allocator_t allocator;
45 } rcutils_string_array_t;
46 
48 
65 RCUTILS_PUBLIC
66 rcutils_string_array_t
67 rcutils_get_zero_initialized_string_array(void);
68 
70 
98 RCUTILS_PUBLIC
99 RCUTILS_WARN_UNUSED
100 rcutils_ret_t
101 rcutils_string_array_init(
102  rcutils_string_array_t * string_array,
103  size_t size,
104  const rcutils_allocator_t * allocator);
105 
107 
119 RCUTILS_PUBLIC
120 RCUTILS_WARN_UNUSED
121 rcutils_ret_t
122 rcutils_string_array_fini(rcutils_string_array_t * string_array);
123 
125 
138 RCUTILS_PUBLIC
139 RCUTILS_WARN_UNUSED
140 rcutils_ret_t
141 rcutils_string_array_cmp(
142  const rcutils_string_array_t * lhs,
143  const rcutils_string_array_t * rhs,
144  int * res);
145 
147 
168 RCUTILS_PUBLIC
169 RCUTILS_WARN_UNUSED
170 rcutils_ret_t
171 rcutils_string_array_resize(
172  rcutils_string_array_t * string_array,
173  size_t new_size);
174 
176 
186 RCUTILS_PUBLIC
187 RCUTILS_WARN_UNUSED
188 int
189 rcutils_string_array_sort_compare(const void * lhs, const void * rhs);
190 
192 
202 inline
203 RCUTILS_WARN_UNUSED
204 rcutils_ret_t
205 rcutils_string_array_sort(rcutils_string_array_t * string_array)
206 {
207  RCUTILS_CHECK_FOR_NULL_WITH_MSG(
208  string_array, "string_array is null", return RCUTILS_RET_INVALID_ARGUMENT);
209 
210  return rcutils_qsort(
211  string_array->data,
212  string_array->size,
213  sizeof(string_array->data[0]),
214  rcutils_string_array_sort_compare);
215 }
216 
217 #ifdef __cplusplus
218 }
219 #endif
220 
221 #endif // RCUTILS__TYPES__STRING_ARRAY_H_
rcutils_string_array_t::allocator
rcutils_allocator_t allocator
The allocator used to allocate and free memory for the string array.
Definition: string_array.h:44
macros.h
rcutils_string_array_t
The structure holding the metadata for a string array.
Definition: string_array.h:35
rcutils_string_array_sort_compare
int rcutils_string_array_sort_compare(const void *lhs, const void *rhs)
Lexicographic comparer for pointers to string pointers.
RCUTILS_PUBLIC_TYPE
#define RCUTILS_PUBLIC_TYPE
Definition: visibility_control.h:29
RCUTILS_RET_INVALID_ARGUMENT
#define RCUTILS_RET_INVALID_ARGUMENT
Invalid argument return code.
Definition: rcutils_ret.h:38
RCUTILS_CHECK_FOR_NULL_WITH_MSG
#define RCUTILS_CHECK_FOR_NULL_WITH_MSG(value, msg, error_statement)
Check a value for null, with an error message and error statement.
Definition: error_handling.h:218
rcutils_ret_t
int rcutils_ret_t
The type that holds a return value for an rcutils operation.
Definition: rcutils_ret.h:26
qsort.h
rcutils_string_array_sort
rcutils_ret_t rcutils_string_array_sort(rcutils_string_array_t *string_array)
Sort a string array according to lexicographical order.
Definition: string_array.h:205
rcutils_string_array_cmp
rcutils_ret_t rcutils_string_array_cmp(const rcutils_string_array_t *lhs, const rcutils_string_array_t *rhs, int *res)
Compare two string arrays.
RCUTILS_WARN_UNUSED
#define RCUTILS_WARN_UNUSED
A macro to make the compiler warn when the return value of a function is not used.
Definition: macros.h:27
rcutils_ret.h
rcutils_string_array_fini
rcutils_ret_t rcutils_string_array_fini(rcutils_string_array_t *string_array)
Finalize a string array, reclaiming all resources.
visibility_control.h
error_handling.h
rcutils_allocator_t
Encapsulation of an allocator.
Definition: allocator.h:47
allocator.h
rcutils_get_zero_initialized_string_array
rcutils_string_array_t rcutils_get_zero_initialized_string_array(void)
Return an empty string array struct.
rcutils_string_array_resize
rcutils_ret_t rcutils_string_array_resize(rcutils_string_array_t *string_array, size_t new_size)
Resize a string array, reclaiming removed resources.
RCUTILS_PUBLIC
#define RCUTILS_PUBLIC
Definition: visibility_control.h:23
rcutils_string_array_init
rcutils_ret_t rcutils_string_array_init(rcutils_string_array_t *string_array, size_t size, const rcutils_allocator_t *allocator)
Initialize a string array with a given size.
rcutils_string_array_t
struct rcutils_string_array_t rcutils_string_array_t
The structure holding the metadata for a string array.
rcutils_string_array_t::size
size_t size
The number of strings that can be stored in the string array.
Definition: string_array.h:38
rcutils_qsort
rcutils_ret_t rcutils_qsort(void *ptr, size_t count, size_t size, int(*comp)(const void *, const void *))
Interface to qsort with rcutils-style argument validation.
rcutils_string_array_t::data
char ** data
The allocated memory for the string array.
Definition: string_array.h:41
Generated by   doxygen 1.8.17