All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
target/Linux-x86_64/include/aerospike/aerospike_llist.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 /**
24  * Functionality related to Large List Data Type
25  */
26 
27 #pragma once
28 
29 #include <aerospike/aerospike.h>
30 #include <aerospike/as_error.h>
31 #include <aerospike/as_ldt.h>
32 #include <aerospike/as_operations.h>
33 #include <aerospike/as_policy.h>
34 #include <aerospike/as_status.h>
35 #include <aerospike/as_key.h>
36 #include <aerospike/as_val.h>
37 #include <aerospike/as_boolean.h>
38 
39 /******************************************************************************
40  * FUNCTIONS
41  *****************************************************************************/
42 
43 /**
44  * Add a value into the llist.
45  *
46  * ~~~~~~~~~~{.c}
47  * as_key key;
48  * as_key_init(&key, "myns", "myset", "mykey");
49  *
50  * as_ldt llist;
51  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
52  *
53  * as_integer ival;
54  * as_integer_init(&ival, 123);
55  *
56  * if ( aerospike_llist_add(&as, &err, NULL, &key, &llist, (as_val *) &ival) != AEROSPIKE_OK ) {
57  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
58  * }
59  * ~~~~~~~~~~
60  *
61  * @param as The aerospike instance to use for this operation.
62  * @param err The as_error to be populated if an error occurs.
63  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
64  * @param key The key of the record.
65  * @param ldt The ldt bin to insert values to.
66  * @param val The value to insert into the llist.
67  *
68  * @return AEROSPIKE_OK if successful. Otherwise an error.
69  *
70  * @ingroup ldt_operations
71  */
73  aerospike * as, as_error * err, const as_policy_apply * policy,
74  const as_key * key, const as_ldt * ldt, const as_val * val);
75 
76 /**
77  * Add a list of values into the llist.
78  *
79  * ~~~~~~~~~~{.c}
80  * as_key key;
81  * as_key_init(&key, "myns", "myset", "mykey");
82  *
83  * as_ldt llist;
84  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
85  *
86  *
87  * as_arraylist vals;
88  * as_arraylist_inita(&vals, 2);
89  * as_string s;
90  * as_string_init(s,"a string",false);
91  * as_arraylist_append_string(&vals, s);
92  * as_arraylist_append_int64(&vals, 35);
93  *
94  * if ( aerospike_llist_add_all(&as, &err, NULL, &key, &llist, (as_list *)vals) != AEROSPIKE_OK ) {
95  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
96  * }
97  *
98  * ~~~~~~~~~~
99  *
100  * @param as The aerospike instance to use for this operation.
101  * @param err The as_error to be populated if an error occurs.
102  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
103  * @param key The key of the record.
104  * @param ldt The ldt bin to insert values to.
105  * @param vals The list of values to insert into the llist.
106  *
107  * @return AEROSPIKE_OK if successful. Otherwise an error.
108  *
109  * @ingroup ldt_operations
110  */
112  aerospike * as, as_error * err, const as_policy_apply * policy,
113  const as_key * key, const as_ldt * ldt, const as_list * vals);
114 
115 /**
116  * Search for a value in the llist.
117  *
118  * ~~~~~~~~~~{.c}
119  * as_key key;
120  * as_key_init(&key, "myns", "myset", "mykey");
121  *
122  * as_ldt llist;
123  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
124  *
125  * as_integer ival;
126  * as_integer_init(&ival, 123);
127  *
128  * as_integer search_val;
129  * as_integer_init(&search_val, 42);
130  *
131  * as_list *result_list = NULL;
132  *
133  * if ( aerospike_llist_find(&as, &err, NULL, &key, &llist, &ival, &search_val, &result_list ) != AEROSPIKE_OK ) {
134  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
135  * }
136  * else {
137  * // do logic because element exists
138  * }
139  * ~~~~~~~~~~
140  *
141  * @param as The aerospike instance to use for this operation.
142  * @param err The as_error to be populated if an error occurs.
143  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
144  * @param key The key of the record.
145  * @param ldt The llist bin to lookup from. If not an llist bin, will return error.
146  * @param search_val The search value
147  * @param result_list The returned list of values
148  *
149  * @return AEROSPIKE_OK if successful. Otherwise an error.
150  *
151  * @ingroup ldt_operations
152  */
154  aerospike * as, as_error * err, const as_policy_apply * policy,
155  const as_key * key, const as_ldt * ldt, const as_val * search_val,
156  as_list ** elements );
157 
158 
159 /**
160  * Given an llist bin, return all values in the list.
161  *
162  * ~~~~~~~~~~{.c}
163  * as_key key;
164  * as_key_init(&key, "myns", "myset", "mykey");
165  *
166  * as_ldt llist;
167  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
168  *
169  * as_list *result_list = NULL;
170  *
171  * if ( aerospike_llist_filter(&as, &err, NULL, &key, &llist,
172  * &result_list) != AEROSPIKE_OK ) {
173  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
174  * }
175  * else {
176  * // process the returned elements
177  * as_arraylist_destroy(result_list);
178  * }
179  * ~~~~~~~~~~
180  *
181  * @param as The aerospike instance to use for this operation.
182  * @param err The as_error to be populated if an error occurs.
183  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
184  * @param key The key of the record.
185  * @param ldt The llist bin to search from. If not an llist bin, will return error.
186  * @param list The pointer to a list of elements returned from search function. Pointer should
187  * be NULL passed in.
188  *
189  * @return AEROSPIKE_OK if successful. Otherwise an error.
190  *
191  * @ingroup ldt_operations
192  */
194  aerospike * as, as_error * err, const as_policy_apply * policy,
195  const as_key * key, const as_ldt * ldt, as_list ** elements );
196 
197 /**
198  * Given an llist bin, filter the collection of objects using the given
199  * filter function. If no filter function is specified, return all values.
200  *
201  * ~~~~~~~~~~{.c}
202  * as_key key;
203  * as_key_init(&key, "myns", "myset", "mykey");
204  *
205  * as_ldt llist;
206  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
207  *
208  * as_list *result_list = NULL;
209  *
210  * if ( aerospike_llist_filter(&as, &err, NULL, &key, &llist,
211  * "search_filter", NULL, &result_list) != AEROSPIKE_OK ) {
212  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
213  * }
214  * else {
215  * // process the returned elements
216  * as_arraylist_destroy(result_list);
217  * }
218  * ~~~~~~~~~~
219  *
220  * @param as The aerospike instance to use for this operation.
221  * @param err The as_error to be populated if an error occurs.
222  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
223  * @param key The key of the record.
224  * @param ldt The llist bin to search from. If not an llist bin, will return error.
225  * @param filter The name of the User-Defined-Function to use as a search filter.
226  * @param fargs The list of parameters passed in to the User-Defined-Function filter.
227  * @param list The pointer to a list of elements returned from search function. Pointer should
228  * be NULL passed in.
229  *
230  * @return AEROSPIKE_OK if successful. Otherwise an error.
231  *
232  * @ingroup ldt_operations
233  */
235  aerospike * as, as_error * err, const as_policy_apply * policy,
236  const as_key * key, const as_ldt * ldt,
237  const as_udf_function_name filter, const as_list *filter_args,
238  as_list ** elements );
239 
240 /**
241  * Look up a llist and find how many elements it contains
242  *
243  * ~~~~~~~~~~{.c}
244  * as_key key;
245  * as_key_init(&key, "myns", "myset", "mykey");
246  *
247  * as_ldt llist;
248  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
249  * uint32_t llist_size = 0;
250  *
251  * if ( aerospike_llist_size(&as, &err, NULL, &key, &llist, &llist_size) != AEROSPIKE_OK ) {
252  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
253  * }
254  * ~~~~~~~~~~
255  *
256  * @param as The aerospike instance to use for this operation.
257  * @param err The as_error to be populated if an error occurs.
258  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
259  * @param key The key of the record.
260  * @param ldt The llist to operate on. If not an llist bin, will return error.
261  * @param n Return the number of elements in the llist.
262  *
263  * @return AEROSPIKE_OK if successful. Otherwise an error.
264  *
265  * @ingroup ldt_operations
266  */
268  aerospike * as, as_error * err, const as_policy_apply * policy,
269  const as_key * key, const as_ldt * ldt,
270  uint32_t *n
271  );
272 
273 /**
274  * Delete the given value from the llist
275  *
276  * ~~~~~~~~~~{.c}
277  * as_key key;
278  * as_key_init(&key, "myns", "myset", "mykey");
279  *
280  * as_ldt llist;
281  * as_ldt_init(&llist, "llist", AS_LDT_LLIST, NULL);
282  *
283  * as_integer ival;
284  * as_integer_init(&ival, 123);
285  *
286  * if ( aerospike_llist_remove(&as, &err, NULL, &key, &llist, &ival) != AEROSPIKE_OK ) {
287  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
288  * }
289  * ~~~~~~~~~~
290  *
291  * @param as The aerospike instance to use for this operation.
292  * @param err The as_error to be populated if an error occurs.
293  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
294  * @param key The key of the record.
295  * @param ldt The llist bin to delete from. If not an llist bin, will return error.
296  * @param val The value to delete from the set.
297  *
298  * @return AEROSPIKE_OK if successful. Otherwise an error.
299  *
300  * @ingroup ldt_operations
301  */
303  aerospike * as, as_error * err, const as_policy_apply * policy,
304  const as_key * key, const as_ldt * ldt, const as_val *element
305  );
306 
307 /**
308  * Destroy the llist bin
309  *
310  * ~~~~~~~~~~{.c}
311  * as_key key;
312  * as_key_init(&key, "myns", "myset", "mykey");
313  *
314  * as_ldt llist;
315  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
316  *
317  * if ( aerospike_llist_destroy(&as, &err, NULL, &key, &llist) != AEROSPIKE_OK ) {
318  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
319  * }
320  * ~~~~~~~~~~
321  *
322  * @param as The aerospike instance to use for this operation.
323  * @param err The as_error to be populated if an error occurs.
324  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
325  * @param key The key of the record.
326  * @param ldt The llist bin to destroy. If not an llist bin, will return error.
327  *
328  * @return AEROSPIKE_OK if successful. Otherwise an error.
329  *
330  * @ingroup ldt_operations
331  */
333  aerospike * as, as_error * err, const as_policy_apply * policy,
334  const as_key * key, const as_ldt * ldt
335  );
336 
as_status aerospike_llist_filter(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_udf_function_name filter, const as_list *filter_args, as_list **elements)
as_status aerospike_llist_scan(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, as_list **elements)
as_status aerospike_llist_remove(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_val *element)
as_status aerospike_llist_find(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_val *search_val, as_list **elements)
as_status aerospike_llist_size(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, uint32_t *n)
as_status aerospike_llist_destroy(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt)
as_status aerospike_llist_add(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_val *val)
char as_udf_function_name[AS_UDF_FUNCTION_MAX_SIZE]
as_status aerospike_llist_add_all(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_list *vals)