All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_rec.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_integer.h>
21 #include <aerospike/as_bytes.h>
22 #include <aerospike/as_list.h>
23 #include <aerospike/as_map.h>
24 #include <aerospike/as_string.h>
25 #include <aerospike/as_util.h>
26 #include <aerospike/as_val.h>
27 
28 #include <stdbool.h>
29 #include <stdint.h>
30 
31 /******************************************************************************
32  * TYPES
33  *****************************************************************************/
34 
35 struct as_rec_hooks_s;
36 
37 /**
38  * Callback function for `as_rec_foreach()`. Called for each bin in the
39  * record.
40  *
41  * @param name The name of the current bin.
42  * @param value The value of the current bin.
43  * @param udata The user-data provided to the `as_rec_foreach()`.
44  *
45  * @return true to continue iterating through the list.
46  * false to stop iterating.
47  */
48 typedef bool (* as_rec_foreach_callback) (const char * name, const as_val * value, void * udata);
49 
50 /**
51  * as_rec is an interface for record types. A record is how data in Aerospike
52  * is represented, and is composed of bins and metadata.
53  *
54  * Implementations:
55  * - as_record
56  *
57  * @extends as_val
58  * @ingroup aerospike_t
59  */
60 typedef struct as_rec_s {
61 
62  /**
63  * @private
64  * as_boolean is a subtype of as_val.
65  * You can cast as_boolean to as_val.
66  */
68 
69  /**
70  * Data provided by the implementation of `as_rec`.
71  */
72  void * data;
73 
74  /**
75  * Hooks provided by the implementation of `as_rec`.
76  */
77  const struct as_rec_hooks_s * hooks;
78 
79 } as_rec;
80 
81 /**
82  * Record Hooks.
83  *
84  * An implementation of `as_rec` should provide implementations for each
85  * of the hooks.
86  */
87 typedef struct as_rec_hooks_s {
88 
89  /**
90  * Destroy the record.
91  */
92  bool (* destroy)(as_rec * rec);
93 
94  /**
95  * Get the hashcode of the record.
96  */
97  uint32_t (* hashcode)(const as_rec * rec);
98 
99  /**
100  * Get the value of the bin in the record.
101  */
102  as_val * (* get)(const as_rec * rec, const char * name);
103 
104  /**
105  * Set the value of the bin in the record.
106  */
107  int (* set)(const as_rec * rec, const char * name, const as_val * value);
108 
109  /**
110  * Remove the bin from the record.
111  */
112  int (* remove)(const as_rec * rec, const char * bin);
113 
114  /**
115  * Get the ttl value of the record.
116  */
117  uint32_t (* ttl)(const as_rec * rec);
118 
119  /**
120  * Get the generation value of the record.
121  */
122  uint16_t (* gen)(const as_rec * rec);
123 
124  /**
125  * Get the number of bins of the record.
126  */
127  uint16_t (* numbins)(const as_rec * rec);
128 
129  /**
130  * Get the digest of the record.
131  */
132  as_bytes * (* digest)(const as_rec * rec);
133 
134  /**
135  * Set flags on a bin.
136  */
137  int (* set_flags)(const as_rec * rec, const char * bin, uint8_t flags);
138 
139  /**
140  * Set the type of record.
141  */
142  int (* set_type)(const as_rec * rec, uint8_t type);
143 
144  /**
145  * Iterate over each bin in the record.
146  */
147  bool (* foreach)(const as_rec * rec, as_rec_foreach_callback callback, void * udata);
148 
149 } as_rec_hooks;
150 
151 /******************************************************************************
152  * INSTANCE FUNCTIONS
153  *****************************************************************************/
154 
155 /**
156  * @private
157  * Utilized by subtypes of as_rec to initialize the parent.
158  *
159  * @param rec The record to initialize
160  * @param free If TRUE, then as_rec_destory() will free the record.
161  * @param data Data for the map.
162  * @param hooks Implementation for the map interface.
163  *
164  * @return The initialized as_map on success. Otherwise NULL.
165  *
166  * @relatesalso as_rec
167  */
168 as_rec * as_rec_cons(as_rec * rec, bool free, void * data, const as_rec_hooks * hooks);
169 
170 /**
171  * Initialize a stack allocated record.
172  *
173  * @param rec Stack allocated record to initialize.
174  * @param data Data for the record.
175  * @param hooks Implementation for the record interface.
176  *
177  * @return On success, the initialized record. Otherwise NULL.
178  *
179  * @relatesalso as_rec
180  */
181 as_rec * as_rec_init(as_rec * rec, void * data, const as_rec_hooks * hooks);
182 
183 /**
184  * Create and initialize a new heap allocated record.
185  *
186  * @param data Data for the record.
187  * @param hooks Implementation for the record interface.
188  *
189  * @return On success, a new record. Otherwise NULL.
190  *
191  * @relatesalso as_rec
192  */
193 as_rec * as_rec_new(void * data, const as_rec_hooks * hooks);
194 
195 /**
196  * Destroy the record.
197  *
198  * @relatesalso as_rec
199  */
200 static inline void as_rec_destroy(as_rec * rec)
201 {
202  as_val_destroy((as_val *) rec);
203 }
204 
205 /******************************************************************************
206  * INLINE FUNCTIONS
207  ******************************************************************************/
208 
209 /**
210  * Get the data source for the record.
211  *
212  * @relatesalso as_rec
213  */
214 static inline void * as_rec_source(const as_rec * rec)
215 {
216  return rec ? rec->data : NULL;
217 }
218 
219 /**
220  * Remove a bin from a record.
221  *
222  * @param rec The record to remove the bin from.
223  * @param name The name of the bin to remove.
224  *
225  * @return 0 on success, otherwise an error occurred.
226  *
227  * @relatesalso as_rec
228  */
229 static inline int as_rec_remove(const as_rec * rec, const char * name)
230 {
231  return as_util_hook(remove, 1, rec, name);
232 }
233 
234 /**
235  * Get the ttl for the record.
236  *
237  * @relatesalso as_rec
238  */
239 static inline uint32_t as_rec_ttl(const as_rec * rec)
240 {
241  return as_util_hook(ttl, 0, rec);
242 }
243 
244 /**
245  * Get the generation of the record
246  *
247  * @relatesalso as_rec
248  */
249 static inline uint16_t as_rec_gen(const as_rec * rec)
250 {
251  return as_util_hook(gen, 0, rec);
252 }
253 
254 /**
255  * Get the number of bins in the record.
256  *
257  * @relatesalso as_rec
258  */
259 static inline uint16_t as_rec_numbins(const as_rec * rec)
260 {
261  return as_util_hook(numbins, 0, rec);
262 }
263 
264 /**
265  * Get the digest of the record.
266  *
267  * @relatesalso as_rec
268  */
269 static inline as_bytes * as_rec_digest(const as_rec * rec)
270 {
271  return as_util_hook(digest, 0, rec);
272 }
273 
274 /**
275  * Set flags on a bin.
276  *
277  * @relatesalso as_rec
278  */
279 static inline int as_rec_set_flags(const as_rec * rec, const char * name, uint8_t flags)
280 {
281  return as_util_hook(set_flags, 0, rec, name, flags);
282 }
283 
284 /**
285  * Set the record type.
286  *
287  * @relatesalso as_rec
288  */
289 static inline int as_rec_set_type(const as_rec * rec, uint8_t rec_type)
290 {
291  return as_util_hook(set_type, 0, rec, rec_type);
292 }
293 
294 /******************************************************************************
295  * BIN GETTER FUNCTIONS
296  ******************************************************************************/
297 
298 /**
299  * Get a bin's value.
300  *
301  * @param rec The as_rec to read the bin value from.
302  * @param name The name of the bin.
303  *
304  * @return On success, the value of the bin. Otherwise NULL.
305  *
306  * @relatesalso as_rec
307  */
308 static inline as_val * as_rec_get(const as_rec * rec, const char * name)
309 {
310  return as_util_hook(get, NULL, rec, name);
311 }
312 
313 /**
314  * Get a bin's value as an int64_t.
315  *
316  * @param rec The as_rec to read the bin value from.
317  * @param name The name of the bin.
318  *
319  * @return On success, the value of the bin. Otherwise 0.
320  *
321  * @relatesalso as_rec
322  */
323 static inline int64_t as_rec_get_int64(const as_rec * rec, const char * name)
324 {
325  as_val * v = as_util_hook(get, NULL, rec, name);
327  return i ? as_integer_toint(i) : 0;
328 }
329 
330 /**
331  * Get a bin's value as a NULL terminated string.
332  *
333  * @param rec The as_rec to read the bin value from.
334  * @param name The name of the bin.
335  *
336  * @return On success, the value of the bin. Otherwise NULL.
337  *
338  * @relatesalso as_rec
339  */
340 static inline char * as_rec_get_str(const as_rec * rec, const char * name)
341 {
342  as_val * v = as_util_hook(get, NULL, rec, name);
343  as_string * s = as_string_fromval(v);
344  return s ? as_string_tostring(s) : 0;
345 }
346 
347 /**
348  * Get a bin's value as an as_integer.
349  *
350  * @param rec The as_rec to read the bin value from.
351  * @param name The name of the bin.
352  *
353  * @return On success, the value of the bin. Otherwise NULL.
354  *
355  * @relatesalso as_rec
356  */
357 static inline as_integer * as_rec_get_integer(const as_rec * rec, const char * name)
358 {
359  as_val * v = as_util_hook(get, NULL, rec, name);
360  return as_integer_fromval(v);
361 }
362 
363 /**
364  * Get a bin's value as an as_string.
365  *
366  * @param rec The as_rec to read the bin value from.
367  * @param name The name of the bin.
368  *
369  * @return On success, the value of the bin. Otherwise NULL.
370  *
371  * @relatesalso as_rec
372  */
373 static inline as_string * as_rec_get_string(const as_rec * rec, const char * name)
374 {
375  as_val * v = as_util_hook(get, NULL, rec, name);
376  return as_string_fromval(v);
377 }
378 
379 /**
380  * Get a bin's value as an as_bytes.
381  *
382  * @param rec The as_rec to read the bin value from.
383  * @param name The name of the bin.
384  *
385  * @return On success, the value of the bin. Otherwise NULL.
386  *
387  * @relatesalso as_rec
388  */
389 static inline as_bytes * as_rec_get_bytes(const as_rec * rec, const char * name)
390 {
391  as_val * v = as_util_hook(get, NULL, rec, name);
392  return as_bytes_fromval(v);
393 }
394 
395 /**
396  * Get a bin's value as an as_list.
397  *
398  * @param rec The as_rec to read the bin value from.
399  * @param name The name of the bin.
400  *
401  * @return On success, the value of the bin. Otherwise NULL.
402  *
403  * @relatesalso as_rec
404  */
405 static inline as_list * as_rec_get_list(const as_rec * rec, const char * name)
406 {
407  as_val * v = as_util_hook(get, NULL, rec, name);
408  return as_list_fromval(v);
409 }
410 
411 /**
412  * Get a bin's value as an as_map.
413  *
414  * @param rec The as_rec to read the bin value from.
415  * @param name The name of the bin.
416  *
417  * @return On success, the value of the bin. Otherwise NULL.
418  *
419  * @relatesalso as_rec
420  */
421 static inline as_map * as_rec_get_map(const as_rec * rec, const char * name)
422 {
423  as_val * v = as_util_hook(get, NULL, rec, name);
424  return as_map_fromval(v);
425 }
426 
427 /******************************************************************************
428  * BIN SETTER FUNCTIONS
429  ******************************************************************************/
430 
431 /**
432  * Set the bin's value to an as_val.
433  *
434  * @param rec The as_rec to write the bin value to - CONSUMES REFERENCE
435  * @param name The name of the bin.
436  * @param value The value of the bin.
437  *
438  * @return On success, 0. Otherwise an error occurred.
439  *
440  * @relatesalso as_rec
441  */
442 static inline int as_rec_set(const as_rec * rec, const char * name, const as_val * value)
443 {
444  return as_util_hook(set, 1, rec, name, value);
445 }
446 
447 /**
448  * Set the bin's value to an int64_t.
449  *
450  * @param rec The as_rec storing the bin.
451  * @param name The name of the bin.
452  * @param value The value of the bin.
453  *
454  * @return On success, 0. Otherwise an error occurred.
455  *
456  * @relatesalso as_rec
457  */
458 static inline int as_rec_set_int64(const as_rec * rec, const char * name, int64_t value)
459 {
460  return as_util_hook(set, 1, rec, name, (as_val *) as_integer_new(value));
461 }
462 
463 /**
464  * Set the bin's value to a NULL terminated string.
465  *
466  * @param rec The as_rec storing the bin.
467  * @param name The name of the bin.
468  * @param value The value of the bin.
469  *
470  * @return On success, 0. Otherwise an error occurred.
471  *
472  * @relatesalso as_rec
473  */
474 static inline int as_rec_set_str(const as_rec * rec, const char * name, const char * value)
475 {
476  return as_util_hook(set, 1, rec, name, (as_val *) as_string_new_strdup(value));
477 }
478 
479 /**
480  * Set the bin's value to an as_integer.
481  *
482  * @param rec The as_rec storing the bin.
483  * @param name The name of the bin.
484  * @param value The value of the bin.
485  *
486  * @return On success, 0. Otherwise an error occurred.
487  *
488  * @relatesalso as_rec
489  */
490 static inline int as_rec_set_integer(const as_rec * rec, const char * name, const as_integer * value)
491 {
492  return as_util_hook(set, 1, rec, name, (as_val *) value);
493 }
494 
495 /**
496  * Set the bin's value to an as_string.
497  *
498  * @param rec The as_rec storing the bin.
499  * @param name The name of the bin.
500  * @param value The value of the bin.
501  *
502  * @return On success, 0. Otherwise an error occurred.
503  *
504  * @relatesalso as_rec
505  */
506 static inline int as_rec_set_string(const as_rec * rec, const char * name, const as_string * value)
507 {
508  return as_util_hook(set, 1, rec, name, (as_val *) value);
509 }
510 
511 /**
512  * Set the bin's value to an as_bytes.
513  *
514  * @param rec The as_rec storing the bin.
515  * @param name The name of the bin.
516  * @param value The value of the bin.
517  *
518  * @return On success, 0. Otherwise an error occurred.
519  *
520  * @relatesalso as_rec
521  */
522 static inline int as_rec_set_bytes(const as_rec * rec, const char * name, const as_bytes * value)
523 {
524  return as_util_hook(set, 1, rec, name, (as_val *) value);
525 }
526 
527 /**
528  * Set the bin's value to an as_list.
529  *
530  * @param rec The as_rec storing the bin.
531  * @param name The name of the bin.
532  * @param value The value of the bin.
533  *
534  * @return On success, 0. Otherwise an error occurred.
535  *
536  * @relatesalso as_rec
537  */
538 static inline int as_rec_set_list(const as_rec * rec, const char * name, const as_list * value)
539 {
540  return as_util_hook(set, 1, rec, name, (as_val *) value);
541 }
542 
543 /**
544  * Set the bin's value to an as_map.
545  *
546  * @param rec The as_rec storing the bin.
547  * @param name The name of the bin.
548  * @param value The value of the bin.
549  *
550  * @return On success, 0. Otherwise an error occurred.
551  *
552  * @relatesalso as_rec
553  */
554 static inline int as_rec_set_map(const as_rec * rec, const char * name, const as_map * value)
555 {
556  return as_util_hook(set, 1, rec, name, (as_val *) value);
557 }
558 
559 /******************************************************************************
560  * ITERATION FUNCTIONS
561  ******************************************************************************/
562 
563 /**
564  * Call the callback function for each bin in the record.
565  *
566  * @param rec The as_rec containing the bins to iterate over.
567  * @param callback The function to call for each entry.
568  * @param udata User-data to be passed to the callback.
569  *
570  * @return true if iteration completes fully. false if iteration was aborted.
571  *
572  * @relatesalso as_rec
573  */
574 static inline bool as_rec_foreach(const as_rec * rec, as_rec_foreach_callback callback, void * udata)
575 {
576  return as_util_hook(foreach, false, rec, callback, udata);
577 }
578 
579 /******************************************************************************
580  * CONVERSION FUNCTIONS
581  ******************************************************************************/
582 
583 /**
584  * Convert to an as_val.
585  *
586  * @relatesalso as_rec
587  */
588 static inline as_val * as_rec_toval(const as_rec * rec)
589 {
590  return (as_val *) rec;
591 }
592 
593 /**
594  * Convert from an as_val.
595  *
596  * @relatesalso as_rec
597  */
598 static inline as_rec * as_rec_fromval(const as_val * v)
599 {
600  return as_util_fromval(v, AS_REC, as_rec);
601 }
602 
603 /******************************************************************************
604  * as_val FUNCTIONS
605  ******************************************************************************/
606 
607 /**
608  * @private
609  * Internal helper function for destroying an as_val.
610  */
611 void as_rec_val_destroy(as_val *);
612 
613 /**
614  * @private
615  * Internal helper function for getting the hashcode of an as_val.
616  */
617 uint32_t as_rec_val_hashcode(const as_val *v);
618 
619 /**
620  * @private
621  * Internal helper function for getting the string representation of an as_val.
622  */
623 char * as_rec_val_tostring(const as_val *v);
static as_integer * as_integer_fromval(const as_val *v)
Definition: as_integer.h:230
static uint32_t as_rec_ttl(const as_rec *rec)
Definition: as_rec.h:239
AS_REC
Definition: as_val.h:215
Definition: as_rec.h:60
as_rec * as_rec_cons(as_rec *rec, bool free, void *data, const as_rec_hooks *hooks)
static as_map * as_rec_get_map(const as_rec *rec, const char *name)
Definition: as_rec.h:421
uint32_t as_rec_val_hashcode(const as_val *v)
Definition: as_map.h:57
bool(* as_rec_foreach_callback)(const char *name, const as_val *value, void *udata)
Definition: as_rec.h:48
static as_list * as_rec_get_list(const as_rec *rec, const char *name)
Definition: as_rec.h:405
as_rec * as_rec_init(as_rec *rec, void *data, const as_rec_hooks *hooks)
#define as_util_fromval(object, type_id, type)
Definition: as_util.h:38
static int64_t as_integer_toint(const as_integer *integer)
Definition: as_integer.h:208
static int as_rec_set(const as_rec *rec, const char *name, const as_val *value)
Definition: as_rec.h:442
static as_bytes * as_rec_get_bytes(const as_rec *rec, const char *name)
Definition: as_rec.h:389
as_integer * as_integer_new(int64_t value)
Definition: as_val.h:51
as_string * as_string_new_strdup(const char *value)
static bool as_rec_foreach(const as_rec *rec, as_rec_foreach_callback callback, void *udata)
Definition: as_rec.h:574
void as_rec_val_destroy(as_val *)
static int64_t as_rec_get_int64(const as_rec *rec, const char *name)
Definition: as_rec.h:323
#define as_util_hook(hook, default, object, args...)
Definition: as_util.h:32
static as_val * as_rec_get(const as_rec *rec, const char *name)
Definition: as_rec.h:308
static char * as_rec_get_str(const as_rec *rec, const char *name)
Definition: as_rec.h:340
static int as_rec_remove(const as_rec *rec, const char *name)
Definition: as_rec.h:229
static void as_rec_destroy(as_rec *rec)
Definition: as_rec.h:200
static uint16_t as_rec_numbins(const as_rec *rec)
Definition: as_rec.h:259
void * data
Definition: as_rec.h:72
static as_string * as_rec_get_string(const as_rec *rec, const char *name)
Definition: as_rec.h:373
static as_rec * as_rec_fromval(const as_val *v)
Definition: as_rec.h:598
static int as_rec_set_list(const as_rec *rec, const char *name, const as_list *value)
Definition: as_rec.h:538
static int as_rec_set_int64(const as_rec *rec, const char *name, int64_t value)
Definition: as_rec.h:458
static as_bytes * as_bytes_fromval(const as_val *v)
Definition: as_bytes.h:876
as_val _
Definition: as_rec.h:67
static int as_rec_set_bytes(const as_rec *rec, const char *name, const as_bytes *value)
Definition: as_rec.h:522
static char * as_string_tostring(const as_string *string)
Definition: as_string.h:225
static as_string * as_string_fromval(const as_val *v)
Definition: as_string.h:261
static int as_rec_set_type(const as_rec *rec, uint8_t rec_type)
Definition: as_rec.h:289
static as_list * as_list_fromval(as_val *v)
Definition: as_list.h:1017
static int as_rec_set_flags(const as_rec *rec, const char *name, uint8_t flags)
Definition: as_rec.h:279
static void * as_rec_source(const as_rec *rec)
Definition: as_rec.h:214
struct as_rec_hooks_s * hooks
Definition: as_rec.h:77
static as_bytes * as_rec_digest(const as_rec *rec)
Definition: as_rec.h:269
static as_map * as_map_fromval(const as_val *val)
Definition: as_map.h:402
#define as_val_destroy(__v)
Definition: as_val.h:104
static int as_rec_set_str(const as_rec *rec, const char *name, const char *value)
Definition: as_rec.h:474
char * as_rec_val_tostring(const as_val *v)
static int as_rec_set_string(const as_rec *rec, const char *name, const as_string *value)
Definition: as_rec.h:506
static uint16_t as_rec_gen(const as_rec *rec)
Definition: as_rec.h:249
static int as_rec_set_integer(const as_rec *rec, const char *name, const as_integer *value)
Definition: as_rec.h:490
static int as_rec_set_map(const as_rec *rec, const char *name, const as_map *value)
Definition: as_rec.h:554
as_rec * as_rec_new(void *data, const as_rec_hooks *hooks)
static as_integer * as_rec_get_integer(const as_rec *rec, const char *name)
Definition: as_rec.h:357
static as_val * as_rec_toval(const as_rec *rec)
Definition: as_rec.h:588