All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
src/include/aerospike/aerospike_lset.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 Set 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_list.h>
33 #include <aerospike/as_operations.h>
34 #include <aerospike/as_policy.h>
35 #include <aerospike/as_status.h>
36 #include <aerospike/as_key.h>
37 #include <aerospike/as_val.h>
38 #include <aerospike/as_boolean.h>
39 
40 /******************************************************************************
41  * FUNCTIONS
42  *****************************************************************************/
43 
44 /**
45  * Add a value into the lset.
46  *
47  * ~~~~~~~~~~{.c}
48  * as_key key;
49  * as_key_init(&key, "myns", "myset", "mykey");
50  *
51  * as_ldt lset;
52  * as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
53  *
54  * as_integer ival;
55  * as_integer_init(&ival, 123);
56  *
57  * if ( aerospike_lset_add(&as, &err, NULL, &key, &lset, (as_val *) &ival) != AEROSPIKE_OK ) {
58  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
59  * }
60  * ~~~~~~~~~~
61  *
62  * @param as The aerospike instance to use for this operation.
63  * @param err The as_error to be populated if an error occurs.
64  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
65  * @param key The key of the record.
66  * @param ldt The ldt bin to insert values to.
67  * @param val The value to insert into the lset.
68  *
69  * @return AEROSPIKE_OK if successful. Otherwise an error.
70  *
71  * @ingroup ldt_operations
72  */
74  aerospike * as, as_error * err, const as_policy_apply * policy,
75  const as_key * key, const as_ldt * ldt, const as_val * val);
76 
77 /**
78  * Add a list of values into the lset.
79  *
80  * ~~~~~~~~~~{.c}
81  * as_key key;
82  * as_key_init(&key, "myns", "myset", "mykey");
83  *
84  * as_ldt lset;
85  * as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
86  *
87  *
88  * as_arraylist vals;
89  * as_arraylist_inita(&vals, 2);
90  * as_string s;
91  * as_string_init(s,"a string",false);
92  * as_arraylist_append_string(&vals, s);
93  * as_arraylist_append_int64(&vals, 35);
94  *
95  * if ( aerospike_lset_add_all(&as, &err, NULL, &key, &lset, (as_list *)vals) != AEROSPIKE_OK ) {
96  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
97  * }
98  *
99  * ~~~~~~~~~~
100  *
101  * @param as The aerospike instance to use for this operation.
102  * @param err The as_error to be populated if an error occurs.
103  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
104  * @param key The key of the record.
105  * @param ldt The ldt bin to insert values to.
106  * @param vals The list of values to insert into the lset.
107  *
108  * @return AEROSPIKE_OK if successful. Otherwise an error.
109  *
110  * @ingroup ldt_operations
111  */
113  aerospike * as, as_error * err, const as_policy_apply * policy,
114  const as_key * key, const as_ldt * ldt, const as_list * vals);
115 
116 /**
117  * See if a value exists in an lset
118  *
119  * ~~~~~~~~~~{.c}
120  * as_key key;
121  * as_key_init(&key, "myns", "myset", "mykey");
122  *
123  * as_ldt lset;
124  * as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
125  *
126  * as_integer ival;
127  * as_integer_init(&ival, 123);
128  *
129  * boolean exists = false;
130  *
131  * if ( aerospike_lset_exists(&as, &err, NULL, &key, &lset, &ival, &exists) != AEROSPIKE_OK ) {
132  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
133  * }
134  * else {
135  * // do logic because element exists
136  * }
137  * ~~~~~~~~~~
138  *
139  * @param as The aerospike instance to use for this operation.
140  * @param err The as_error to be populated if an error occurs.
141  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
142  * @param key The key of the record.
143  * @param ldt The lset bin to lookup from. If not an lset bin, will return error.
144  * @param val The value we're searching for.
145  * @param exists Returned boolean value to indicate value exists.
146  *
147  * @return AEROSPIKE_OK if successful. Otherwise an error.
148  *
149  * @ingroup ldt_operations
150  */
151 
153  aerospike * as, as_error * err, const as_policy_apply * policy,
154  const as_key * key, const as_ldt * ldt, const as_val * val,
155  as_boolean *exists);
156 
157 
158 /**
159  * Fetch (get) a value from the lset.
160  * Note that this is useful mainly in the case where the search criteria for
161  * an object is less than the entire object -- and that is when the standard
162  * defaults are overridden and the unique_identifier() function is employed
163  * to use only part of the object for search and compare.
164  * The unique_identifier() function is defined on create -- and declared in
165  * the USER_MODULE.
166  *
167  * ~~~~~~~~~~{.c}
168  * as_key key;
169  * as_key_init(&key, "myns", "myset", "mykey");
170  *
171  * as_ldt lset;
172  * as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
173  *
174  * as_integer ival;
175  * as_integer_init(&ival, 123);
176  *
177  * as_val * p_return_val;
178  *
179  * if ( aerospike_lset_exists(&as, &err, NULL, &key, &lset, &ival, &p_return_value) != AEROSPIKE_OK ) {
180  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
181  * }
182  * else {
183  * // do logic because element exists
184  * }
185  * ~~~~~~~~~~
186  *
187  * @param as The aerospike instance to use for this operation.
188  * @param err The as_error to be populated if an error occurs.
189  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
190  * @param key The key of the record.
191  * @param ldt The lset bin to lookup from. If not an lset bin, will return error.
192  * @param val The value we're searching for.
193  * @param pp_return_val Returned value.
194  *
195  * @return AEROSPIKE_OK if successful. Otherwise an error.
196  *
197  * @ingroup ldt_operations
198  */
199 
201  aerospike * as, as_error * err, const as_policy_apply * policy,
202  const as_key * key, const as_ldt * ldt, const as_val * val,
203  as_val ** pp_return_val );
204 
205 /**
206  * Given an lset bin, filter the set of objects using the given filter function.
207  * If no filter function is specified, all values in the set will be returned.
208  *
209  * ~~~~~~~~~~{.c}
210  * as_key key;
211  * as_key_init(&key, "myns", "myset", "mykey");
212  *
213  * as_ldt lset;
214  * as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
215  *
216  * as_list *list = NULL;
217  *
218  * if ( aerospike_lset_filter(&as, &err, NULL, &key, &lset,
219  * "search_filter", NULL, (as_list *) &list) != AEROSPIKE_OK ) {
220  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
221  * }
222  * else {
223  * // process the returned elements
224  * as_arraylist_destroy(list);
225  * }
226  * ~~~~~~~~~~
227  *
228  * @param as The aerospike instance to use for this operation.
229  * @param err The as_error to be populated if an error occurs.
230  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
231  * @param key The key of the record.
232  * @param ldt The lset bin to search from. If not an lset bin, will return error.
233  * @param filter The name of the User-Defined-Function to use as a search filter.
234  * @param fargs The list of parameters passed in to the User-Defined-Function filter.
235  * @param list The pointer to a list of elements returned from search function. Pointer should
236  * be NULL passed in.
237  *
238  * @return AEROSPIKE_OK if successful. Otherwise an error.
239  *
240  * @ingroup ldt_operations
241  */
243  aerospike * as, as_error * err, const as_policy_apply * policy,
244  const as_key * key, const as_ldt * ldt,
245  const as_udf_function_name filter, const as_list *filter_args,
246  as_list ** elements );
247 
248 /**
249  * Given an lset bin, scan for all the values in the set
250  *
251  * ~~~~~~~~~~{.c}
252  * as_key key;
253  * as_key_init(&key, "myns", "myset", "mykey");
254  *
255  * as_ldt lset;
256  * as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
257  *
258  * as_list *list = NULL;
259  *
260  * if ( aerospike_lset_scan(&as, &err, NULL, &key, &lset,
261  * "search_filter", NULL, (as_list *) &list) != AEROSPIKE_OK ) {
262  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
263  * }
264  * else {
265  * // process the returned elements
266  * as_arraylist_destroy(list);
267  * }
268  * ~~~~~~~~~~
269  *
270  * @param as The aerospike instance to use for this operation.
271  * @param err The as_error to be populated if an error occurs.
272  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
273  * @param key The key of the record.
274  * @param ldt The lset bin to search from. If not an lset bin, will return error.
275  * @param list The pointer to a list of elements returned from search function. Pointer should
276  * be NULL passed in.
277  *
278  * @return AEROSPIKE_OK if successful. Otherwise an error.
279  *
280  * @ingroup ldt_operations
281  */
283  aerospike * as, as_error * err, const as_policy_apply * policy,
284  const as_key * key, const as_ldt * ldt,
285  as_list ** elements );
286 
287 /**
288  * Look up a lset and find how many elements it contains
289  *
290  * ~~~~~~~~~~{.c}
291  * as_key key;
292  * as_key_init(&key, "myns", "myset", "mykey");
293  *
294  * as_ldt lset;
295  * as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
296  * uint32_t lset_size = 0;
297  *
298  * if ( aerospike_lset_size(&as, &err, NULL, &key, &lset, &lset_size) != AEROSPIKE_OK ) {
299  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
300  * }
301  * ~~~~~~~~~~
302  *
303  * @param as The aerospike instance to use for this operation.
304  * @param err The as_error to be populated if an error occurs.
305  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
306  * @param key The key of the record.
307  * @param ldt The lset to operate on. If not an lset bin, will return error.
308  * @param n Return the number of elements in the lset.
309  *
310  * @return AEROSPIKE_OK if successful. Otherwise an error.
311  *
312  * @ingroup ldt_operations
313  */
315  aerospike * as, as_error * err, const as_policy_apply * policy,
316  const as_key * key, const as_ldt * ldt,
317  uint32_t *n
318  );
319 
320 /**
321  * Delete the given value from the lset
322  *
323  * ~~~~~~~~~~{.c}
324  * as_key key;
325  * as_key_init(&key, "myns", "myset", "mykey");
326  *
327  * as_ldt lset;
328  * as_ldt_init(&lset, "lset", AS_LDT_LSET, NULL);
329  *
330  * as_integer ival;
331  * as_integer_init(&ival, 123);
332  *
333  * if ( aerospike_lset_remove(&as, &err, NULL, &key, &lset, &ival) != AEROSPIKE_OK ) {
334  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
335  * }
336  * ~~~~~~~~~~
337  *
338  * @param as The aerospike instance to use for this operation.
339  * @param err The as_error to be populated if an error occurs.
340  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
341  * @param key The key of the record.
342  * @param ldt The lset bin to delete from. If not an lset bin, will return error.
343  * @param val The value to delete from the set.
344  *
345  * @return AEROSPIKE_OK if successful. Otherwise an error.
346  *
347  * @ingroup ldt_operations
348  */
350  aerospike * as, as_error * err, const as_policy_apply * policy,
351  const as_key * key, const as_ldt * ldt, const as_val *element
352  );
353 
354 /**
355  * Destroy the lset bin
356  *
357  * ~~~~~~~~~~{.c}
358  * as_key key;
359  * as_key_init(&key, "myns", "myset", "mykey");
360  *
361  * as_ldt lset;
362  * as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
363  *
364  * if ( aerospike_lset_destroy(&as, &err, NULL, &key, &lset) != AEROSPIKE_OK ) {
365  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
366  * }
367  * ~~~~~~~~~~
368  *
369  * @param as The aerospike instance to use for this operation.
370  * @param err The as_error to be populated if an error occurs.
371  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
372  * @param key The key of the record.
373  * @param ldt The lset bin to destroy. If not an lset bin, will return error.
374  *
375  * @return AEROSPIKE_OK if successful. Otherwise an error.
376  *
377  * @ingroup ldt_operations
378  */
380  aerospike * as, as_error * err, const as_policy_apply * policy,
381  const as_key * key, const as_ldt * ldt
382  );
383 
as_status aerospike_lset_add_all(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_list *vals)
as_status aerospike_lset_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_lset_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_lset_destroy(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt)
as_status aerospike_lset_get(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_val *val, as_val **pp_return_val)
as_status aerospike_lset_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_lset_exists(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_val *val, as_boolean *exists)
as_status aerospike_lset_size(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, uint32_t *n)
char as_udf_function_name[AS_UDF_FUNCTION_MAX_SIZE]
as_status aerospike_lset_add(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_val *val)