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