Loading...
Searching...
No Matches
as_geojson.h
Go to the documentation of this file.
1/*
2 * Copyright 2008-2018 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_std.h>
21#include <aerospike/as_util.h>
22#include <aerospike/as_val.h>
23
24#ifdef __cplusplus
25extern "C" {
26#endif
27
28/******************************************************************************
29 * TYPES
30 ******************************************************************************/
31
32/**
33 * Container for NULL-terminates GeoJSON string values.
34 *
35 * ## Initialization
36 *
37 * An as_geojson should be initialized via one of the provided function.
38 * - as_geojson_init()
39 * - as_geojson_new()
40 *
41 * To initialize a stack allocated as_geojson, use as_geojson_init():
42 *
43 * ~~~~~~~~~~{.c}
44 * as_geojson s;
45 * as_geojson_init(&s, "abc", false);
46 * ~~~~~~~~~~
47 *
48 * The 3rd argument indicates whether the string value should be `free()`d
49 * when as_geojson is destroyed.
50 *
51 * To create and initialize a heap allocated as_integer, use as_integer_new():
52 *
53 * ~~~~~~~~~~{.c}
54 * as_geojson * s = as_geojson_new("abc", false);
55 * ~~~~~~~~~~
56 *
57 * ## Destruction
58 *
59 * When the as_geojson instance is no longer required, then you should
60 * release the resources associated with it via as_geojson_destroy():
61 *
62 * ~~~~~~~~~~{.c}
63 * as_geojson_destroy(s);
64 * ~~~~~~~~~~
65 *
66 * ## Usage
67 *
68 * There are two functions for getting the boxed value contained by
69 * as_geojson:
70 *
71 * as_geojson_get() returns the contained value. If an error occurred, then
72 * NULL is returned. Possible errors is the as_integer instance is NULL.
73 *
74 * ~~~~~~~~~~{.c}
75 * char * sval = as_geojson_get(i);
76 * ~~~~~~~~~~
77 *
78 * as_geojson_getorelse() allows you to return a default value if an error
79 * occurs:
80 *
81 * ~~~~~~~~~~{.c}
82 * char * sval = as_geojson_getorelse(i, "oops!");
83 * ~~~~~~~~~~
84 *
85 * ## Conversions
86 *
87 * as_geojson is derived from as_val, so it is generally safe to down cast:
88 *
89 * ~~~~~~~~~~{.c}
90 * as_val val = (as_val) s;
91 * ~~~~~~~~~~
92 *
93 * However, upcasting is more error prone. When doing so, you should use
94 * as_geojson_fromval(). If conversion fails, then the return value is NULL.
95 *
96 * ~~~~~~~~~~{.c}
97 * as_geojson * i = as_geojson_fromval(val);
98 * ~~~~~~~~~~
99 *
100 * @extends as_val
101 * @ingroup aerospike_t
102 */
103typedef struct as_geojson_s {
104
105 /**
106 * @private
107 * as_boolean is a subtype of as_val.
108 * You can cast as_boolean to as_val.
109 */
110 as_val _;
111
112 /**
113 * If true, then `as_geojson.value` can be freed.
114 */
115 bool free;
116
117 /**
118 * The string value.
119 */
120 char * value;
121
122 /**
123 * The length of the string.
124 */
125 size_t len;
126
127} as_geojson;
128
129/******************************************************************************
130 * INSTANCE FUNCTIONS
131 ******************************************************************************/
132
133/**
134 * Initialize a stack allocated `as_geojson`.
135 *
136 * If free is true, then the string value will be freed when the as_geojson is destroyed.
137 *
138 * @param string The stack allocated as_geojson to initialize
139 * @param value The NULL terminated string of character.
140 * @param free If true, then the value will be freed when as_geojson is destroyed.
141 *
142 * @return On success, the initialized string. Otherwise NULL.
143 *
144 * @relatesalso as_geojson
145 */
146AS_EXTERN as_geojson * as_geojson_init(as_geojson * string, char * value, bool free);
147
148/**
149 * Initialize a stack allocated `as_geojson` and its length.
150 *
151 * If free is true, then the string value will be freed when the as_geojson is destroyed.
152 *
153 * @param string The stack allocated as_geojson to initialize
154 * @param value The NULL terminated string of character.
155 * @param len The length of the string.
156 * @param free If true, then the value will be freed when as_geojson is destroyed.
157 *
158 * @return On success, the initialized string. Otherwise NULL.
159 *
160 * @relatesalso as_geojson
161 */
162AS_EXTERN as_geojson * as_geojson_init_wlen(as_geojson * string, char * value, size_t len, bool free);
163
164/**
165 * Create and initialize a new heap allocated `as_geojson`.
166 *
167 * If free is true, then the string value will be freed when the as_geojson is destroyed.
168 *
169 * @param value The NULL terminated string of character.
170 * @param free If true, then the value will be freed when as_geojson is destroyed.
171 *
172 * @return On success, the new string. Otherwise NULL.
173 *
174 * @relatesalso as_geojson
175 */
176AS_EXTERN as_geojson * as_geojson_new(char * value, bool free);
177
178/**
179 * Create and initialize a new heap allocated `as_geojson` and its length.
180 *
181 * If free is true, then the string value will be freed when the as_geojson is destroyed.
182 *
183 * @param value The NULL terminated string of character.
184 * @param len The length of the string.
185 * @param free If true, then the value will be freed when as_geojson is destroyed.
186 *
187 * @return On success, the new string. Otherwise NULL.
188 *
189 * @relatesalso as_geojson
190 */
191AS_EXTERN as_geojson * as_geojson_new_wlen(char * value, size_t len, bool free);
192
193/**
194 * Create and initialize a new heap allocated `as_geojson`.
195 *
196 * Value is cf_strdup()'d and will be freed when the as_geojson is destroyed.
197 *
198 * @param value The NULL terminated string of character.
199 *
200 * @return On success, the new string. Otherwise NULL.
201 */
203
204/**
205 * Destroy the as_geojson and associated resources.
206 *
207 * @relatesalso as_geojson
208 */
209static inline void as_geojson_destroy(as_geojson * string)
210{
211 as_val_destroy((as_val *) string);
212}
213
214/******************************************************************************
215 * VALUE FUNCTIONS
216 ******************************************************************************/
217
218/**
219 * The length of the string
220 *
221 * @param string The string to get the length of.
222 *
223 * @return the length of the string in bytes.
224 *
225 * @relatesalso as_geojson
226 */
228
229/**
230 * Get the string value. If string is NULL, then return the fallback value.
231 *
232 * @relatesalso as_geojson
233 */
234static inline char * as_geojson_getorelse(const as_geojson * string, char * fallback)
235{
236 return string ? string->value : fallback;
237}
238
239/**
240 * Get the string value.
241 *
242 * @relatesalso as_geojson
243 */
244static inline char * as_geojson_get(const as_geojson * string)
245{
246 return as_geojson_getorelse(string, NULL);
247}
248
249/******************************************************************************
250 * CONVERSION FUNCTIONS
251 ******************************************************************************/
252
253/**
254 * Convert to an as_val.
255 *
256 * @relatesalso as_geojson
257 */
258static inline as_val * as_geojson_toval(const as_geojson * s)
259{
260 return (as_val *) s;
261}
262
263/**
264 * Convert from an as_val.
265 *
266 * @relatesalso as_geojson
267 */
268static inline as_geojson * as_geojson_fromval(const as_val * v)
269{
271}
272
273/******************************************************************************
274 * as_val FUNCTIONS
275 ******************************************************************************/
276
277/**
278 * @private
279 * Internal helper function for destroying an as_val.
280 */
282
283/**
284 * @private
285 * Internal helper function for getting the hashcode of an as_val.
286 */
288
289/**
290 * @private
291 * Internal helper function for getting the string representation of an as_val.
292 */
294
295#ifdef __cplusplus
296} // end extern "C"
297#endif
AS_EXTERN as_geojson * as_geojson_new_strdup(const char *value)
AS_EXTERN char * as_geojson_val_tostring(const as_val *v)
AS_EXTERN uint32_t as_geojson_val_hashcode(const as_val *v)
AS_EXTERN void as_geojson_val_destroy(as_val *v)
static char * as_geojson_getorelse(const as_geojson *string, char *fallback)
Definition as_geojson.h:234
#define AS_EXTERN
Definition as_std.h:25
#define as_util_fromval(object, type_id, type)
Definition as_util.h:43
@ AS_GEOJSON
Definition as_val.h:47
#define as_val_destroy(__v)
Definition as_val.h:114
AS_EXTERN as_geojson * as_geojson_new(char *value, bool free)
AS_EXTERN size_t as_geojson_len(as_geojson *string)
static as_geojson * as_geojson_fromval(const as_val *v)
Definition as_geojson.h:268
AS_EXTERN as_geojson * as_geojson_new_wlen(char *value, size_t len, bool free)
AS_EXTERN as_geojson * as_geojson_init_wlen(as_geojson *string, char *value, size_t len, bool free)
static void as_geojson_destroy(as_geojson *string)
Definition as_geojson.h:209
AS_EXTERN as_geojson * as_geojson_init(as_geojson *string, char *value, bool free)
static char * as_geojson_get(const as_geojson *string)
Definition as_geojson.h:244
static char * as_geojson_getorelse(const as_geojson *string, char *fallback)
Definition as_geojson.h:234
char * value
Definition as_geojson.h:120
size_t len
Definition as_geojson.h:125
static as_val * as_geojson_toval(const as_geojson *s)
Definition as_geojson.h:258