RTI Connext Micro  Version 2.4.1.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
reda_string.h
1 /*
2  * FILE: reda_string.h - String API
3  *
4  * Copyright 2012-2014 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  * 15may2014,as MICRO-317 (Verocel PR#1443) Added REDA_String_ncompare
14  * 20jul2012,tk Written
15  */
16 /*ci
17  * \file
18  *
19  * \brief The REDA string API provides commonly used functions to manipulate
20  * C style ASCIIZ strings beyond what OSAPI provides.
21  *
22  * \defgroup REDAStringClass REDA String
23  *
24  * \ingroup REDAModule
25  *
26  * \details
27  *
28  * TThe REDA string API provides frequently used functions to manipulate
29  * C ASCIIZ strings beyond what OSAPI provides. In general REDA does access
30  * platform dependent functions, but uses OSAPI ass the basis. The API
31  * defines the REDA_String_T as a convenience, but it is guaranteed to
32  * be compatible with char*
33  */
34 #ifndef reda_string_h
35 #define reda_string_h
36 
37 #ifndef reda_dll_h
38 #include "reda/reda_dll.h"
39 #endif
40 
41 #include "reda/reda_sequence.h"
42 
43 REDA_DEFINE_SEQUENCE_STRUCT(REDA_StringSeq, char*)
44 
45 #ifdef __cplusplus
46 extern "C"
47 {
48 #endif
49 
50 /*ci
51  * \addtogroup REDAStringClass
52  * @{
53  */
54 
55 /*
56  * define the REDA_StringSeq
57  */
58 REDA_DEFINE_SEQUENCE_IN_C(REDA_StringSeq, char*)
59 
60 /*ci
61  * \def REDA_StringSeq_INITIALIZER
62  * \brief Initializer for REDA_StringSeq variables
63  */
64 #define REDA_StringSeq_INITIALIZER REDA_DEFINE_SEQUENCE_INITIALIZER(char*)
65 
66 /*ci
67  * \brief Alias for char*
68  */
69 typedef char* REDA_String_T;
70 
71 /*ci
72  * \brief Allocate a string of length bytes, excluding the NULL character.
73  *
74  * \details
75  *
76  * Allocate a buffer to hold a string of length bytes, excluding the
77  * NULL termination.
78  *
79  * \param[in] length Length of string to allocate, does not include the
80  * NULL termination character.
81  *
82  * \return Valid buffer on success, NULL on failure
83  *
84  * \sa \ref REDA_String_free
85  */
86 MUST_CHECK_RETURN REDADllExport char*
87 REDA_String_alloc(RTI_SIZE_T length);
88 
89 /*ci
90  * \brief Free a string buffer allocated with \ref REDA_String_alloc
91  *
92  * \details
93  *
94  * Free a string buffer allocated with \ref REDA_String_alloc
95  *
96  * \param[in] string String buffer to free
97  *
98  * \sa \ref REDA_String_alloc
99  */
100 REDADllExport void
101 REDA_String_free(char *string);
102 
103 /*ci
104  * \brief Return the length of a string excluding the NULL termination
105  *
106  * \details
107  *
108  * Return the length of a string, does not include the NULL termination
109  *
110  * \param[in] string String buffer to return length of
111  *
112  * \return Return the length of the string excluding the NULL termination
113  */
114 REDADllExport RTI_SIZE_T
115 REDA_String_length(const char *string);
116 
117 /*ci
118  * \brief Return a duplicate of a string
119  *
120  * \details
121  *
122  * Allocate a new buffer and copy the content of a string.
123  *
124  * \param[in] string String to duplicate
125  *
126  * \return Returns a pointer to the duplicate string on success, NULL on failure
127  */
128 MUST_CHECK_RETURN REDADllExport char*
129 REDA_String_dup(const char *string);
130 
131 /*ci
132  * \brief Replace the content of a previously allocated string buffer
133  *
134  * \details
135  *
136  * This function replaces the content of a previously allocated string buffer.
137  * If the replacement string is longer than the previously allocated string
138  * a new buffer is allocated and the content copied.
139  *
140  * \param[in] string_ptr String to replace
141  * \param[in] new_value String replacement
142  *
143  * \return Returns a pointer to the replaced string on success, NULL on failure
144  */
145 MUST_CHECK_RETURN REDADllExport char*
146 REDA_String_replace(char **string_ptr, const char *new_value);
147 
148 /*ci
149  * \brief Compare two strings
150  *
151  * \details
152  *
153  * This function compares two strings for lexicographic equivalence.
154  *
155  * \param[in] left Left side of comparison
156  *
157  * \param[in] right Right side of comparison
158  *
159  * \return Returns 0 if left is == right, < 0 if left < right, > 0 if left > right
160  *
161  * \sa \ref REDA_String_ncompare
162  */
163 MUST_CHECK_RETURN REDADllExport RTI_INT32
164 REDA_String_compare(const char *left, const char *right);
165 
166 /*ci
167  * \brief Compare two strings
168  *
169  * \details
170  *
171  * This function compares two strings for lexicographic equivalence, but only
172  * up to num bytes.
173  *
174  * \param[in] left Left side of comparison
175  *
176  * \param[in] right Right side of comparison
177  *
178  * \param[in] num Maximum number of bytes to compare
179  *
180  * \return Returns 0 if left is == right, < 0 if left < right, > 0 if left > right
181  *
182  * \sa \ref REDA_String_compare
183  */
184 MUST_CHECK_RETURN REDADllExport RTI_INT32
185 REDA_String_ncompare(const char *left, const char *right, RTI_SIZE_T num);
186 
187 #ifdef __cplusplus
188 } /* extern "C" */
189 #endif
190 
191 #endif /* reda_string_h */
192 
193 /*ci @} */
194 
RTI Connext Micro Version 2.4.1.0 Copyright © Thu Nov 20 2014 Real-Time Innovations, Inc