RTI Connext DDS Micro
Version 2.4.6
Main Page
Related Pages
Manuals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
dds_c_string.h
Go to the documentation of this file.
1
/*
2
* FILE: dds_c_string.h - DDS string definitions
3
*
4
* (c) Copyright, Real-Time Innovations, 2012-2015.
5
*
6
* All rights reserved.
7
*
8
* No duplications, whole or partial, manual or electronic, may be made
9
* without express written permission. Any such copies, or
10
* revisions thereof, must display this notice unaltered.
11
* This code contains trade secrets of Real-Time Innovations, Inc.
12
*
13
* Modification History
14
* --------------------
15
* 15may2014,as MICRO-317 (Verocel PR#1443) Added DDS_String_ncmp
16
* 08jun2012,tk Written
17
*/
18
/*ce
19
* \file
20
* \brief DDS string definitions
21
*/
22
23
/* ================================================================== */
24
/* Class: String */
25
/* ================================================================== */
26
/*e @addtogroup DDSStringClass String Support
27
@ingroup DDSInfrastructureModule
28
@brief String creation, cloning, assignment, and deletion.
29
30
The \methods in this class ensure consistent cross-platform
31
implementations for string creation (DDS_String_alloc()), deletion
32
(DDS_String_free()), and cloning (DDS_String_dup()) that preserve the
33
mutable value type semantics. These are to be viewed as \methods that
34
define a \p string class whose data is represented by a \c 'char*'.
35
36
@section DDSStringClass_conventions Conventions
37
38
The following conventions govern the memory management of strings in \ndds.
39
40
<ul>
41
<li>The \dds implementation ensures that when value types containing
42
strings are passed back and forth to the DDS APIs, the strings
43
are created/deleted/assigned/cloned using the \p string class
44
\methods.
45
<ul>
46
<li>Value types containing strings have ownership of the
47
contained string. Thus, when a value type is deleted, the
48
contained string field is also deleted.</li>
49
</ul></li>
50
<li>The user must ensure that when value types containing
51
strings are passed back and forth to the DDS APIs, the strings
52
are created/deleted/assigned/cloned using the String class \methods.
53
</li>
54
</ul>
55
56
The representation of a string in C/C++ unfortunately does not allow
57
programs to detect how much memory has been allocated for a string. \ndds
58
must therefore make some assumptions when a user requests that a string be
59
copied into. The following rules apply when \ndds is copying into a string
60
or string sequence:
61
62
\li If the 'char*' is NULL, \ndds will log a warning and allocate a new
63
string on behalf of the user. <i>To avoid leaking memory, you must
64
ensure that the string will be freed (see \ref DDSStringClass_usage
65
below)</i>.
66
\li If the 'char*' is not NULL, \ndds will assume that you are managing the
67
string's memory yourself and have allocated enough memory to store the
68
string to be copied. <i>\ndds will copy into your memory; to avoid
69
memory corruption, be sure to allocate enough of it.</i> Also, <i>do
70
not pass structures containing junk pointers into \ndds</i>; you are
71
likely to crash.
72
73
@section DDSStringClass_usage Usage
74
75
This requirement can generally be assured by adhering
76
to the following \em idiom for manipulating strings.
77
78
\code
79
Always use
80
DDS_String_alloc() to create,
81
DDS_String_dup() to clone,
82
DDS_String_free() to delete
83
a string 'char*' that is passed back and forth between
84
user code and the DDS C/C++ APIs.
85
\endcode
86
87
Not adhering to this idiom can result in bad pointers, and incorrect
88
memory being freed.
89
90
In addition, the user code should be vigilant to avoid memory leaks.
91
It is good practice to:
92
93
\li Balance occurrences of DDS_String_alloc(), DDS_String_dup(),
94
with matching occurrences of DDS_String_free() in the code.
95
\li Finalize value types containing strings. In C++ the destructor
96
accomplishes this automatically. in C, explicit "destructor" functions
97
are provided; these functions are typically called "finalize."
98
99
*/
100
101
/* ================================================================= */
102
/*i @file
103
@ingroup String
104
@brief Defines the String facilities.
105
*/
106
#ifndef dds_c_string_h
107
#define dds_c_string_h
108
109
110
111
#ifndef dds_c_dll_h
112
#include "
dds_c/dds_c_dll.h
"
113
#endif
114
#ifndef dds_c_common_h
115
#include "
dds_c/dds_c_common.h
"
116
#endif
117
#ifndef dds_c_sequence_h
118
#include "
dds_c/dds_c_sequence.h
"
119
#endif
120
121
#ifdef __cplusplus
122
extern
"C"
123
{
124
#endif
125
126
#define DDS_StringSeq REDA_StringSeq
127
#define DDS_StringSeq_initialize REDA_StringSeq_initialize
128
#define DDS_StringSeq_finalize REDA_StringSeq_finalize
129
#define DDS_StringSeq_get_maximum REDA_StringSeq_get_maximum
130
#define DDS_StringSeq_set_maximum REDA_StringSeq_set_maximum
131
#define DDS_StringSeq_set_length REDA_StringSeq_set_length
132
#define DDS_StringSeq_get_length REDA_StringSeq_get_length
133
#define DDS_StringSeq_get_reference REDA_StringSeq_get_reference
134
#define DDS_StringSeq_copy REDA_StringSeq_copy
135
#define DDS_StringSeq_is_equal REDA_StringSeq_is_equal
136
#define DDS_StringSeq_loan_contiguous REDA_StringSeq_loan_contiguous
137
#define DDS_StringSeq_loan_discontiguous REDA_StringSeq_loan_discontiguous
138
#define DDS_StringSeq_unloan REDA_StringSeq_unloan
139
#define DDS_StringSeq_has_ownership REDA_StringSeq_has_ownership
140
#define DDS_StringSeq_get_contiguous_buffer REDA_StringSeq_get_contiguous_buffer
141
#define DDS_StringSeq_set_contiguous_buffer REDA_StringSeq_set_contiguous_buffer
142
#define DDS_StringSeq_has_discontiguous_buffer REDA_StringSeq_has_discontiougous_buffer
143
#define DDS_StringSeq_ensure_length REDA_StringSeq_ensure_length
144
#define DDS_StringSeq_to_array REDA_StringSeq_to_array
145
#define DDS_StringSeq_from_array REDA_StringSeq_from_array
146
147
/* ----------------------------------------------------------------- */
148
/*e @ingroup DDSStringClass
149
*
150
* @brief Create a new empty string that can hold up to \p length
151
* characters.
152
*
153
* @details
154
* A string created by this \method must be deleted using
155
* DDS_String_free().
156
*
157
* This function will allocate enough memory to hold a string of
158
* \p length characters, \b plus one additional byte to hold the NULL
159
* terminating character.
160
*
161
* @param length \st_in Capacity of the string.
162
*
163
* @return A newly created non-NULL string upon success or
164
* NULL upon failure.
165
*/
166
DDSCDllExport
char
*
167
DDS_String_alloc
(
DDS_UnsignedLong
length);
168
169
#define DDS_String_alloc(l_) REDA_String_alloc(l_)
170
171
/* ----------------------------------------------------------------- */
172
/*e @ingroup DDSStringClass
173
*
174
* @brief Clone a string. Creates a new string that duplicates
175
* the value of \p string.
176
*
177
* @details
178
* A string created by this \method must be deleted using
179
* DDS_String_free()
180
*
181
* @param str \st_in The string to duplicate.
182
*
183
* @return If \p string == NULL, this \method always returns NULL.
184
* Otherwise, upon success it returns a newly created string
185
* whose value is \p string; upon failure it returns NULL.
186
*/
187
DDSCDllExport
char
*
188
DDS_String_dup
(
const
char
*str);
189
190
#define DDS_String_dup(str_) REDA_String_dup(str_)
191
192
/* ----------------------------------------------------------------- */
193
/*i @ingroup DDSStringClass
194
*
195
* @brief Assign a string to a new value.
196
*
197
* @details
198
* Replaces the string
199
* pointed to by \p string_ptr, with a string whose value
200
* is \p new_value.
201
*
202
* A string created by this \method must be deleted using
203
* DDS_String_free().
204
*
205
* @pre \p string_ptr be a non-NULL pointer. *string_ptr must be
206
* either NULL, or a string created using DDS_String_alloc()
207
* or DDS_String_dup(), or DDS_String_replace().
208
*
209
* @param string_ptr \st_inout Pointer to the string to replace.
210
*
211
* @param new_value \st_in The value of the replacement string.
212
*
213
* @return If \p new_value = NULL, this \method always returns NULL.
214
* Otherwise, upon success it returns *string_ptr whose value
215
* is \p new_value; upon failure it returns NULL.
216
*
217
* @post If \p new_value = NULL, *string_ptr == NULL.
218
* Otherwise, upon success \p string_ptr contains a pointer
219
* to a string whose value is \p new_value; upon failure,
220
* \p string_ptr is left unchanged.
221
*/
222
DDSCDllExport
char
*
223
DDS_String_replace(
char
**string_ptr,
const
char
*new_value);
224
225
#define DDS_String_replace(str_,val_) REDA_String_replace(str_,val_)
226
227
/* ----------------------------------------------------------------- */
228
#ifndef RTI_CERT
229
/*e @ingroup DDSStringClass
230
*
231
* @brief Delete a string.
232
*
233
* @pre \p string must be either NULL, or must have been created
234
* using DDS_String_alloc(), DDS_String_dup()
235
*
236
* @param str \st_in The string to delete.
237
* @internal String could also have been created with DDS_String_replace()
238
*/
239
DDSCDllExport
void
240
DDS_String_free
(
char
*str);
241
#endif
/* !RTI_CERT */
242
243
#ifndef RTI_CERT
244
#define DDS_String_free(str_) REDA_String_free(str_)
245
#else
246
#define DDS_String_free(str_)
247
#endif
/* !RTI_CERT */
248
/* ----------------------------------------------------------------- */
249
/*e @ingroup DDSStringClass
250
*
251
* @brief Compare two strings.
252
*
253
* @pre \p s1 and s2 can be NULL or non-NULL.
254
*
255
* @param s1 \st_in String 1 to compare.
256
* @param s2 \st_in String 2 to compare.
257
*
258
* @return 0 if s1 equals s2,
259
* positive integer if s1 is greater than s2,
260
* negative integer if s1 is less than s2
261
*/
262
DDSCDllExport
int
263
DDS_String_cmp
(
const
char
*s1,
const
char
*s2);
264
#define DDS_String_cmp(str1_,str2_) REDA_String_compare(str1_,str2_)
265
266
/*e @ingroup DDSStringClass
267
*
268
* @brief Compare two strings.
269
*
270
* \details
271
*
272
* This function compares two strings for lexicographic equivalence, but only
273
* up to num bytes.
274
275
* \param[in] s1 \st_in Left side of comparison
276
* \param[in] s2 \st_in Right side of comparison
277
* \param[in] num Maximum number of bytes to compare
278
*
279
* @return 0 if s1 equals s2,
280
* positive integer if s1 is greater than s2,
281
* negative integer if s1 is less than s2
282
*/
283
DDSCDllExport
int
284
DDS_String_ncmp
(
const
char
*s1,
const
char
*s2,
DDS_UnsignedLong
num);
285
#define DDS_String_ncmp(str1_,str2_,num_) REDA_String_ncompare(str1_,str2_,num_)
286
287
/* ----------------------------------------------------------------- */
288
/*e @ingroup DDSStringClass
289
*
290
* @brief Return the length of a string
291
*
292
* @pre \p string must be non-NULL
293
*
294
* @param string \st_in String to return length of
295
*
296
* @return length of string. Does not include the NUL-termination character.
297
* If a NULL value is passed as argument, RTI_SIZE_INVALID will be returned.
298
*/
299
DDSCDllExport
int
300
DDS_String_length
(
const
char
*
string
);
301
#define DDS_String_length(str1_) REDA_String_length(str1_)
302
303
#ifdef __cplusplus
304
}
/* extern "C" */
305
#endif
306
307
308
#endif
/* dds_c_string_h */
RTI Connext DDS Micro Version 2.4.6
Copyright © Sun Jan 24 2016
Real-Time Innovations, Inc