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_string, use as_string_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_string 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  * @extends as_val
104  * @ingroup aerospike_t
105  */
106 typedef struct as_string_s {
107 
108  /**
109  * @private
110  * as_boolean is a subtype of as_val.
111  * You can cast as_boolean to as_val.
112  */
114 
115  /**
116  * If true, then `as_string.value` can be freed.
117  */
118  bool free;
119 
120  /**
121  * The string value.
122  */
123  char * value;
124 
125  /**
126  * The length of the string.
127  */
128  size_t len;
129 
130 } as_string;
131 
132 /******************************************************************************
133  * INSTANCE FUNCTIONS
134  ******************************************************************************/
135 
136 /**
137  * Initialize a stack allocated `as_string`.
138  *
139  * If free is true, then the string value will be freed when the as_string is destroyed.
140  *
141  * @param string The stack allocated as_string to initialize
142  * @param value The NULL terminated string of character.
143  * @param free If true, then the value will be freed when as_string is destroyed.
144  *
145  * @return On success, the initialized string. Otherwise NULL.
146  *
147  * @relatesalso as_string
148  */
149 as_string * as_string_init(as_string * string, char * value, bool free);
150 
151 /**
152  * Initialize a stack allocated `as_string` and its length.
153  *
154  * If free is true, then the string value will be freed when the as_string is destroyed.
155  *
156  * @param string The stack allocated as_string to initialize
157  * @param value The NULL terminated string of character.
158  * @param len The length of the string.
159  * @param free If true, then the value will be freed when as_string is destroyed.
160  *
161  * @return On success, the initialized string. Otherwise NULL.
162  *
163  * @relatesalso as_string
164  */
165 as_string * as_string_init_wlen(as_string * string, char * value, size_t len, bool free);
166 
167 /**
168  * Create and initialize a new heap allocated `as_string`.
169  *
170  * If free is true, then the string value will be freed when the as_string is destroyed.
171  *
172  * @param value The NULL terminated string of character.
173  * @param free If true, then the value will be freed when as_string is destroyed.
174  *
175  * @return On success, the new string. Otherwise NULL.
176  *
177  * @relatesalso as_string
178  */
179 as_string * as_string_new(char * value, bool free);
180 
181 /**
182  * Create and initialize a new heap allocated `as_string` and its length.
183  *
184  * If free is true, then the string value will be freed when the as_string is destroyed.
185  *
186  * @param value The NULL terminated string of character.
187  * @param len The length of the string.
188  * @param free If true, then the value will be freed when as_string is destroyed.
189  *
190  * @return On success, the new string. Otherwise NULL.
191  *
192  * @relatesalso as_string
193  */
194 as_string * as_string_new_wlen(char * value, size_t len, bool free);
195 
196 /**
197  * Create and initialize a new heap allocated `as_string`.
198  *
199  * Value is cf_strdup()'d and will be freed when the as_string is destroyed.
200  *
201  * @param value The NULL terminated string of character.
202  *
203  * @return On success, the new string. Otherwise NULL.
204  */
205 as_string * as_string_new_strdup(const char * value);
206 
207 /**
208  * Destroy the as_string and associated resources.
209  *
210  * @relatesalso as_string
211  */
212 static inline void as_string_destroy(as_string * string)
213 {
214  as_val_destroy((as_val *) string);
215 }
216 
217 /******************************************************************************
218  * VALUE FUNCTIONS
219  ******************************************************************************/
220 
221 /**
222  * The length of the string
223  *
224  * @param string The string to get the length of.
225  *
226  * @return the length of the string in bytes.
227  *
228  * @relatesalso as_string
229  */
230 size_t as_string_len(as_string * string);
231 
232 /**
233  * Get the string value. If string is NULL, then return the fallback value.
234  *
235  * @relatesalso as_string
236  */
237 static inline char * as_string_getorelse(const as_string * string, char * fallback)
238 {
239  return string ? string->value : fallback;
240 }
241 
242 /**
243  * Get the string value.
244  *
245  * @relatesalso as_string
246  */
247 static inline char * as_string_get(const as_string * string)
248 {
249  return as_string_getorelse(string, NULL);
250 }
251 
252 /**
253  * Get the string value.
254  * @deprecated Use as_string_get() instead
255  *
256  * @relatesalso as_string
257  */
258 static inline char * as_string_tostring(const as_string * string)
259 {
260  return as_string_getorelse(string, NULL);
261 }
262 
263 /**
264  * Return filename component of full path.
265  *
266  * If path is empty, the current directory is returned.
267  * If path contains trailing directory slashes, create new string to hold
268  * filename without slashes. The input path is guaranteed not to be modified.
269  * as_string_destroy() must be called when finished with filename.
270  *
271  * @relatesalso as_string
272  */
273 const char* as_basename(as_string * filename, const char* path);
274 
275 /******************************************************************************
276  * CONVERSION FUNCTIONS
277  ******************************************************************************/
278 
279 /**
280  * Convert to an as_val.
281  *
282  * @relatesalso as_string
283  */
284 static inline as_val * as_string_toval(const as_string * s)
285 {
286  return (as_val *) s;
287 }
288 
289 /**
290  * Convert from an as_val.
291  *
292  * @relatesalso as_string
293  */
294 static inline as_string * as_string_fromval(const as_val * v)
295 {
296  return as_util_fromval(v, AS_STRING, as_string);
297 }
298 
299 /******************************************************************************
300  * as_val FUNCTIONS
301  ******************************************************************************/
302 
303 /**
304  * @private
305  * Internal helper function for destroying an as_val.
306  */
307 void as_string_val_destroy(as_val * v);
308 
309 /**
310  * @private
311  * Internal helper function for getting the hashcode of an as_val.
312  */
313 uint32_t as_string_val_hashcode(const as_val * v);
314 
315 /**
316  * @private
317  * Internal helper function for getting the string representation of an as_val.
318  */
319 char * as_string_val_tostring(const as_val * v);
320 
321 /******************************************************************************
322  * String utilities
323  ******************************************************************************/
324 
325 /**
326  * @private
327  * Copy null terminated src to trg up to a maximum size.
328  * If maximum size reached, null terminate last character and
329  * and return true that truncation occurred.
330  *
331  * as_strncpy does not pad unused bytes with zeroes like the
332  * standard strncpy.
333  *
334  * ~~~~~~~~~~{.c}
335  * char target[64];
336  * as_strncpy(target, "source string", sizeof(target));
337  * ~~~~~~~~~~
338  *
339  * @relatesalso as_string
340  */
341 bool as_strncpy(char* trg, const char* src, int size);
342 
343 #ifdef __cplusplus
344 } // end extern "C"
345 #endif