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