RTI Connext DDS Micro
Version 2.4.10
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-2016.
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
/* ----------------------------------------------------------------- */
127
/*e @ingroup DDSStringClass
128
*
129
* @brief Create a new empty string that can hold up to \p length
130
* characters.
131
*
132
* @details
133
* A string created by this \method must be deleted using
134
* DDS_String_free().
135
*
136
* This function will allocate enough memory to hold a string of
137
* \p length characters, \b plus one additional byte to hold the NULL
138
* terminating character.
139
*
140
* @param length \st_in Capacity of the string.
141
*
142
* @return A newly created non-NULL string upon success or
143
* NULL upon failure.
144
*/
145
DDSCDllExport
char
*
146
DDS_String_alloc
(
DDS_UnsignedLong
length);
147
148
#define DDS_String_alloc(l_) REDA_String_alloc(l_)
149
150
/* ----------------------------------------------------------------- */
151
/*e @ingroup DDSStringClass
152
*
153
* @brief Clone a string. Creates a new string that duplicates
154
* the value of \p string.
155
*
156
* @details
157
* A string created by this \method must be deleted using
158
* DDS_String_free()
159
*
160
* @param str \st_in The string to duplicate.
161
*
162
* @return If \p string == NULL, this \method always returns NULL.
163
* Otherwise, upon success it returns a newly created string
164
* whose value is \p string; upon failure it returns NULL.
165
*/
166
DDSCDllExport
char
*
167
DDS_String_dup
(
const
char
*str);
168
169
#define DDS_String_dup(str_) REDA_String_dup(str_)
170
171
/* ----------------------------------------------------------------- */
172
/*i @ingroup DDSStringClass
173
*
174
* @brief Assign a string to a new value.
175
*
176
* @details
177
* Replaces the string
178
* pointed to by \p string_ptr, with a string whose value
179
* is \p new_value.
180
*
181
* A string created by this \method must be deleted using
182
* DDS_String_free().
183
*
184
* @pre \p string_ptr be a non-NULL pointer. *string_ptr must be
185
* either NULL, or a string created using DDS_String_alloc()
186
* or DDS_String_dup(), or DDS_String_replace().
187
*
188
* @param string_ptr \st_inout Pointer to the string to replace.
189
*
190
* @param new_value \st_in The value of the replacement string.
191
*
192
* @return If \p new_value = NULL, this \method always returns NULL.
193
* Otherwise, upon success it returns *string_ptr whose value
194
* is \p new_value; upon failure it returns NULL.
195
*
196
* @post If \p new_value = NULL, *string_ptr == NULL.
197
* Otherwise, upon success \p string_ptr contains a pointer
198
* to a string whose value is \p new_value; upon failure,
199
* \p string_ptr is left unchanged.
200
*/
201
DDSCDllExport
char
*
202
DDS_String_replace(
char
**string_ptr,
const
char
*new_value);
203
204
#define DDS_String_replace(str_,val_) REDA_String_replace(str_,val_)
205
206
/* ----------------------------------------------------------------- */
207
#ifndef RTI_CERT
208
/*e @ingroup DDSStringClass
209
*
210
* @brief Delete a string.
211
*
212
* @pre \p string must be either NULL, or must have been created
213
* using DDS_String_alloc(), DDS_String_dup()
214
*
215
* @param str \st_in The string to delete.
216
* @internal String could also have been created with DDS_String_replace()
217
*/
218
DDSCDllExport
void
219
DDS_String_free
(
char
*str);
220
#endif
/* !RTI_CERT */
221
222
#ifndef RTI_CERT
223
#define DDS_String_free(str_) REDA_String_free(str_)
224
#else
225
#define DDS_String_free(str_)
226
#endif
/* !RTI_CERT */
227
/* ----------------------------------------------------------------- */
228
/*e @ingroup DDSStringClass
229
*
230
* @brief Compare two strings.
231
*
232
* @pre \p s1 and s2 can be NULL or non-NULL.
233
*
234
* @param s1 \st_in String 1 to compare.
235
* @param s2 \st_in String 2 to compare.
236
*
237
* @return 0 if s1 equals s2,
238
* positive integer if s1 is greater than s2,
239
* negative integer if s1 is less than s2
240
*/
241
DDSCDllExport
int
242
DDS_String_cmp
(
const
char
*s1,
const
char
*s2);
243
#define DDS_String_cmp(str1_,str2_) REDA_String_compare(str1_,str2_)
244
245
/*e @ingroup DDSStringClass
246
*
247
* @brief Compare two strings.
248
*
249
* \details
250
*
251
* This function compares two strings for lexicographic equivalence, but only
252
* up to num bytes.
253
254
* \param[in] s1 \st_in Left side of comparison
255
* \param[in] s2 \st_in Right side of comparison
256
* \param[in] num Maximum number of bytes 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_ncmp
(
const
char
*s1,
const
char
*s2,
DDS_UnsignedLong
num);
264
#define DDS_String_ncmp(str1_,str2_,num_) REDA_String_ncompare(str1_,str2_,num_)
265
266
/* ----------------------------------------------------------------- */
267
/*e @ingroup DDSStringClass
268
*
269
* @brief Return the length of a string
270
*
271
* @pre \p string must be non-NULL
272
*
273
* @param string \st_in String to return length of
274
*
275
* @return length of string. Does not include the NUL-termination character.
276
* If a NULL value is passed as argument, RTI_SIZE_INVALID will be returned.
277
*/
278
DDSCDllExport
int
279
DDS_String_length
(
const
char
*
string
);
280
#define DDS_String_length(str1_) REDA_String_length(str1_)
281
282
#ifdef __cplusplus
283
}
/* extern "C" */
284
#endif
285
286
287
#endif
/* dds_c_string_h */
RTI Connext DDS Micro Version 2.4.10
Copyright © Fri Jun 30 2017
Real-Time Innovations, Inc