RTI Connext DDS Micro  Version 2.4.11
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
reda_string.h
1 /*
2  * FILE: reda_string.h - String API
3  *
4  * Copyright 2012-2016 Real-Time Innovations, Inc.
5  *
6  * No duplications, whole or partial, manual or electronic, may be made
7  * without express written permission. Any such copies, or
8  * revisions thereof, must display this notice unaltered.
9  * This code contains trade secrets of Real-Time Innovations, Inc.
10  *
11  * Modification History
12  * --------------------
13  * 10feb2016,tk MICRO-1530 Unified REDA_StringSeq, CDR_StringSeq, and DDS_StringSeq
14  * 19may2015,as MICRO-1193 Refactoring of Sequence API levels
15  * 15may2014,as MICRO-317 (Verocel PR#1443) Added REDA_String_ncompare
16  * 20jul2012,tk Written
17  */
18 /*ci
19  * \file
20  *
21  * \brief The REDA string API provides commonly used functions to manipulate
22  * C style ASCIIZ strings beyond what OSAPI provides.
23  *
24  * \defgroup REDAStringClass REDA String
25  *
26  * \ingroup REDAModule
27  *
28  * \details
29  *
30  * TThe REDA string API provides frequently used functions to manipulate
31  * C ASCIIZ strings beyond what OSAPI provides. In general REDA does access
32  * platform dependent functions, but uses OSAPI ass the basis. The API
33  * defines the REDA_String_T as a convenience, but it is guaranteed to
34  * be compatible with char*
35  */
36 #ifndef reda_string_h
37 #define reda_string_h
38 
39 #ifndef reda_dll_h
40 #include "reda/reda_dll.h"
41 #endif
42 
43 #include "reda/reda_sequence.h"
44 
45 
46 #ifdef __cplusplus
47 extern "C"
48 {
49 #endif
50 /*ci
51  * \addtogroup REDAStringClass
52  * @{
53  */
54 
55 /*ci
56  * \brief Alias for char*
57  */
58 typedef char* REDA_String_T;
59 
60 /*
61  * define the REDA_StringSeq
62  */
63 #define T char*
64 #define TSeq REDA_StringSeq
65 #define REDA_SEQUENCE_USER_API
66 #define TSeq_is_equal
67 #define TSeq_isCDRStringType
68 #define TSeq_isCDRCharStringType
69 #include <reda/reda_sequence_decl.h>
70 
71 /*ci
72  * \def REDA_StringSeq_INITIALIZER
73  * \brief Initializer for REDA_StringSeq variables
74  */
75 #define REDA_StringSeq_INITIALIZER REDA_DEFINE_SEQUENCE_INITIALIZER(char*)
76 
77 /*ci
78  * \brief Allocate a string of length bytes, excluding the NULL character.
79  *
80  * \details
81  *
82  * Allocate a buffer to hold a string of length bytes, excluding the
83  * NULL termination.
84  *
85  * \param[in] length Length of string to allocate, does not include the
86  * NULL termination character.
87  *
88  * \return Valid buffer on success, NULL on failure
89  *
90  * \sa \ref REDA_String_free
91  */
92 MUST_CHECK_RETURN REDADllExport char*
93 REDA_String_alloc(RTI_SIZE_T length);
94 
95 #ifndef RTI_CERT
96 /*ci
97  * \brief Free a string buffer allocated with \ref REDA_String_alloc
98  *
99  * \details
100  *
101  * Free a string buffer allocated with \ref REDA_String_alloc
102  *
103  * \param[in] string String buffer to free
104  *
105  * \sa \ref REDA_String_alloc
106  */
107 REDADllExport void
108 REDA_String_free(char *string);
109 #endif /* !RTI_CERT */
110 
111 /*ci
112  * \brief Return the length of a string excluding the NULL termination
113  *
114  * \details
115  *
116  * Return the length of a string, does not include the NULL termination
117  *
118  * \param[in] string String buffer to return length of
119  *
120  * \return Return the length of the string excluding the NULL termination
121  */
122 REDADllExport RTI_SIZE_T
123 REDA_String_length(const char *string);
124 
125 /*ci
126  * \brief Return a duplicate of a string
127  *
128  * \details
129  *
130  * Allocate a new buffer and copy the content of a string.
131  *
132  * \param[in] string String to duplicate
133  *
134  * \return Returns a pointer to the duplicate string on success, NULL on failure
135  */
136 MUST_CHECK_RETURN REDADllExport char*
137 REDA_String_dup(const char *string);
138 
139 /*ci
140  * \brief Replace the content of a previously allocated string buffer
141  *
142  * \details
143  *
144  * This function replaces the content of a previously allocated string buffer.
145  * If the replacement string is longer than the previously allocated string
146  * a new buffer is allocated and the content copied.
147  *
148  * \param[in] string_ptr String to replace
149  * \param[in] new_value String replacement
150  *
151  * \return Returns a pointer to the replaced string on success, NULL on failure
152  */
153 MUST_CHECK_RETURN REDADllExport char*
154 REDA_String_replace(char **string_ptr, const char *new_value);
155 
156 /*ci
157  * \brief Compare two strings
158  *
159  * \details
160  *
161  * This function compares two strings for lexicographic equivalence.
162  *
163  * \param[in] left Left side of comparison
164  *
165  * \param[in] right Right side of comparison
166  *
167  * \return Returns 0 if left is == right, < 0 if left < right, > 0 if left > right
168  *
169  * \sa \ref REDA_String_ncompare
170  */
171 MUST_CHECK_RETURN REDADllExport RTI_INT32
172 REDA_String_compare(const char *left, const char *right);
173 
174 /*ci
175  * \brief Compare two strings
176  *
177  * \details
178  *
179  * This function compares two strings for lexicographic equivalence, but only
180  * up to num bytes.
181  *
182  * \param[in] left Left side of comparison
183  *
184  * \param[in] right Right side of comparison
185  *
186  * \param[in] num Maximum number of bytes to compare
187  *
188  * \return positive integer if left is greater than right,
189  * negative integer if left is less than right,
190  * zero if left is equal to right
191  *
192  * \sa \ref REDA_String_compare
193  */
194 MUST_CHECK_RETURN REDADllExport RTI_INT32
195 REDA_String_ncompare(const char *left, const char *right, RTI_SIZE_T num);
196 
197 /*ci
198  * \brief Copy a string into a buffer of maximum length
199  *
200  * \details
201  * Copy a NUL terminated string into a buffer with a maximum length. If the
202  * source string is to long, RTI_FALSE is returned.
203  *
204  * \param[in] dst Destination string buffer
205  * \param[in] max_length Maximum length (excluding NUL) of destination
206  * buffer
207  * \param[in] src Source string to copy
208  *
209  * \return Returns RTI_TRUE on success, RTI_FALSE on failure
210  */
211 REDADllExport RTI_BOOL
212 REDA_String_copy(char *dst,RTI_SIZE_T max_length,const char *src);
213 
214 #ifdef __cplusplus
215 } /* extern "C" */
216 #endif
217 
218 #endif /* reda_string_h */
219 
220 /*ci @} */
221 

RTI Connext DDS Micro Version 2.4.11 Copyright © Mon Jul 23 2018 Real-Time Innovations, Inc