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

RTI Connext DDS Micro Version 2.4.6 Copyright © Sun Jan 24 2016 Real-Time Innovations, Inc