All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_record.h
Go to the documentation of this file.
1 /*
2  * Copyright 2008-2015 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 #pragma once
18 
19 #include <aerospike/as_bin.h>
20 #include <aerospike/as_bytes.h>
21 #include <aerospike/as_integer.h>
22 #include <aerospike/as_key.h>
23 #include <aerospike/as_list.h>
24 #include <aerospike/as_map.h>
25 #include <aerospike/as_rec.h>
26 #include <aerospike/as_string.h>
27 #include <aerospike/as_geojson.h>
28 #include <aerospike/as_util.h>
29 #include <aerospike/as_val.h>
30 
31 #include <stdbool.h>
32 #include <stdint.h>
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 /******************************************************************************
39  * TYPES
40  *****************************************************************************/
41 
42 /**
43  * Records in Aerospike are collections of named bins.
44  *
45  * The bins in a record are analogous to columns in relational databases.
46  * However, unlike columns, the bins themselves are not typed. Instead, bins
47  * contain values which are typed. So, it is possible to have multiple records
48  * with bins of the same name but different types for values.
49  *
50  * The bin's value can only be of the types defined in `as_bin_value`.
51  *
52  * ## Initialization
53  *
54  * There are several ways to initialize an `as_record`.
55  *
56  * You can create the `as_record` on the stack:
57  *
58  * ~~~~~~~~~~{.c}
59  * as_record rec;
60  * ~~~~~~~~~~
61  *
62  * Then initialize it using either the `as_record_init()` function or
63  * `as_record_inita()` macro.
64  *
65  * The `as_record_init()` function will initialize the variable, then
66  * allocate the specified number of bins using `malloc()`. The following
67  * initializes `rec` with 2 bins.
68  *
69  * ~~~~~~~~~~{.c}
70  * as_record_init(&rec, 2);
71  * ~~~~~~~~~~
72  *
73  * The `as_record_inita()` macro will initialize the variable, then allocate
74  * the specified number of bins using `alloca()`. The following initializes
75  * `rec` with 2 bins.
76  *
77  * ~~~~~~~~~~{.c}
78  * as_record_inita(&rec, 2);
79  * ~~~~~~~~~~
80  *
81  * The `as_record_new()` function will allocate an `as_record` on the heap
82  * using `malloc()` then allocate the specified number of bins using
83  * `malloc()`. The following creates a new `as_record` with 2 bins.
84  *
85  * ~~~~~~~~~~{.c}
86  * as_record * rec = as_record_new(2);
87  * ~~~~~~~~~~
88  *
89  * ## Destruction
90  *
91  * When you no longer require an as_record, you should call `as_record_destroy()`
92  * to release the record and associated resources.
93  *
94  * ~~~~~~~~~~{.c}
95  * as_record_destroy(rec);
96  * ~~~~~~~~~~
97  *
98  * If the record has been ref-counted, then the ref-count will be decremented,
99  * until it reaches 0 (zero), at which point, the record will be released.
100  *
101  * ## Setting Bin Values
102  *
103  * The following are functions for setting values in bins of a record. Utilize
104  * the appropriate setter for the data you want to store in a bin.
105  *
106  * Function | Description
107  * ---------------------------- | ----------------------------------------------
108  * `as_record_set_int64()` | Set the bin value to a 64-bit integer.
109  * `as_record_set_str()` | Set the bin value to a NULL-terminated string.
110  * `as_record_set_integer()` | Set the bin value to an `as_integer`.
111  * `as_record_set_double()` | Set the bin value to an `as_double`.
112  * `as_record_set_string()` | Set the bin value to an `as_string`.
113  * `as_record_set_geojson()` | Set the bin value to an `as_geojson`.
114  * `as_record_set_bytes()` | Set the bin value to an `as_bytes`.
115  * `as_record_set_list()` | Set the bin value to an `as_list`.
116  * `as_record_set_map()` | Set the bin value to an `as_map`.
117  * `as_record_set_nil()` | Set the bin value to an `as_nil`.
118  * `as_record_set()` | Set the bin value to an `as_bin_value`.
119  *
120  * ## Getting Bin Values
121  *
122  * The following are functions for getting values from bins of a record.
123  * Utilize the appropriate getter for the data you want to read from a bin.
124  *
125  *
126  * Function | Description
127  * ---------------------------- | ----------------------------------------------
128  * `as_record_get_int64()` | Get the bin as a 64-bit integer.
129  * `as_record_get_str()` | Get the bin as a NULL-terminated string.
130  * `as_record_get_integer()` | Get the bin as an `as_integer`.
131  * `as_record_get_double()` | Get the bin as an `as_double`.
132  * `as_record_get_string()` | Get the bin as an `as_string`.
133  * `as_record_get_geojson()` | Get the bin as an `as_geojson`.
134  * `as_record_get_bytes()` | Get the bin as an `as_bytes`.
135  * `as_record_get_list()` | Get the bin as an `as_list`.
136  * `as_record_get_map()` | Get the bin as an `as_map`.
137  * `as_record_get()` | Get the bin as an `as_bin_value`.
138  *
139  * If you are unsure of the type of data stored in the bin, then you should
140  * use `as_record_get()`. You can then check the type of the value using
141  * `as_val_type()`.
142  *
143  * ~~~~~~~~~~{.c}
144  * as_val * value = as_record_get(rec, "bin1");
145  * switch ( as_val_type(value) ) {
146  * case AS_NIL: break;
147  * case AS_INTEGER: break;
148  * case AS_DOUBLE: break;
149  * case AS_STRING: break;
150  * case AS_GEOJSON: break;
151  * case AS_BYTES: break;
152  * case AS_LIST: break;
153  * case AS_MAP: break;
154  * case AS_REC: break;
155  * case AS_UNDEF: break;
156  * }
157  * ~~~~~~~~~~
158  *
159  * ## Traversing Bins
160  *
161  * If you want to traverse the bins of a record, then you have two options:
162  *
163  * - as_record_foreach() — Calls a function for each bin traversed.
164  * - as_record_iterator — Uses an iterator pattern to traverse bins.
165  *
166  * @extends as_rec
167  * @ingroup client_objects
168  */
169 typedef struct as_record_s {
170 
171  /**
172  * @private
173  * as_record is "derived" from as_rec.
174  * So you can actually type cast as_record to as_rec.
175  */
177 
178  /**
179  * The key of the record.
180  * This is populated when a record is read from the database.
181  * This should not be set by the user.
182  */
184 
185  /**
186  * The generation of the record.
187  */
188  uint16_t gen;
189 
190  /**
191  * The time-to-live (expiration) of the record in seconds.
192  * There are two special values that can be set in the record TTL:
193  * (*) ZERO (defined as AS_RECORD_DEFAULT_TTL), which means that the
194  * record will adopt the default TTL value from the namespace.
195  * (*) 0xFFFFFFFF (also, -1 in a signed 32 bit int)
196  * (defined as AS_RECORD_NO_EXPIRE_TTL), which means that the record
197  * will get an internal "void_time" of zero, and thus will never expire.
198  *
199  * Note that the TTL value will be employed ONLY on write/update calls.
200  */
201  uint32_t ttl;
202 
203  /**
204  * The bins of the record.
205  */
207 
208 } as_record;
209 
210 /**
211  * When the record is given a TTL value of ZERO, it will adopt the TTL value
212  * that is the default TTL value for the namespace (defined in the config file).
213  */
214 #define AS_RECORD_DEFAULT_TTL 0
215 
216 /**
217  * When the record is given a TTL value of 0xFFFFFFFF, it will set the internal
218  * void_time value (the absolute clock time value that shows when a record
219  * will expire) to zero, which means the record will never expire
220  */
221 #define AS_RECORD_NO_EXPIRE_TTL 0xFFFFFFFF
222 
223 /******************************************************************************
224  * MACROS
225  *****************************************************************************/
226 
227 /**
228  * Initialize a stack allocated `as_record` then allocate `__nbins` capacity
229  * for as_record.bins on the stack.
230  *
231  * ~~~~~~~~~~{.c}
232  * as_record record;
233  * as_record_inita(&record, 2);
234  * as_record_set_int64(&record, "bin1", 123);
235  * as_record_set_int64(&record, "bin2", 456);
236  * ~~~~~~~~~~
237  *
238  * When you are finished using the `as_record` instance, you should release the
239  * resources allocated to it by calling `as_record_destroy()`.
240  *
241  * @param __rec The `as_record *` to initialize.
242  * @param __nbins The number of `as_record.bins.entries` to allocate on the
243  * stack.
244  *
245  * @relates as_record
246  */
247 #define as_record_inita(__rec, __nbins) \
248  as_record_init(__rec, 0);\
249  (__rec)->bins._free = false;\
250  (__rec)->bins.capacity = __nbins;\
251  (__rec)->bins.size = 0;\
252  (__rec)->bins.entries = (as_bin *) alloca(sizeof(as_bin) * __nbins);
253 
254 /******************************************************************************
255  * FUNCTIONS
256  *****************************************************************************/
257 
258 /**
259  * Create a new as_record on the heap.
260  *
261  * ~~~~~~~~~~{.c}
262  * as_record * r = as_record_new(2);
263  * as_record_set_int64(r, "bin1", 123);
264  * as_record_set_str(r, "bin1", "abc");
265  * ~~~~~~~~~~
266  *
267  * When you are finished using the `as_record` instance, you should release the
268  * resources allocated to it by calling `as_record_destroy()`.
269  *
270  * @param nbins The number of bins to initialize. Set to 0, if unknown.
271  *
272  * @return a pointer to the new as_record if successful, otherwise NULL.
273  *
274  * @relates as_record
275  */
276 as_record * as_record_new(uint16_t nbins);
277 
278 /**
279  * Initializes an as_record created on the stack.
280  *
281  * ~~~~~~~~~~{.c}
282  * as_record r;
283  * as_record_init(&r, 2);
284  * as_record_set_int64(&r, "bin1", 123);
285  * as_record_set_str(&r, "bin1", "abc");
286  * ~~~~~~~~~~
287  *
288  * When you are finished using the `as_record` instance, you should release the
289  * resources allocated to it by calling `as_record_destroy()`.
290  *
291  * @param rec The record to initialize.
292  * @param nbins The number of bins to initialize. Set to 0, if unknown.
293  *
294  * @return a pointer to the initialized as_record if successful, otherwise NULL.
295  *
296  * @relates as_record
297  */
298 as_record * as_record_init(as_record * rec, uint16_t nbins);
299 
300 /**
301  * Destroy the as_record and associated resources.
302  *
303  * @param rec The record to destroy.
304  *
305  * @relates as_record
306  */
307 void as_record_destroy(as_record * rec);
308 
309 /**
310  * Get the number of bins in the record.
311  *
312  * @return the number of bins in the record.
313  *
314  * @relates as_record
315  */
316 uint16_t as_record_numbins(const as_record * rec);
317 
318 /**
319  * Set specified bin's value to an as_bin_value.
320  *
321  * @param rec The record containing the bin.
322  * @param name The name of the bin.
323  * @param value The value of the bin.
324  *
325  * @return true on success, false on failure.
326  *
327  * @relates as_record
328  */
329 bool as_record_set(as_record * rec, const as_bin_name name, as_bin_value * value);
330 
331 /**
332  * Set specified bin's value to an int64_t.
333  *
334  * ~~~~~~~~~~{.c}
335  * as_record_set_int64(rec, "bin", 123);
336  * ~~~~~~~~~~
337  *
338  * @param rec The record containing the bin.
339  * @param name The name of the bin.
340  * @param value The value of the bin.
341  *
342  * @return true on success, false on failure.
343  *
344  * @relates as_record
345  */
346 bool as_record_set_int64(as_record * rec, const as_bin_name name, int64_t value);
347 
348 /**
349  * Set specified bin's value to a double.
350  *
351  * ~~~~~~~~~~{.c}
352  * as_record_set_double(rec, "bin", 123.456);
353  * ~~~~~~~~~~
354  *
355  * @param rec The record containing the bin.
356  * @param name The name of the bin.
357  * @param value The value of the bin.
358  *
359  * @return true on success, false on failure.
360  *
361  * @relates as_record
362  */
363 bool as_record_set_double(as_record * rec, const as_bin_name name, double value);
364 
365 /**
366  * Set specified bin's value to an NULL terminated string.
367  *
368  * ~~~~~~~~~~{.c}
369  * as_record_set_strp(rec, "bin", strdup("abc"), true);
370  * ~~~~~~~~~~
371  *
372  * @param rec The record containing the bin.
373  * @param name The name of the bin.
374  * @param value The value of the bin.
375  * @param free If true, then the value will be freed when the record is destroyed.
376  *
377  * @return true on success, false on failure.
378  *
379  * @relates as_record
380  */
381 bool as_record_set_strp(as_record * rec, const as_bin_name name, const char * value, bool free);
382 
383 /**
384  * Set specified bin's value to an NULL terminated string.
385  *
386  * ~~~~~~~~~~{.c}
387  * as_record_set_str(rec, "bin", "abc");
388  * ~~~~~~~~~~
389  *
390  * @param rec The record containing the bin.
391  * @param name The name of the bin.
392  * @param value The value of the bin. Must last for the lifetime of the record.
393  *
394  * @return true on success, false on failure.
395  *
396  * @relates as_record
397  */
398 static inline bool as_record_set_str(as_record * rec, const as_bin_name name, const char * value)
399 {
400  return as_record_set_strp(rec, name, value, false);
401 }
402 
403 /**
404  * Set specified bin's value to an NULL terminated GeoJSON string.
405  *
406  * ~~~~~~~~~~{.c}
407  * as_record_set_geojson_strp(rec, "bin", strdup("abc"), true);
408  * ~~~~~~~~~~
409  *
410  * @param rec The record containing the bin.
411  * @param name The name of the bin.
412  * @param value The value of the bin.
413  * @param free If true, then the value will be freed when the record is destroyed.
414  *
415  * @return true on success, false on failure.
416  *
417  * @relates as_record
418  */
419 bool as_record_set_geojson_strp(as_record * rec, const as_bin_name name, const char * value, bool free);
420 
421 /**
422  * Set specified bin's value to an NULL terminated GeoJSON string.
423  *
424  * ~~~~~~~~~~{.c}
425  * as_record_set_geojson_str(rec, "bin", "abc");
426  * ~~~~~~~~~~
427  *
428  * @param rec The record containing the bin.
429  * @param name The name of the bin.
430  * @param value The value of the bin. Must last for the lifetime of the record.
431  *
432  * @return true on success, false on failure.
433  *
434  * @relates as_record
435  */
436 static inline bool as_record_set_geojson_str(as_record * rec, const as_bin_name name, const char * value)
437 {
438  return as_record_set_geojson_strp(rec, name, value, false);
439 }
440 
441 /**
442  * Set specified bin's value to an NULL terminated string.
443  *
444  * ~~~~~~~~~~{.c}
445  * uint8_t * bytes = (uint8_t *) malloc(3);
446  * bytes[0] = 1;
447  * bytes[1] = 2;
448  * bytes[3] = 3;
449  *
450  * as_record_set_raw(rec, "bin", bytes, 3, true);
451  * ~~~~~~~~~~
452  *
453  * @param rec The record containing the bin.
454  * @param name The name of the bin.
455  * @param value The value of the bin.
456  * @param size The size of the value.
457  * @param free If true, then the value will be freed when the record is destroyed.
458  *
459  * @return true on success, false on failure.
460  *
461  * @relates as_record
462  */
463 bool as_record_set_rawp(as_record * rec, const as_bin_name name, const uint8_t * value, uint32_t size, bool free);
464 
465 /**
466  * Set specified bin's value to an as_bytes value of a specified type.
467  *
468  * ~~~~~~~~~~{.c}
469  * uint8_t * bytes = (uint8_t *) malloc(3);
470  * bytes[0] = 1;
471  * bytes[1] = 2;
472  * bytes[3] = 3;
473  *
474  * as_record_set_raw(rec, "bin", bytes, 3, true);
475  * ~~~~~~~~~~
476  *
477  * @param rec The record containing the bin.
478  * @param name The name of the bin.
479  * @param value The value of the bin.
480  * @param size The size of the value.
481  * @param type The as_bytes_type designation (AS_BYTES_*)
482  * @param free If true, then the value will be freed when the record is destroyed.
483  *
484  * @return true on success, false on failure.
485  *
486  * @relates as_record
487  */
488 bool as_record_set_raw_typep(as_record * rec, const as_bin_name name, const uint8_t * value, uint32_t size, as_bytes_type type, bool free);
489 
490 /**
491  * Set specified bin's value to an NULL terminated string.
492  *
493  * ~~~~~~~~~~{.c}
494  * uint8_t bytes[3] = {1,2,3};
495  * as_record_set_raw(rec, "bin", bytes, 3);
496  * ~~~~~~~~~~
497  *
498  * @param rec The record containing the bin.
499  * @param name The name of the bin.
500  * @param value The value of the bin.
501  * @param size The size of the value. Must last for the lifetime of the record.
502  *
503  * @return true on success, false on failure.
504  *
505  * @relates as_record
506  */
507 static inline bool as_record_set_raw(as_record * rec, const as_bin_name name, const uint8_t * value, uint32_t size)
508 {
509  return as_record_set_rawp(rec, name, value, size, false);
510 }
511 
512 /**
513  * Set specified bin's value to an as_integer.
514  *
515  * ~~~~~~~~~~{.c}
516  * as_record_set_integer(rec, "bin", as_integer_new(123));
517  * ~~~~~~~~~~
518  *
519  * @param rec The record containing the bin.
520  * @param name The name of the bin.
521  * @param value The value of the bin.
522  *
523  * @return true on success, false on failure.
524  *
525  * @relates as_record
526  */
527 bool as_record_set_integer(as_record * rec, const as_bin_name name, as_integer * value);
528 
529 /**
530  * Set specified bin's value to an as_double.
531  *
532  * ~~~~~~~~~~{.c}
533  * as_record_set_as_double(rec, "bin", as_double_new(123.456));
534  * ~~~~~~~~~~
535  *
536  * @param rec The record containing the bin.
537  * @param name The name of the bin.
538  * @param value The value of the bin.
539  *
540  * @return true on success, false on failure.
541  *
542  * @relates as_record
543  */
544 bool as_record_set_as_double(as_record * rec, const as_bin_name name, as_double * value);
545 
546 /**
547  * Set specified bin's value to an as_string.
548  *
549  * ~~~~~~~~~~{.c}
550  * as_record_set_string(rec, "bin", as_string_new("abc", false));
551  * ~~~~~~~~~~
552  *
553  * @param rec The record containing the bin.
554  * @param name The name of the bin.
555  * @param value The value of the bin.
556  *
557  * @return true on success, false on failure.
558  *
559  * @relates as_record
560  */
561 bool as_record_set_string(as_record * rec, const as_bin_name name, as_string * value);
562 
563 /**
564  * Set specified bin's value to an as_geojson.
565  *
566  * ~~~~~~~~~~{.c}
567  * as_record_set_geojson(rec, "bin", as_geojson_new("abc", false));
568  * ~~~~~~~~~~
569  *
570  * @param rec The record containing the bin.
571  * @param name The name of the bin.
572  * @param value The value of the bin.
573  *
574  * @return true on success, false on failure.
575  *
576  * @relates as_record
577  */
578 bool as_record_set_geojson(as_record * rec, const as_bin_name name, as_geojson * value);
579 
580 /**
581  * Set specified bin's value to an as_bytes.
582  *
583  * ~~~~~~~~~~{.c}
584  * as_record_set_integer(rec, "bin", bytes);
585  * ~~~~~~~~~~
586  *
587  * @param rec The record containing the bin.
588  * @param name The name of the bin.
589  * @param value The value of the bin.
590  *
591  * @return true on success, false on failure.
592  *
593  * @relates as_record
594  */
595 bool as_record_set_bytes(as_record * rec, const as_bin_name name, as_bytes * value);
596 
597 /**
598  * Set specified bin's value to an as_list.
599  *
600  * ~~~~~~~~~~{.c}
601  * as_arraylist list;
602  * as_arraylist_init(&list);
603  * as_arraylist_add_int64(&list, 1);
604  * as_arraylist_add_int64(&list, 2);
605  * as_arraylist_add_int64(&list, 3);
606  *
607  * as_record_set_list(rec, "bin", &list);
608  * ~~~~~~~~~~
609  *
610  * @param rec The record containing the bin.
611  * @param name The name of the bin.
612  * @param value The value of the bin.
613  *
614  * @return true on success, false on failure.
615  *
616  * @relates as_record
617  */
618 bool as_record_set_list(as_record * rec, const as_bin_name name, as_list * value);
619 
620 /**
621  * Set specified bin's value to an as_map.
622  *
623  * ~~~~~~~~~~{.c}
624  * as_hashmap map;
625  * as_hashmap_init(&map, 32);
626  * as_stringmap_set_int64(&map, "a", 1);
627  * as_stringmap_set_int64(&map, "b", 2);
628  * as_stringmap_set_int64(&map, "c", 3);
629  *
630  * as_record_set_map(rec, "bin", &map);
631  * ~~~~~~~~~~
632  *
633  * @param rec The record containing the bin.
634  * @param name The name of the bin.
635  * @param value The value of the bin.
636  *
637  * @return true on success, false on failure.
638  *
639  * @relates as_record
640  */
641 bool as_record_set_map(as_record * rec, const as_bin_name name, as_map * value);
642 
643 /**
644  * Set specified bin's value to as_nil.
645  *
646  * ~~~~~~~~~~{.c}
647  * as_record_set_nil(rec, "bin");
648  * ~~~~~~~~~~
649  *
650  * @param rec The record containing the bin.
651  * @param name The name of the bin.
652  *
653  * @return true on success, false on failure.
654  *
655  * @relates as_record
656  */
657 bool as_record_set_nil(as_record * rec, const as_bin_name name);
658 
659 /**
660  * Get specified bin's value.
661  *
662  * ~~~~~~~~~~{.c}
663  * as_val * value = as_record_get(rec, "bin");
664  * ~~~~~~~~~~
665  *
666  * @param rec The record containing the bin.
667  * @param name The name of the bin.
668  *
669  * @return the value if it exists, otherwise NULL.
670  *
671  * @relates as_record
672  */
673 as_bin_value * as_record_get(const as_record * rec, const as_bin_name name);
674 
675 /**
676  * Get specified bin's value as an int64_t.
677  *
678  * ~~~~~~~~~~{.c}
679  * int64_t value = as_record_get_int64(rec, "bin", INT64_MAX);
680  * ~~~~~~~~~~
681  *
682  * @param rec The record containing the bin.
683  * @param name The name of the bin.
684  * @param fallback The default value to use, if the bin doesn't exist or is not an integer.
685  *
686  * @return the value if it exists, otherwise 0.
687  *
688  * @relates as_record
689  */
690 int64_t as_record_get_int64(const as_record * rec, const as_bin_name name, int64_t fallback);
691 
692 /**
693  * Get specified bin's value as a double.
694  *
695  * ~~~~~~~~~~{.c}
696  * double value = as_record_get_double(rec, "bin", -1.0);
697  * ~~~~~~~~~~
698  *
699  * @param rec The record containing the bin.
700  * @param name The name of the bin.
701  * @param fallback The default value to use, if the bin doesn't exist or is not an integer.
702  *
703  * @return the value if it exists, otherwise 0.
704  *
705  * @relates as_record
706  */
707 double as_record_get_double(const as_record * rec, const as_bin_name name, double fallback);
708 
709 /**
710  * Get specified bin's value as an NULL terminated string.
711  *
712  * ~~~~~~~~~~{.c}
713  * char * value = as_record_get_str(rec, "bin");
714  * ~~~~~~~~~~
715  *
716  * @param rec The record containing the bin.
717  * @param name The name of the bin.
718  *
719  * @return the value if it exists, otherwise NULL.
720  *
721  * @relates as_record
722  */
723 char * as_record_get_str(const as_record * rec, const as_bin_name name);
724 
725 /**
726  * Get specified bin's value as an NULL terminated GeoJSON string.
727  *
728  * ~~~~~~~~~~{.c}
729  * char * value = as_record_get_geojson_str(rec, "bin");
730  * ~~~~~~~~~~
731  *
732  * @param rec The record containing the bin.
733  * @param name The name of the bin.
734  *
735  * @return the value if it exists, otherwise NULL.
736  *
737  * @relates as_record
738  */
739 char * as_record_get_geojson_str(const as_record * rec, const as_bin_name name);
740 
741 /**
742  * Get specified bin's value as an as_integer.
743  *
744  * ~~~~~~~~~~{.c}
745  * as_integer * value = as_record_get_integer(rec, "bin");
746  * ~~~~~~~~~~
747  *
748  * @param rec The record containing the bin.
749  * @param name The name of the bin.
750  *
751  * @return the value if it exists, otherwise NULL.
752  *
753  * @relates as_record
754  */
755 as_integer * as_record_get_integer(const as_record * rec, const as_bin_name name);
756 
757 /**
758  * Get specified bin's value as an as_double.
759  *
760  * ~~~~~~~~~~{.c}
761  * as_double * value = as_record_get_as_double(rec, "bin");
762  * ~~~~~~~~~~
763  *
764  * @param rec The record containing the bin.
765  * @param name The name of the bin.
766  *
767  * @return the value if it exists, otherwise NULL.
768  *
769  * @relates as_record
770  */
771 as_double * as_record_get_as_double(const as_record * rec, const as_bin_name name);
772 
773 /**
774  * Get specified bin's value as an as_string.
775  *
776  * ~~~~~~~~~~{.c}
777  * as_string * value = as_record_get_string(rec, "bin");
778  * ~~~~~~~~~~
779  *
780  * @param rec The record containing the bin.
781  * @param name The name of the bin.
782  *
783  * @return the value if it exists, otherwise NULL.
784  *
785  * @relates as_record
786  */
787 as_string * as_record_get_string(const as_record * rec, const as_bin_name name);
788 
789 /**
790  * Get specified bin's value as an as_geojson.
791  *
792  * ~~~~~~~~~~{.c}
793  * as_geojson * value = as_record_get_geojson(rec, "bin");
794  * ~~~~~~~~~~
795  *
796  * @param rec The record containing the bin.
797  * @param name The name of the bin.
798  *
799  * @return the value if it exists, otherwise NULL.
800  *
801  * @relates as_record
802  */
803 as_geojson * as_record_get_geojson(const as_record * rec, const as_bin_name name);
804 
805 /**
806  * Get specified bin's value as an as_bytes.
807  *
808  * ~~~~~~~~~~{.c}
809  * as_bytes * value = as_record_get_bytes(rec, "bin");
810  * ~~~~~~~~~~
811  *
812  * @param rec The record containing the bin.
813  * @param name The name of the bin.
814  *
815  * @return the value if it exists, otherwise NULL.
816  *
817  * @relates as_record
818  */
819 as_bytes * as_record_get_bytes(const as_record * rec, const as_bin_name name);
820 
821 /**
822  * Get specified bin's value as an as_list.
823  *
824  * ~~~~~~~~~~{.c}
825  * as_list * value = as_record_get_list(rec, "bin");
826  * ~~~~~~~~~~
827  *
828  * @param rec The record containing the bin.
829  * @param name The name of the bin.
830  *
831  * @return the value if it exists, otherwise NULL.
832  *
833  * @relates as_record
834  */
835 as_list * as_record_get_list(const as_record * rec, const as_bin_name name);
836 
837 /**
838  * Get specified bin's value as an as_map.
839  *
840  * ~~~~~~~~~~{.c}
841  * as_map * value = as_record_get_map(rec, "bin");
842  * ~~~~~~~~~~
843  *
844  * @param rec The record containing the bin.
845  * @param name The name of the bin.
846  *
847  * @return the value if it exists, otherwise NULL.
848  *
849  * @relates as_record
850  */
851 as_map * as_record_get_map(const as_record * rec, const as_bin_name name);
852 
853 /******************************************************************************
854  * ITERATION FUNCTIONS
855  ******************************************************************************/
856 
857 /**
858  * Iterate over each bin in the record and invoke the callback function.
859  *
860  * ~~~~~~~~~~{.c}
861  * bool print_bin(const char * name, const as_val * value, void * udata) {
862  * char * sval = as_val_tostring(value);
863  * printf("bin: name=%s, value=%s\n", name, sval);
864  * free(sval);
865  * return true;
866  * }
867  *
868  * as_record_foreach(rec, print_bin, NULL);
869  * ~~~~~~~~~~
870  *
871  * If the callback returns true, then iteration will continue to the next bin.
872  * Otherwise, the iteration will halt and `as_record_foreach()` will return
873  * false.
874  *
875  * @param rec The record containing the bins to iterate over.
876  * @param callback The callback to invoke for each bin.
877  * @param udata User-data provided for the callback.
878  *
879  * @return true if iteration completes fully. false if iteration was aborted.
880  *
881  * @relates as_record
882  */
883 bool as_record_foreach(const as_record * rec, as_rec_foreach_callback callback, void * udata);
884 
885 /******************************************************************************
886  * CONVERSION FUNCTIONS
887  ******************************************************************************/
888 
889 /**
890  * Convert to an as_val.
891  *
892  * @relates as_record
893  */
894 static inline as_val * as_record_toval(const as_record * rec)
895 {
896  return (as_val *) rec;
897 }
898 
899 /**
900  * Convert from an as_val.
901  *
902  * @relates as_record
903  */
904 static inline as_record * as_record_fromval(const as_val * v)
905 {
906  return (as_record *) as_util_fromval(v, AS_REC, as_rec);
907 }
908 
909 #ifdef __cplusplus
910 } // end extern "C"
911 #endif
as_record * as_record_new(uint16_t nbins)
AS_REC
Definition: as_val.h:213
static bool as_record_set_raw(as_record *rec, const as_bin_name name, const uint8_t *value, uint32_t size)
Definition: as_record.h:507
as_bin_value * as_record_get(const as_record *rec, const as_bin_name name)
uint8_t type
Definition: as_proto.h:828
Definition: as_rec.h:76
as_double * as_record_get_as_double(const as_record *rec, const as_bin_name name)
char * as_record_get_str(const as_record *rec, const as_bin_name name)
Definition: as_map.h:61
bool as_record_set_list(as_record *rec, const as_bin_name name, as_list *value)
as_list * as_record_get_list(const as_record *rec, const as_bin_name name)
static as_record * as_record_fromval(const as_val *v)
Definition: as_record.h:904
bool(* as_rec_foreach_callback)(const char *name, const as_val *value, void *udata)
Definition: as_rec.h:64
#define as_util_fromval(object, type_id, type)
Definition: as_util.h:42
as_bins bins
Definition: as_record.h:206
double as_record_get_double(const as_record *rec, const as_bin_name name, double fallback)
bool as_record_set_bytes(as_record *rec, const as_bin_name name, as_bytes *value)
as_string * as_record_get_string(const as_record *rec, const as_bin_name name)
bool as_record_set_int64(as_record *rec, const as_bin_name name, int64_t value)
bool as_record_foreach(const as_record *rec, as_rec_foreach_callback callback, void *udata)
uint16_t gen
Definition: as_record.h:188
bool as_record_set(as_record *rec, const as_bin_name name, as_bin_value *value)
bool as_record_set_string(as_record *rec, const as_bin_name name, as_string *value)
Definition: as_val.h:57
as_map * as_record_get_map(const as_record *rec, const as_bin_name name)
static bool as_record_set_str(as_record *rec, const as_bin_name name, const char *value)
Definition: as_record.h:398
uint32_t ttl
Definition: as_record.h:201
bool as_record_set_strp(as_record *rec, const as_bin_name name, const char *value, bool free)
bool as_record_set_integer(as_record *rec, const as_bin_name name, as_integer *value)
as_record * as_record_init(as_record *rec, uint16_t nbins)
as_geojson * as_record_get_geojson(const as_record *rec, const as_bin_name name)
bool as_record_set_geojson_strp(as_record *rec, const as_bin_name name, const char *value, bool free)
int64_t as_record_get_int64(const as_record *rec, const as_bin_name name, int64_t fallback)
static bool as_record_set_geojson_str(as_record *rec, const as_bin_name name, const char *value)
Definition: as_record.h:436
uint16_t as_record_numbins(const as_record *rec)
as_rec _
Definition: as_record.h:176
void as_record_destroy(as_record *rec)
bool as_record_set_as_double(as_record *rec, const as_bin_name name, as_double *value)
char as_bin_name[AS_BIN_NAME_MAX_SIZE]
Definition: as_bin.h:52
as_bytes_type
Definition: as_bytes.h:38
bool as_record_set_geojson(as_record *rec, const as_bin_name name, as_geojson *value)
as_integer * as_record_get_integer(const as_record *rec, const as_bin_name name)
bool as_record_set_double(as_record *rec, const as_bin_name name, double value)
char * as_record_get_geojson_str(const as_record *rec, const as_bin_name name)
bool as_record_set_rawp(as_record *rec, const as_bin_name name, const uint8_t *value, uint32_t size, bool free)
static as_val * as_record_toval(const as_record *rec)
Definition: as_record.h:894
Definition: as_key.h:199
as_bytes * as_record_get_bytes(const as_record *rec, const as_bin_name name)
bool as_record_set_raw_typep(as_record *rec, const as_bin_name name, const uint8_t *value, uint32_t size, as_bytes_type type, bool free)
bool as_record_set_map(as_record *rec, const as_bin_name name, as_map *value)
bool as_record_set_nil(as_record *rec, const as_bin_name name)
as_key key
Definition: as_record.h:183