Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
aerospike
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
*/
115
as_val
_
;
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