All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
aerospike_llist.h
Go to the documentation of this file.
1 /*
2  * Copyright 2008-2014 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 /**
20  * Functionality related to Large List Data Type
21  */
22 
23 #include <aerospike/aerospike.h>
24 #include <aerospike/as_error.h>
25 #include <aerospike/as_ldt.h>
27 #include <aerospike/as_policy.h>
28 #include <aerospike/as_status.h>
29 #include <aerospike/as_key.h>
30 #include <aerospike/as_val.h>
31 #include <aerospike/as_boolean.h>
32 
33 /******************************************************************************
34  * FUNCTIONS
35  *****************************************************************************/
36 
37 /**
38  * Add a value into the llist.
39  *
40  * ~~~~~~~~~~{.c}
41  * as_key key;
42  * as_key_init(&key, "myns", "myset", "mykey");
43  *
44  * as_ldt llist;
45  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
46  *
47  * as_integer ival;
48  * as_integer_init(&ival, 123);
49  *
50  * if ( aerospike_llist_add(&as, &err, NULL, &key, &llist, (as_val *) &ival) != AEROSPIKE_OK ) {
51  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
52  * }
53  * ~~~~~~~~~~
54  *
55  * @param as The aerospike instance to use for this operation.
56  * @param err The as_error to be populated if an error occurs.
57  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
58  * @param key The key of the record.
59  * @param ldt The ldt bin to insert values to.
60  * @param val The value to insert into the llist.
61  *
62  * @return AEROSPIKE_OK if successful. Otherwise an error.
63  *
64  * @ingroup ldt_operations
65  */
67  aerospike * as, as_error * err, const as_policy_apply * policy,
68  const as_key * key, const as_ldt * ldt, const as_val * val);
69 
70 /**
71  * Add a list of values into the llist.
72  *
73  * ~~~~~~~~~~{.c}
74  * as_key key;
75  * as_key_init(&key, "myns", "myset", "mykey");
76  *
77  * as_ldt llist;
78  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
79  *
80  *
81  * as_arraylist vals;
82  * as_arraylist_inita(&vals, 2);
83  * as_string s;
84  * as_string_init(s,"a string",false);
85  * as_arraylist_append_string(&vals, s);
86  * as_arraylist_append_int64(&vals, 35);
87  *
88  * if ( aerospike_llist_add_all(&as, &err, NULL, &key, &llist, (as_list *)vals) != AEROSPIKE_OK ) {
89  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
90  * }
91  *
92  * ~~~~~~~~~~
93  *
94  * @param as The aerospike instance to use for this operation.
95  * @param err The as_error to be populated if an error occurs.
96  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
97  * @param key The key of the record.
98  * @param ldt The ldt bin to insert values to.
99  * @param vals The list of values to insert into the llist.
100  *
101  * @return AEROSPIKE_OK if successful. Otherwise an error.
102  *
103  * @ingroup ldt_operations
104  */
106  aerospike * as, as_error * err, const as_policy_apply * policy,
107  const as_key * key, const as_ldt * ldt, const as_list * vals);
108 
109 /**
110  * Search for a value in the llist.
111  *
112  * ~~~~~~~~~~{.c}
113  * as_key key;
114  * as_key_init(&key, "myns", "myset", "mykey");
115  *
116  * as_ldt llist;
117  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
118  *
119  * as_integer search_val;
120  * as_integer_init(&search_val, 42);
121  *
122  * as_list *result_list = NULL;
123  *
124  * if ( aerospike_llist_find(&as, &err, NULL, &key, &llist, &search_val, &result_list ) != AEROSPIKE_OK ) {
125  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
126  * }
127  * else {
128  * // do logic because element exists
129  * }
130  * ~~~~~~~~~~
131  *
132  * @param as The aerospike instance to use for this operation.
133  * @param err The as_error to be populated if an error occurs.
134  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
135  * @param key The key of the record.
136  * @param ldt The llist bin to lookup from. If not an llist bin, will return error.
137  * @param search_val The search value
138  * @param result_list The returned list of values
139  *
140  * @return AEROSPIKE_OK if successful. Otherwise an error.
141  *
142  * @ingroup ldt_operations
143  */
145  aerospike * as, as_error * err, const as_policy_apply * policy,
146  const as_key * key, const as_ldt * ldt, const as_val * search_val,
147  as_list ** elements );
148 
149 
150 /**
151  * Given an llist bin, return all values in the list.
152  *
153  * ~~~~~~~~~~{.c}
154  * as_key key;
155  * as_key_init(&key, "myns", "myset", "mykey");
156  *
157  * as_ldt llist;
158  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
159  *
160  * as_list *result_list = NULL;
161  *
162  * if ( aerospike_llist_filter(&as, &err, NULL, &key, &llist,
163  * &result_list) != AEROSPIKE_OK ) {
164  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
165  * }
166  * else {
167  * // process the returned elements
168  * as_arraylist_destroy(result_list);
169  * }
170  * ~~~~~~~~~~
171  *
172  * @param as The aerospike instance to use for this operation.
173  * @param err The as_error to be populated if an error occurs.
174  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
175  * @param key The key of the record.
176  * @param ldt The llist bin to search from. If not an llist bin, will return error.
177  * @param list The pointer to a list of elements returned from search function. Pointer should
178  * be NULL passed in.
179  *
180  * @return AEROSPIKE_OK if successful. Otherwise an error.
181  *
182  * @ingroup ldt_operations
183  */
185  aerospike * as, as_error * err, const as_policy_apply * policy,
186  const as_key * key, const as_ldt * ldt, as_list ** elements );
187 
188 /**
189  * Given an llist bin, filter the collection of objects using the given
190  * filter function. If no filter function is specified, return all values.
191  *
192  * ~~~~~~~~~~{.c}
193  * as_key key;
194  * as_key_init(&key, "myns", "myset", "mykey");
195  *
196  * as_ldt llist;
197  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
198  *
199  * as_list *result_list = NULL;
200  *
201  * if ( aerospike_llist_filter(&as, &err, NULL, &key, &llist,
202  * "search_filter", NULL, &result_list) != AEROSPIKE_OK ) {
203  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
204  * }
205  * else {
206  * // process the returned elements
207  * as_arraylist_destroy(result_list);
208  * }
209  * ~~~~~~~~~~
210  *
211  * @param as The aerospike instance to use for this operation.
212  * @param err The as_error to be populated if an error occurs.
213  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
214  * @param key The key of the record.
215  * @param ldt The llist bin to search from. If not an llist bin, will return error.
216  * @param filter The name of the User-Defined-Function to use as a search filter.
217  * @param fargs The list of parameters passed in to the User-Defined-Function filter.
218  * @param list The pointer to a list of elements returned from search function. Pointer should
219  * be NULL passed in.
220  *
221  * @return AEROSPIKE_OK if successful. Otherwise an error.
222  *
223  * @ingroup ldt_operations
224  */
226  aerospike * as, as_error * err, const as_policy_apply * policy,
227  const as_key * key, const as_ldt * ldt,
228  const as_udf_function_name filter, const as_list *filter_args,
229  as_list ** elements );
230 
231 /**
232  * Given an llist bin, return the key values from MIN to MAX, and then
233  * filter the returned collection of objects using the given
234  * filter function. If no filter function is specified, return all values.
235  *
236  * ~~~~~~~~~~{.c}
237  * as_key key;
238  * as_key_init(&key, "myns", "myset", "mykey");
239  *
240  * as_ldt llist;
241  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
242  *
243  * as_integer min_value;
244  * as_integer_init(&min_value, 18);
245  *
246  * as_integer max_value;
247  * as_integer_init(&max_value, 99);
248  *
249  * as_list *result_list = NULL;
250  *
251  * if ( aerospike_llist_range(&as, &err, NULL, &key, &llist, &min_value, &max_value,
252  * "search_filter", NULL, &result_list) != AEROSPIKE_OK ) {
253  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
254  * }
255  * else {
256  * // process the returned elements
257  * as_arraylist_destroy(result_list);
258  * }
259  * ~~~~~~~~~~
260  *
261  * @param as The aerospike instance to use for this operation.
262  * @param err The as_error to be populated if an error occurs.
263  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
264  * @param key The key of the record.
265  * @param ldt The llist bin to search from. If not an llist bin, will return error.
266  * @param min_value The minimum range value (or null to be LEAST value)
267  * @param max_value The maximum range value (or null to be the GREATEST value)
268  * @param filter The name of the User-Defined-Function to use as a search filter (or null if no filter)
269  * @param fargs The list of parameters passed in to the User-Defined-Function filter (or null)
270  * @param list The pointer to a list of elements returned from search function. Pointer should
271  * be NULL passed in.
272  *
273  * @return AEROSPIKE_OK if successful. Otherwise an error.
274  *
275  * @ingroup ldt_operations
276  */
278  aerospike * as, as_error * err, const as_policy_apply * policy,
279  const as_key * key, const as_ldt * ldt,
280  const as_val * min_value, const as_val * max_value,
281  const as_udf_function_name filter, const as_list *filter_args,
282  as_list ** elements );
283 
284 /**
285  * Look up a llist and find how many elements it contains
286  *
287  * ~~~~~~~~~~{.c}
288  * as_key key;
289  * as_key_init(&key, "myns", "myset", "mykey");
290  *
291  * as_ldt llist;
292  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
293  * uint32_t llist_size = 0;
294  *
295  * if ( aerospike_llist_size(&as, &err, NULL, &key, &llist, &llist_size) != AEROSPIKE_OK ) {
296  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
297  * }
298  * ~~~~~~~~~~
299  *
300  * @param as The aerospike instance to use for this operation.
301  * @param err The as_error to be populated if an error occurs.
302  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
303  * @param key The key of the record.
304  * @param ldt The llist to operate on. If not an llist bin, will return error.
305  * @param n Return the number of elements in the llist.
306  *
307  * @return AEROSPIKE_OK if successful. Otherwise an error.
308  *
309  * @ingroup ldt_operations
310  */
312  aerospike * as, as_error * err, const as_policy_apply * policy,
313  const as_key * key, const as_ldt * ldt,
314  uint32_t *n
315  );
316 
317 /**
318  * Delete the given value from the llist
319  *
320  * ~~~~~~~~~~{.c}
321  * as_key key;
322  * as_key_init(&key, "myns", "myset", "mykey");
323  *
324  * as_ldt llist;
325  * as_ldt_init(&llist, "llist", AS_LDT_LLIST, NULL);
326  *
327  * as_integer ival;
328  * as_integer_init(&ival, 123);
329  *
330  * if ( aerospike_llist_remove(&as, &err, NULL, &key, &llist, &ival) != AEROSPIKE_OK ) {
331  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
332  * }
333  * ~~~~~~~~~~
334  *
335  * @param as The aerospike instance to use for this operation.
336  * @param err The as_error to be populated if an error occurs.
337  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
338  * @param key The key of the record.
339  * @param ldt The llist bin to delete from. If not an llist bin, will return error.
340  * @param val The value to delete from the set.
341  *
342  * @return AEROSPIKE_OK if successful. Otherwise an error.
343  *
344  * @ingroup ldt_operations
345  */
347  aerospike * as, as_error * err, const as_policy_apply * policy,
348  const as_key * key, const as_ldt * ldt, const as_val *element
349  );
350 
351 /**
352  * Destroy the llist bin
353  *
354  * ~~~~~~~~~~{.c}
355  * as_key key;
356  * as_key_init(&key, "myns", "myset", "mykey");
357  *
358  * as_ldt llist;
359  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
360  *
361  * if ( aerospike_llist_destroy(&as, &err, NULL, &key, &llist) != AEROSPIKE_OK ) {
362  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
363  * }
364  * ~~~~~~~~~~
365  *
366  * @param as The aerospike instance to use for this operation.
367  * @param err The as_error to be populated if an error occurs.
368  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
369  * @param key The key of the record.
370  * @param ldt The llist bin to destroy. If not an llist bin, will return error.
371  *
372  * @return AEROSPIKE_OK if successful. Otherwise an error.
373  *
374  * @ingroup ldt_operations
375  */
377  aerospike * as, as_error * err, const as_policy_apply * policy,
378  const as_key * key, const as_ldt * ldt
379  );
380 
381 /**
382  * SET the storage capacity for this LDT.
383  *
384  * ~~~~~~~~~~{.c}
385  * as_key key;
386  * as_key_init(&key, "myns", "myset", "mykey");
387  *
388  * as_ldt llist;
389  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
390  * uint32_t ldt_capacity = 5000;
391  *
392  * if ( aerospike_llist_set_capacity(&as, &err, NULL, &key, &llist, ldt_capacity) != AEROSPIKE_OK ) {
393  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
394  * }
395  * ~~~~~~~~~~
396  *
397  * @param as The aerospike instance to use for this operation.
398  * @param err The as_error to be populated if an error occurs.
399  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
400  * @param key The key of the record.
401  * @param ldt The LDT to operate on. If not an LLIST bin, will return error.
402  * @param ldt_capacity Set by function to 1 for true, 0 for false
403  *
404  * @return AEROSPIKE_OK if successful. Otherwise an error.
405  *
406  * @ingroup ldt_operations
407  */
409  aerospike * as, as_error * err, const as_policy_apply * policy,
410  const as_key * key, const as_ldt * ldt,
411  uint32_t ldt_capacity
412  );
413 
414 /**
415  * Check the storage capacity for this LDT.
416  *
417  * ~~~~~~~~~~{.c}
418  * as_key key;
419  * as_key_init(&key, "myns", "myset", "mykey");
420  *
421  * as_ldt llist;
422  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
423  * uint32_t ldt_capacity = 0;
424  *
425  * if ( aerospike_llist_get_capacity(&as, &err, NULL, &key, &llist, &ldt_capacity) != AEROSPIKE_OK ) {
426  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
427  * }
428  * ~~~~~~~~~~
429  *
430  * @param as The aerospike instance to use for this operation.
431  * @param err The as_error to be populated if an error occurs.
432  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
433  * @param key The key of the record.
434  * @param ldt The LDT to operate on. If not an LLIST bin, will return error.
435  * @param ldt_capacity Set by function to 1 for true, 0 for false
436  *
437  * @return AEROSPIKE_OK if successful. Otherwise an error.
438  *
439  * @ingroup ldt_operations
440  */
442  aerospike * as, as_error * err, const as_policy_apply * policy,
443  const as_key * key, const as_ldt * ldt,
444  uint32_t *ldt_capacity
445  );
446 
447 /**
448  * Check to see if an LLIST object exists in this record bin.
449  *
450  * ~~~~~~~~~~{.c}
451  * as_key key;
452  * as_key_init(&key, "myns", "myset", "mykey");
453  *
454  * as_ldt llist;
455  * as_ldt_init(&llist, "myllist", AS_LDT_LLIST, NULL);
456  * uint32_t ldt_exists = 0;
457  *
458  * if ( aerospike_llist_size(&as, &err, NULL, &key, &llist, &ldt_exists) != AEROSPIKE_OK ) {
459  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
460  * }
461  * ~~~~~~~~~~
462  *
463  * @param as The aerospike instance to use for this operation.
464  * @param err The as_error to be populated if an error occurs.
465  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
466  * @param key The key of the record.
467  * @param ldt The LDT to operate on. If not an LLIST bin, will return error.
468  * @param ldt_exists Ptr to as_boolean: Set to TRUE if ldt exists, otherwise false.
469  *
470  * @return AEROSPIKE_OK if successful. Otherwise an error.
471  *
472  * @ingroup ldt_operations
473  */
475  aerospike * as, as_error * err, const as_policy_apply * policy,
476  const as_key * key, const as_ldt * ldt,
477  as_boolean *ldt_exists
478  );
479