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