All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
modules/common/src/include/aerospike/as_string.h
Go to the documentation of this file.
1 /******************************************************************************
2  * Copyright 2008-2013 by Aerospike.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to
6  * deal in the Software without restriction, including without limitation the
7  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8  * sell copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20  * IN THE SOFTWARE.
21  *****************************************************************************/
22 
23 #pragma once
24 
25 #include <aerospike/as_util.h>
26 #include <aerospike/as_val.h>
27 
28 #include <stdbool.h>
29 #include <stdint.h>
30 #include <string.h>
31 
32 /******************************************************************************
33  * TYPES
34  ******************************************************************************/
35 
36 /**
37  * Container for NULL-terminates string values.
38  *
39  * ## Initialization
40  *
41  * An as_string should be initialized via one of the provided function.
42  * - as_string_init()
43  * - as_string_new()
44  *
45  * To initialize a stack allocated as_string, use as_string_init():
46  *
47  * ~~~~~~~~~~{.c}
48  * as_string s;
49  * as_string_init(&s, "abc", false);
50  * ~~~~~~~~~~
51  *
52  * The 3rd argument indicates whether the string value should be `free()`d
53  * when as_string is destroyed.
54  *
55  * To create and initialize a heap allocated as_integer, use as_integer_new():
56  *
57  * ~~~~~~~~~~{.c}
58  * as_string * s = as_string_new("abc", false);
59  * ~~~~~~~~~~
60  *
61  * ## Destruction
62  *
63  * When the as_string instance is no longer required, then you should
64  * release the resources associated with it via as_string_destroy():
65  *
66  * ~~~~~~~~~~{.c}
67  * as_string_destroy(s);
68  * ~~~~~~~~~~
69  *
70  * ## Usage
71  *
72  * There are two functions for getting the boxed value contained by
73  * as_string:
74  *
75  * as_string_get() returns the contained value. If an error occurred, then
76  * NULL is returned. Possible errors is the as_integer instance is NULL.
77  *
78  * ~~~~~~~~~~{.c}
79  * char * sval = as_string_get(i);
80  * ~~~~~~~~~~
81  *
82  * as_string_getorelse() allows you to return a default value if an error
83  * occurs:
84  *
85  * ~~~~~~~~~~{.c}
86  * char * sval = as_string_getorelse(i, "oops!");
87  * ~~~~~~~~~~
88  *
89  * ## Conversions
90  *
91  * as_string is derived from as_val, so it is generally safe to down cast:
92  *
93  * ~~~~~~~~~~{.c}
94  * as_val val = (as_val) s;
95  * ~~~~~~~~~~
96  *
97  * However, upcasting is more error prone. When doing so, you should use
98  * as_string_fromval(). If conversion fails, then the return value is NULL.
99  *
100  * ~~~~~~~~~~{.c}
101  * as_string * i = as_string_fromval(val);
102  * ~~~~~~~~~~
103  *
104  *
105  *
106  * @extends as_val
107  * @ingroup aerospike_t
108  */
109 typedef struct as_string_s {
110 
111  /**
112  * @private
113  * as_boolean is a subtype of as_val.
114  * You can cast as_boolean to as_val.
115  */
117 
118  /**
119  * If true, then `as_string.value` can be freed.
120  */
121  bool free;
122 
123  /**
124  * The string value.
125  */
126  char * value;
127 
128  /**
129  * The length of the string.
130  */
131  size_t len;
132 
133 } as_string;
134 
135 /******************************************************************************
136  * INSTANCE FUNCTIONS
137  ******************************************************************************/
138 
139 /**
140  * Initialize a stack allocated `as_string`.
141  *
142  * If free is true, then the string value will be freed when the as_string is destroyed.
143  *
144  * @param string The stack allocated as_string to initialize
145  * @param value The NULL terminated string of character.
146  * @param free If true, then the value will be freed when as_string is destroyed.
147  *
148  * @return On success, the initialized string. Otherwise NULL.
149  *
150  * @relatesalso as_string
151  */
152 as_string * as_string_init(as_string * string, char * value, bool free);
153 
154 /**
155  * Create and initialize a new heap allocated `as_string`.
156  *
157  * If free is true, then the string value will be freed when the as_string is destroyed.
158  *
159  * @param value The NULL terminated string of character.
160  * @param free If true, then the value will be freed when as_string is destroyed.
161  *
162  * @return On success, the new string. Otherwise NULL.
163  *
164  * @relatesalso as_string
165  */
166 as_string * as_string_new(char * value, bool free);
167 
168 /**
169  * Create and initialize a new heap allocated `as_string`.
170  *
171  * Value is cf_strdup()'d and will be freed when the as_string is destroyed.
172  *
173  * @param value The NULL terminated string of character.
174  *
175  * @return On success, the new string. Otherwise NULL.
176  */
177 as_string * as_string_new_strdup(const char * value);
178 
179 /**
180  * Destroy the as_string and associated resources.
181  *
182  * @relatesalso as_string
183  */
184 static inline void as_string_destroy(as_string * string)
185 {
186  as_val_destroy((as_val *) string);
187 }
188 
189 /******************************************************************************
190  * VALUE FUNCTIONS
191  ******************************************************************************/
192 
193 /**
194  * The length of the string
195  *
196  * @param string The string to get the length of.
197  *
198  * @return the length of the string in bytes.
199  *
200  * @relatesalso as_string
201  */
202 size_t as_string_len(as_string * string);
203 
204 /**
205  * Get the string value. If string is NULL, then return the fallback value.
206  *
207  * @relatesalso as_string
208  */
209 static inline char * as_string_getorelse(const as_string * string, char * fallback)
210 {
211  return string ? string->value : fallback;
212 }
213 
214 /**
215  * Get the string value.
216  *
217  * @relatesalso as_string
218  */
219 static inline char * as_string_get(const as_string * string)
220 {
221  return as_string_getorelse(string, NULL);
222 }
223 
224 /**
225  * Get the string value.
226  * @deprecated Use as_string_get() instead
227  *
228  * @relatesalso as_string
229  */
230 static inline char * as_string_tostring(const as_string * string)
231 {
232  return as_string_getorelse(string, NULL);
233 }
234 
235 /**
236  * Return filename component of full path.
237  *
238  * If path is empty, the current directory is returned.
239  * If path contains trailing directory slashes, create new string to hold
240  * filename without slashes. The input path is guaranteed not to be modified.
241  * as_string_destroy() must be called when finished with filename.
242  *
243  * @relatesalso as_string
244  */
245 const char* as_basename(as_string * filename, const char* path);
246 
247 /******************************************************************************
248  * CONVERSION FUNCTIONS
249  ******************************************************************************/
250 
251 /**
252  * Convert to an as_val.
253  *
254  * @relatesalso as_string
255  */
256 static inline as_val * as_string_toval(const as_string * s)
257 {
258  return (as_val *) s;
259 }
260 
261 /**
262  * Convert from an as_val.
263  *
264  * @relatesalso as_string
265  */
266 static inline as_string * as_string_fromval(const as_val * v)
267 {
268  return as_util_fromval(v, AS_STRING, as_string);
269 }
270 
271 /******************************************************************************
272  * as_val FUNCTIONS
273  ******************************************************************************/
274 
275 /**
276  * @private
277  * Internal helper function for destroying an as_val.
278  */
279 void as_string_val_destroy(as_val * v);
280 
281 /**
282  * @private
283  * Internal helper function for getting the hashcode of an as_val.
284  */
285 uint32_t as_string_val_hashcode(const as_val * v);
286 
287 /**
288  * @private
289  * Internal helper function for getting the string representation of an as_val.
290  */
291 char * as_string_val_tostring(const as_val * v);