Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
modules
common
target
Linux-x86_64
include
aerospike
modules/common/target/Linux-x86_64/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
*/
116
as_val
_;
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);