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-2014 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 /******************************************************************************
28  * TYPES
29  ******************************************************************************/
30 
31 /**
32  * Container for NULL-terminates string values.
33  *
34  * ## Initialization
35  *
36  * An as_string should be initialized via one of the provided function.
37  * - as_string_init()
38  * - as_string_new()
39  *
40  * To initialize a stack allocated as_string, use as_string_init():
41  *
42  * ~~~~~~~~~~{.c}
43  * as_string s;
44  * as_string_init(&s, "abc", false);
45  * ~~~~~~~~~~
46  *
47  * The 3rd argument indicates whether the string value should be `free()`d
48  * when as_string is destroyed.
49  *
50  * To create and initialize a heap allocated as_integer, use as_integer_new():
51  *
52  * ~~~~~~~~~~{.c}
53  * as_string * s = as_string_new("abc", false);
54  * ~~~~~~~~~~
55  *
56  * ## Destruction
57  *
58  * When the as_string instance is no longer required, then you should
59  * release the resources associated with it via as_string_destroy():
60  *
61  * ~~~~~~~~~~{.c}
62  * as_string_destroy(s);
63  * ~~~~~~~~~~
64  *
65  * ## Usage
66  *
67  * There are two functions for getting the boxed value contained by
68  * as_string:
69  *
70  * as_string_get() returns the contained value. If an error occurred, then
71  * NULL is returned. Possible errors is the as_integer instance is NULL.
72  *
73  * ~~~~~~~~~~{.c}
74  * char * sval = as_string_get(i);
75  * ~~~~~~~~~~
76  *
77  * as_string_getorelse() allows you to return a default value if an error
78  * occurs:
79  *
80  * ~~~~~~~~~~{.c}
81  * char * sval = as_string_getorelse(i, "oops!");
82  * ~~~~~~~~~~
83  *
84  * ## Conversions
85  *
86  * as_string is derived from as_val, so it is generally safe to down cast:
87  *
88  * ~~~~~~~~~~{.c}
89  * as_val val = (as_val) s;
90  * ~~~~~~~~~~
91  *
92  * However, upcasting is more error prone. When doing so, you should use
93  * as_string_fromval(). If conversion fails, then the return value is NULL.
94  *
95  * ~~~~~~~~~~{.c}
96  * as_string * i = as_string_fromval(val);
97  * ~~~~~~~~~~
98  *
99  *
100  *
101  * @extends as_val
102  * @ingroup aerospike_t
103  */
104 typedef struct as_string_s {
105 
106  /**
107  * @private
108  * as_boolean is a subtype of as_val.
109  * You can cast as_boolean to as_val.
110  */
112 
113  /**
114  * If true, then `as_string.value` can be freed.
115  */
116  bool free;
117 
118  /**
119  * The string value.
120  */
121  char * value;
122 
123  /**
124  * The length of the string.
125  */
126  size_t len;
127 
128 } as_string;
129 
130 /******************************************************************************
131  * INSTANCE FUNCTIONS
132  ******************************************************************************/
133 
134 /**
135  * Initialize a stack allocated `as_string`.
136  *
137  * If free is true, then the string value will be freed when the as_string is destroyed.
138  *
139  * @param string The stack allocated as_string to initialize
140  * @param value The NULL terminated string of character.
141  * @param free If true, then the value will be freed when as_string is destroyed.
142  *
143  * @return On success, the initialized string. Otherwise NULL.
144  *
145  * @relatesalso as_string
146  */
147 as_string * as_string_init(as_string * string, char * value, bool free);
148 
149 /**
150  * Create and initialize a new heap allocated `as_string`.
151  *
152  * If free is true, then the string value will be freed when the as_string is destroyed.
153  *
154  * @param value The NULL terminated string of character.
155  * @param free If true, then the value will be freed when as_string is destroyed.
156  *
157  * @return On success, the new string. Otherwise NULL.
158  *
159  * @relatesalso as_string
160  */
161 as_string * as_string_new(char * value, bool free);
162 
163 /**
164  * Create and initialize a new heap allocated `as_string`.
165  *
166  * Value is cf_strdup()'d and will be freed when the as_string is destroyed.
167  *
168  * @param value The NULL terminated string of character.
169  *
170  * @return On success, the new string. Otherwise NULL.
171  */
172 as_string * as_string_new_strdup(const char * value);
173 
174 /**
175  * Destroy the as_string and associated resources.
176  *
177  * @relatesalso as_string
178  */
179 static inline void as_string_destroy(as_string * string)
180 {
181  as_val_destroy((as_val *) string);
182 }
183 
184 /******************************************************************************
185  * VALUE FUNCTIONS
186  ******************************************************************************/
187 
188 /**
189  * The length of the string
190  *
191  * @param string The string to get the length of.
192  *
193  * @return the length of the string in bytes.
194  *
195  * @relatesalso as_string
196  */
197 size_t as_string_len(as_string * string);
198 
199 /**
200  * Get the string value. If string is NULL, then return the fallback value.
201  *
202  * @relatesalso as_string
203  */
204 static inline char * as_string_getorelse(const as_string * string, char * fallback)
205 {
206  return string ? string->value : fallback;
207 }
208 
209 /**
210  * Get the string value.
211  *
212  * @relatesalso as_string
213  */
214 static inline char * as_string_get(const as_string * string)
215 {
216  return as_string_getorelse(string, NULL);
217 }
218 
219 /**
220  * Get the string value.
221  * @deprecated Use as_string_get() instead
222  *
223  * @relatesalso as_string
224  */
225 static inline char * as_string_tostring(const as_string * string)
226 {
227  return as_string_getorelse(string, NULL);
228 }
229 
230 /**
231  * Return filename component of full path.
232  *
233  * If path is empty, the current directory is returned.
234  * If path contains trailing directory slashes, create new string to hold
235  * filename without slashes. The input path is guaranteed not to be modified.
236  * as_string_destroy() must be called when finished with filename.
237  *
238  * @relatesalso as_string
239  */
240 const char* as_basename(as_string * filename, const char* path);
241 
242 /******************************************************************************
243  * CONVERSION FUNCTIONS
244  ******************************************************************************/
245 
246 /**
247  * Convert to an as_val.
248  *
249  * @relatesalso as_string
250  */
251 static inline as_val * as_string_toval(const as_string * s)
252 {
253  return (as_val *) s;
254 }
255 
256 /**
257  * Convert from an as_val.
258  *
259  * @relatesalso as_string
260  */
261 static inline as_string * as_string_fromval(const as_val * v)
262 {
263  return as_util_fromval(v, AS_STRING, as_string);
264 }
265 
266 /******************************************************************************
267  * as_val FUNCTIONS
268  ******************************************************************************/
269 
270 /**
271  * @private
272  * Internal helper function for destroying an as_val.
273  */
274 void as_string_val_destroy(as_val * v);
275 
276 /**
277  * @private
278  * Internal helper function for getting the hashcode of an as_val.
279  */
280 uint32_t as_string_val_hashcode(const as_val * v);
281 
282 /**
283  * @private
284  * Internal helper function for getting the string representation of an as_val.
285  */
286 char * as_string_val_tostring(const as_val * v);
287 
288 /******************************************************************************
289  * String utilities
290  ******************************************************************************/
291 
292 /**
293  * @private
294  * Copy null terminated src to trg up to a maximum size.
295  * If maximum size reached, null terminate last character and
296  * and return true that truncation occurred.
297  *
298  * as_strncpy does not pad unused bytes with zeroes like the
299  * standard strncpy.
300  *
301  * ~~~~~~~~~~{.c}
302  * char target[64];
303  * as_strncpy(target, "source string", sizeof(target));
304  * ~~~~~~~~~~
305  *
306  * @relatesalso as_string
307  */
308 bool as_strncpy(char* trg, const char* src, int size);