RTI Connext DDS Micro  Version 2.4.8
 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*
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.8 Copyright © Tue Apr 12 2016 Real-Time Innovations, Inc