All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_string.h
Go to the documentation of this file.
1 /*
2  * Copyright 2008-2015 Aerospike, Inc.
3  *
4  * Portions may be licensed to Aerospike, Inc. under one or more contributor
5  * license agreements.
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
8  * use this file except in compliance with the License. You may obtain a copy of
9  * the License at http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14  * License for the specific language governing permissions and limitations under
15  * the License.
16  */
17 
18 #pragma once
19 
20 #include <aerospike/as_util.h>
21 #include <aerospike/as_val.h>
22 
23 #include <stdbool.h>
24 #include <stdint.h>
25 #include <string.h>
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
31 /******************************************************************************
32  * TYPES
33  ******************************************************************************/
34 
35 /**
36  * Container for NULL-terminates string values.
37  *
38  * ## Initialization
39  *
40  * An as_string should be initialized via one of the provided function.
41  * - as_string_init()
42  * - as_string_new()
43  *
44  * To initialize a stack allocated as_string, use as_string_init():
45  *
46  * ~~~~~~~~~~{.c}
47  * as_string s;
48  * as_string_init(&s, "abc", false);
49  * ~~~~~~~~~~
50  *
51  * The 3rd argument indicates whether the string value should be `free()`d
52  * when as_string is destroyed.
53  *
54  * To create and initialize a heap allocated as_integer, use as_integer_new():
55  *
56  * ~~~~~~~~~~{.c}
57  * as_string * s = as_string_new("abc", false);
58  * ~~~~~~~~~~
59  *
60  * ## Destruction
61  *
62  * When the as_string instance is no longer required, then you should
63  * release the resources associated with it via as_string_destroy():
64  *
65  * ~~~~~~~~~~{.c}
66  * as_string_destroy(s);
67  * ~~~~~~~~~~
68  *
69  * ## Usage
70  *
71  * There are two functions for getting the boxed value contained by
72  * as_string:
73  *
74  * as_string_get() returns the contained value. If an error occurred, then
75  * NULL is returned. Possible errors is the as_integer instance is NULL.
76  *
77  * ~~~~~~~~~~{.c}
78  * char * sval = as_string_get(i);
79  * ~~~~~~~~~~
80  *
81  * as_string_getorelse() allows you to return a default value if an error
82  * occurs:
83  *
84  * ~~~~~~~~~~{.c}
85  * char * sval = as_string_getorelse(i, "oops!");
86  * ~~~~~~~~~~
87  *
88  * ## Conversions
89  *
90  * as_string is derived from as_val, so it is generally safe to down cast:
91  *
92  * ~~~~~~~~~~{.c}
93  * as_val val = (as_val) s;
94  * ~~~~~~~~~~
95  *
96  * However, upcasting is more error prone. When doing so, you should use
97  * as_string_fromval(). If conversion fails, then the return value is NULL.
98  *
99  * ~~~~~~~~~~{.c}
100  * as_string * i = as_string_fromval(val);
101  * ~~~~~~~~~~
102  *
103  *
104  *
105  * @extends as_val
106  * @ingroup aerospike_t
107  */
108 typedef struct as_string_s {
109 
110  /**
111  * @private
112  * as_boolean is a subtype of as_val.
113  * You can cast as_boolean to as_val.
114  */
116 
117  /**
118  * If true, then `as_string.value` can be freed.
119  */
120  bool free;
121 
122  /**
123  * The string value.
124  */
125  char * value;
126 
127  /**
128  * The length of the string.
129  */
130  size_t len;
131 
132 } as_string;
133 
134 /******************************************************************************
135  * INSTANCE FUNCTIONS
136  ******************************************************************************/
137 
138 /**
139  * Initialize a stack allocated `as_string`.
140  *
141  * If free is true, then the string value will be freed when the as_string is destroyed.
142  *
143  * @param string The stack allocated as_string to initialize
144  * @param value The NULL terminated string of character.
145  * @param free If true, then the value will be freed when as_string is destroyed.
146  *
147  * @return On success, the initialized string. Otherwise NULL.
148  *
149  * @relatesalso as_string
150  */
151 as_string * as_string_init(as_string * string, char * value, bool free);
152 
153 /**
154  * Initialize a stack allocated `as_string` and its length.
155  *
156  * If free is true, then the string value will be freed when the as_string is destroyed.
157  *
158  * @param string The stack allocated as_string to initialize
159  * @param value The NULL terminated string of character.
160  * @param len The length of the string.
161  * @param free If true, then the value will be freed when as_string is destroyed.
162  *
163  * @return On success, the initialized string. Otherwise NULL.
164  *
165  * @relatesalso as_string
166  */
167 as_string * as_string_init_wlen(as_string * string, char * value, size_t len, bool free);
168 
169 /**
170  * Create and initialize a new heap allocated `as_string`.
171  *
172  * If free is true, then the string value will be freed when the as_string is destroyed.
173  *
174  * @param value The NULL terminated string of character.
175  * @param free If true, then the value will be freed when as_string is destroyed.
176  *
177  * @return On success, the new string. Otherwise NULL.
178  *
179  * @relatesalso as_string
180  */
181 as_string * as_string_new(char * value, bool free);
182 
183 /**
184  * Create and initialize a new heap allocated `as_string` and its length.
185  *
186  * If free is true, then the string value will be freed when the as_string is destroyed.
187  *
188  * @param value The NULL terminated string of character.
189  * @param len The length of the string.
190  * @param free If true, then the value will be freed when as_string is destroyed.
191  *
192  * @return On success, the new string. Otherwise NULL.
193  *
194  * @relatesalso as_string
195  */
196 as_string * as_string_new_wlen(char * value, size_t len, bool free);
197 
198 /**
199  * Create and initialize a new heap allocated `as_string`.
200  *
201  * Value is cf_strdup()'d and will be freed when the as_string is destroyed.
202  *
203  * @param value The NULL terminated string of character.
204  *
205  * @return On success, the new string. Otherwise NULL.
206  */
207 as_string * as_string_new_strdup(const char * value);
208 
209 /**
210  * Destroy the as_string and associated resources.
211  *
212  * @relatesalso as_string
213  */
214 static inline void as_string_destroy(as_string * string)
215 {
216  as_val_destroy((as_val *) string);
217 }
218 
219 /******************************************************************************
220  * VALUE FUNCTIONS
221  ******************************************************************************/
222 
223 /**
224  * The length of the string
225  *
226  * @param string The string to get the length of.
227  *
228  * @return the length of the string in bytes.
229  *
230  * @relatesalso as_string
231  */
232 size_t as_string_len(as_string * string);
233 
234 /**
235  * Get the string value. If string is NULL, then return the fallback value.
236  *
237  * @relatesalso as_string
238  */
239 static inline char * as_string_getorelse(const as_string * string, char * fallback)
240 {
241  return string ? string->value : fallback;
242 }
243 
244 /**
245  * Get the string value.
246  *
247  * @relatesalso as_string
248  */
249 static inline char * as_string_get(const as_string * string)
250 {
251  return as_string_getorelse(string, NULL);
252 }
253 
254 /**
255  * Get the string value.
256  * @deprecated Use as_string_get() instead
257  *
258  * @relatesalso as_string
259  */
260 static inline char * as_string_tostring(const as_string * string)
261 {
262  return as_string_getorelse(string, NULL);
263 }
264 
265 /**
266  * Return filename component of full path.
267  *
268  * If path is empty, the current directory is returned.
269  * If path contains trailing directory slashes, create new string to hold
270  * filename without slashes. The input path is guaranteed not to be modified.
271  * as_string_destroy() must be called when finished with filename.
272  *
273  * @relatesalso as_string
274  */
275 const char* as_basename(as_string * filename, const char* path);
276 
277 /******************************************************************************
278  * CONVERSION FUNCTIONS
279  ******************************************************************************/
280 
281 /**
282  * Convert to an as_val.
283  *
284  * @relatesalso as_string
285  */
286 static inline as_val * as_string_toval(const as_string * s)
287 {
288  return (as_val *) s;
289 }
290 
291 /**
292  * Convert from an as_val.
293  *
294  * @relatesalso as_string
295  */
296 static inline as_string * as_string_fromval(const as_val * v)
297 {
298  return as_util_fromval(v, AS_STRING, as_string);
299 }
300 
301 /******************************************************************************
302  * as_val FUNCTIONS
303  ******************************************************************************/
304 
305 /**
306  * @private
307  * Internal helper function for destroying an as_val.
308  */
309 void as_string_val_destroy(as_val * v);
310 
311 /**
312  * @private
313  * Internal helper function for getting the hashcode of an as_val.
314  */
315 uint32_t as_string_val_hashcode(const as_val * v);
316 
317 /**
318  * @private
319  * Internal helper function for getting the string representation of an as_val.
320  */
321 char * as_string_val_tostring(const as_val * v);
322 
323 /******************************************************************************
324  * String utilities
325  ******************************************************************************/
326 
327 /**
328  * @private
329  * Copy null terminated src to trg up to a maximum size.
330  * If maximum size reached, null terminate last character and
331  * and return true that truncation occurred.
332  *
333  * as_strncpy does not pad unused bytes with zeroes like the
334  * standard strncpy.
335  *
336  * ~~~~~~~~~~{.c}
337  * char target[64];
338  * as_strncpy(target, "source string", sizeof(target));
339  * ~~~~~~~~~~
340  *
341  * @relatesalso as_string
342  */
343 bool as_strncpy(char* trg, const char* src, int size);
344 
345 #ifdef __cplusplus
346 } // end extern "C"
347 #endif