All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
_bin.h
Go to the documentation of this file.
1 /******************************************************************************
2  * Copyright 2008-2013 by Aerospike.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to
6  * deal in the Software without restriction, including without limitation the
7  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8  * sell copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20  * IN THE SOFTWARE.
21  *****************************************************************************/
22 
23 #pragma once
24 
25 #include <aerospike/as_bin.h>
26 #include <aerospike/as_integer.h>
27 #include <aerospike/as_string.h>
28 #include <aerospike/as_bytes.h>
29 #include <aerospike/as_list.h>
30 #include <aerospike/as_map.h>
31 #include <aerospike/as_val.h>
32 
33 /******************************************************************************
34  * MACROS
35  *****************************************************************************/
36 
37 /**
38  * Initializes a stack allocated `as_bins` (__bins) and allocates `__capacity`
39  * number of entries on the stack.
40  *
41  * ~~~~~~~~~~{.c}
42  * as_bins bins;
43  * as_bins_init(&bins, 2);
44  * as_bins_append(&bins, "bin1", as_integer_new(123));
45  * as_bins_append(&bins, "bin2", as_integer_new(456));
46  * ~~~~~~~~~~
47  *
48  * @param __bins The `as_bins *` to initialize.
49  * @param __capacity The number of `as_bins.entries` to allocate on the
50  * stack.
51  */
52 #define as_bins_inita(__bins, __capacity) \
53  (__bins)->_free = false;\
54  (__bins)->capacity = __capacity;\
55  (__bins)->size = 0;\
56  (__bins)->entries = (as_bin *) alloca(sizeof(as_bin) * __capacity);
57 
58 /******************************************************************************
59  * as_bin FUNCTIONS
60  *****************************************************************************/
61 
62 /**
63  * Intializes an `as_bin` with the given name and value.
64  *
65  * ~~~~~~~~~~{.c}
66  * as_bin bin;
67  * as_bin_init(&bin, "bin1", as_integer_new(123));
68  * ~~~~~~~~~~
69  *
70  * Use `as_bin_destroy()` to free the resources allocated by this function.
71  *
72  * @param bin The `as_bin` to initialize.
73  * @param name The name of the bin.
74  * @param value The value of the bin.
75  *
76  * @return The initialized `as_bin` on success. Otherwsie NULL.
77  */
78 as_bin * as_bin_init(as_bin * bin, const as_bin_name name, as_bin_value * value);
79 
80 /**
81  * Initialize a stack allocated `as_bin` to a int64_t value.
82  *
83  * ~~~~~~~~~~{.c}
84  * as_bin bin;
85  * as_bin_init_int64(&key, "abc", 123);
86  * ~~~~~~~~~~
87  *
88  * Use `as_bin_destroy()` to release resources allocated to `as_bin`.
89  *
90  * @param name The name of the bin.
91  * @param value The value of the value.
92  *
93  * @return The initialized `as_bin` on success. Otherwise NULL.
94  */
95 as_bin * as_bin_init_int64(as_bin * bin, const as_bin_name name, int64_t value);
96 
97 /**
98  * Initialize a stack allocated `as_bin` to a NULL-terminated string value.
99  *
100  * ~~~~~~~~~~{.c}
101  * as_bin bin;
102  * as_bin_init_str(&key, "abc", "def", false);
103  * ~~~~~~~~~~
104  *
105  * Use `as_bin_destroy()` to release resources allocated to `as_bin`.
106  *
107  * @param name The name of the bin.
108  * @param value The value of the value.
109  * @param free If true, then the value is freed when the bin is destroyed.
110  *
111  * @return The initialized `as_bin` on success. Otherwise NULL.
112  */
113 as_bin * as_bin_init_str(as_bin * bin, const as_bin_name name, const char * value, bool free);
114 
115 /**
116  * Initialize a stack allocated `as_key` to a raw bytes value.
117  *
118  * ~~~~~~~~~~{.c}
119  * uint8_t rgb[3] = {254,254,120};
120  *
121  * as_bin bin;
122  * as_bin_init_raw(&key, "abc", rgb, 3, false);
123  * ~~~~~~~~~~
124  *
125  * Use `as_bin_destroy()` to release resources allocated to `as_bin`.
126  *
127  * @param name The name of the bin.
128  * @param value The value of the value.
129  * @param free If true, then the value is freed when the bin is destroyed.
130  *
131  * @return The initialized `as_bin` on success. Otherwise NULL.
132  */
133 as_bin * as_bin_init_raw(as_bin * bin, const as_bin_name name, const uint8_t * value, uint32_t size, bool free);
134 
135 /**
136  * Initialize a stack allocated `as_key` to a an `as_key_value`.
137  *
138  * ~~~~~~~~~~{.c}
139  * as_bin bin;
140  * as_bin_init_nil(&key, "abc");
141  * ~~~~~~~~~~
142  *
143  * Use `as_bin_destroy()` to release resources allocated to `as_bin`.
144  *
145  * @param name The name of the bin.
146  * @param value The value of the value.
147  *
148  * @return The initialized `as_bin` on success. Otherwise NULL.
149  */
151 
152 /**
153  * Destroy the given `as_bin` and associated resources.
154  *
155  * ~~~~~~~~~~{.c}
156  * as_bin_destroy(bin);
157  * ~~~~~~~~~~
158  *
159  * @param bin The `as_bin` to destroy.
160  */
161 void as_bin_destroy(as_bin * bin);
162 
163 /******************************************************************************
164  * as_bins FUNCTIONS
165  *****************************************************************************/
166 
167 /**
168  * Intializes a stack allocated `as_bins`. The capacity specifies the number
169  * of `as_bins.entries` to allocate on the heap.
170  *
171  * ~~~~~~~~~~{.c}
172  * as_bins bins;
173  * as_bins_init(&bins, 2);
174  * as_bins_append(&bins, "bin1", as_integer_new(123));
175  * as_bins_append(&bins, "bin2", as_integer_new(456));
176  * ~~~~~~~~~~
177  *
178  * Use `as_bins_destroy()` to free the resources allocated by this function.
179  *
180  * @param bins The `as_bins` to initialize.
181  * @param capacity The number of `as_bins.entries` to allocate on the heap.
182  *
183  * @return The initialized `as_bins` on success. Otherwsie NULL.
184  */
185 as_bins * as_bins_init(as_bins * bins, uint16_t capacity);
186 
187 /**
188  * Destroy the `as_bins` and associated resources.
189  *
190  * ~~~~~~~~~~{.c}
191  * as_bins_destroy(bins);
192  * ~~~~~~~~~~
193  *
194  * @param bins The `as_bins` to destroy.
195  */
196 void as_bins_destroy(as_bins * bins);
197 
198 /**
199  * Append a bin to the sequence of bins.
200  *
201  * @param bins The `as_bins` to append the bin to.
202  * @param name The name of the bin to append.
203  * @param value The value of the bin to append.
204  *
205  * @return true on success. Otherswise an error occurred.
206  */
207 bool as_bins_append(as_bins * bins, as_bin_name name, as_bin_value * value);
208