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