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-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
*/
111
as_val
_
;
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 length.
295
* If maximum length 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
bool
as_strncpy
(
char
* trg,
const
char
* src,
int
len);