All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_list_operations.h
Go to the documentation of this file.
1 /*
2  * Copyright 2008-2016 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 
20 
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24 
25 /******************************************************************************
26  * FUNCTIONS
27  *****************************************************************************/
28 
29 /**
30  * Add an as_val element to end of list.
31  *
32  * @param ops The `as_operations` to append the operation to.
33  * @param name The name of the bin to perform the operation on.
34  * @param val Value to append. Consumes a reference of this as_val.
35  *
36  * @return true on success. Otherwise an error occurred.
37  *
38  * @relates as_operations
39  * @ingroup as_operations_object
40  */
41 bool
43 
44 /**
45  * Add an integer to end of list. Convenience function of as_operations_add_list_append()
46  *
47  * @param ops The `as_operations` to append the operation to.
48  * @param name The name of the bin to perform the operation on.
49  * @param value An integer value.
50  *
51  * @return true on success. Otherwise an error occurred.
52  *
53  * @relates as_operations
54  * @ingroup as_operations_object
55  */
56 bool
57 as_operations_add_list_append_int64(as_operations* ops, const as_bin_name name, int64_t value);
58 
59 /**
60  * Add a double to end of list. Convenience function of as_operations_add_list_append()
61  *
62  * @param ops The `as_operations` to append the operation to.
63  * @param name The name of the bin to perform the operation on.
64  * @param value A double value.
65  *
66  * @return true on success. Otherwise an error occurred.
67  *
68  * @relates as_operations
69  * @ingroup as_operations_object
70  */
71 bool
72 as_operations_add_list_append_double(as_operations* ops, const as_bin_name name, double value);
73 
74 /**
75  * Add a string to end of list. Convenience function of as_operations_add_list_append()
76  *
77  * @param ops The `as_operations` to append the operation to.
78  * @param name The name of the bin to perform the operation on.
79  * @param value A c-string.
80  * @param free If true, then the value will be freed when the operations is destroyed.
81  *
82  * @return true on success. Otherwise an error occurred.
83  *
84  * @relates as_operations
85  * @ingroup as_operations_object
86  */
87 bool
88 as_operations_add_list_append_strp(as_operations* ops, const as_bin_name name, const char* value, bool free);
89 
90 /**
91  * Add a string to end of list. Convenience function of as_operations_add_list_append()
92  *
93  * @param ops The `as_operations` to append the operation to.
94  * @param name The name of the bin to perform the operation on.
95  * @param value A c-string.
96  *
97  * @return true on success. Otherwise an error occurred.
98  *
99  * @relates as_operations
100  * @ingroup as_operations_object
101  */
102 static inline bool
103 as_operations_add_list_append_str(as_operations* ops, const as_bin_name name, const char* value)
104 {
105  return as_operations_add_list_append_strp(ops, name, value, false);
106 }
107 
108 /**
109  * Add a blob to end of list. Convenience function of as_operations_add_list_append()
110  *
111  * @param ops The `as_operations` to append the operation to.
112  * @param name The name of the bin to perform the operation on.
113  * @param value A blob.
114  * @param size Size of the blob.
115  * @param free If true, then the value will be freed when the operations is destroyed.
116  *
117  * @return true on success. Otherwise an error occurred.
118  *
119  * @relates as_operations
120  * @ingroup as_operations_object
121  */
122 bool
123 as_operations_add_list_append_rawp(as_operations* ops, const as_bin_name name, const uint8_t* value, uint32_t size, bool free);
124 
125 /**
126  * Add a blob to end of list. Convenience function of as_operations_add_list_append()
127  *
128  * @param ops The `as_operations` to append the operation to.
129  * @param name The name of the bin to perform the operation on.
130  * @param value A blob.
131  * @param size Size of the blob.
132  *
133  * @return true on success. Otherwise an error occurred.
134  *
135  * @relates as_operations
136  * @ingroup as_operations_object
137  */
138 static inline bool
139 as_operations_add_list_append_raw(as_operations* ops, const as_bin_name name, const uint8_t* value, uint32_t size)
140 {
141  return as_operations_add_list_append_rawp(ops, name, value, size, false);
142 }
143 
144 /**
145  * Add multiple values to end of list.
146  *
147  * @param ops The `as_operations` to append the operation to.
148  * @param name The name of the bin to perform the operation on.
149  * @param list List of values to append. Consumes a reference of this as_list.
150  *
151  * @return true on success. Otherwise an error occurred.
152  *
153  * @relates as_operations
154  * @ingroup as_operations_object
155  */
156 bool
158 
159 /**
160  * Insert an as_val element to list at index position.
161  *
162  * @param ops The `as_operations` to append the operation to.
163  * @param name The name of the bin to perform the operation on.
164  * @param index Index position which the as_val will be inserted at. Negative index counts from end of list.
165  * @param val Value to insert. Consumes a reference of this as_list.
166  *
167  * @return true on success. Otherwise an error occurred.
168  *
169  * @relates as_operations
170  * @ingroup as_operations_object
171  */
172 bool
173 as_operations_add_list_insert(as_operations* ops, const as_bin_name name, int64_t index, as_val* val);
174 
175 /**
176  * Insert integer to list at index position. Convenience function of as_operations_add_list_insert()
177  *
178  * @param ops The `as_operations` to append the operation to.
179  * @param name The name of the bin to perform the operation on.
180  * @param index Index position which the integer will be inserted at. Negative index counts from end of list.
181  * @param value An integer value.
182  *
183  * @return true on success. Otherwise an error occurred.
184  *
185  * @relates as_operations
186  * @ingroup as_operations_object
187  */
188 bool
189 as_operations_add_list_insert_int64(as_operations* ops, const as_bin_name name, int64_t index, int64_t value);
190 
191 /**
192  * Insert double to list at index position. Convenience function of as_operations_add_list_insert()
193  *
194  * @param ops The `as_operations` to append the operation to.
195  * @param name The name of the bin to perform the operation on.
196  * @param index Index position which the double will be inserted at. Negative index counts from end of list.
197  * @param value A double value.
198  *
199  * @return true on success. Otherwise an error occurred.
200  *
201  * @relates as_operations
202  * @ingroup as_operations_object
203  */
204 bool
205 as_operations_add_list_insert_double(as_operations* ops, const as_bin_name name, int64_t index, double value);
206 
207 /**
208  * Insert string to list at index position. Convenience function of as_operations_add_list_insert()
209  *
210  * @param ops The `as_operations` to append the operation to.
211  * @param name The name of the bin to perform the operation on.
212  * @param index Index position which the string will be inserted at. Negative index counts from end of list.
213  * @param value A c-string.
214  * @param free If true, then the value will be freed when the operations is destroyed.
215  *
216  * @return true on success. Otherwise an error occurred.
217  *
218  * @relates as_operations
219  * @ingroup as_operations_object
220  */
221 bool
222 as_operations_add_list_insert_strp(as_operations* ops, const as_bin_name name, int64_t index, const char* value, bool free);
223 
224 /**
225  * Insert string to list at index position. Convenience function of as_operations_add_list_insert()
226  *
227  * @param ops The `as_operations` to append the operation to.
228  * @param name The name of the bin to perform the operation on.
229  * @param index Index position which the string will be inserted at. Negative index counts from end of list.
230  * @param value A c-string.
231  *
232  * @return true on success. Otherwise an error occurred.
233  *
234  * @relates as_operations
235  * @ingroup as_operations_object
236  */
237 static inline bool
238 as_operations_add_list_insert_str(as_operations* ops, const as_bin_name name, int64_t index, const char* value)
239 {
240  return as_operations_add_list_insert_strp(ops, name, index, value, false);
241 }
242 
243 /**
244  * Insert blob to list at index position. Convenience function of as_operations_add_list_insert()
245  *
246  * @param ops The `as_operations` to append the operation to.
247  * @param name The name of the bin to perform the operation on.
248  * @param index Index position which the blob will be inserted at. Negative index counts from end of list.
249  * @param value A blob.
250  * @param size Size of the blob.
251  * @param free If true, then the value will be freed when the operations is destroyed.
252  *
253  * @return true on success. Otherwise an error occurred.
254  *
255  * @relates as_operations
256  * @ingroup as_operations_object
257  */
258 bool
259 as_operations_add_list_insert_rawp(as_operations* ops, const as_bin_name name, int64_t index, const uint8_t* value, uint32_t size, bool free);
260 
261 /**
262  * Insert blob to list at index position. Convenience function of as_operations_add_list_insert()
263  *
264  * @param ops The `as_operations` to append the operation to.
265  * @param name The name of the bin to perform the operation on.
266  * @param index Index position which the blob will be inserted at. Negative index counts from end of list.
267  * @param value A blob.
268  * @param size Size of the blob.
269  *
270  * @return true on success. Otherwise an error occurred.
271  *
272  * @relates as_operations
273  * @ingroup as_operations_object
274  */
275 static inline bool
276 as_operations_add_list_insert_raw(as_operations* ops, const as_bin_name name, int64_t index, const uint8_t* value, uint32_t size)
277 {
278  return as_operations_add_list_insert_rawp(ops, name, index, value, size, false);
279 }
280 
281 /**
282  * Insert multiple values to list at index position.
283  *
284  * @param ops The `as_operations` to append the operation to.
285  * @param name The name of the bin to perform the operation on.
286  * @param index Index position which the blob will be inserted at. Negative index counts from end of list.
287  * @param list List of values to insert. Consumes reference of list.
288  *
289  * @return true on success. Otherwise an error occurred.
290  *
291  * @relates as_operations
292  * @ingroup as_operations_object
293  */
294 bool
295 as_operations_add_list_insert_items(as_operations* ops, const as_bin_name name, int64_t index, as_list *list);
296 
297 /**
298  * Remove and return a value at index.
299  *
300  * @param ops The `as_operations` to append the operation to.
301  * @param name The name of the bin to perform the operation on.
302  * @param index Index position at which the value will be removed and returned. Negative index counts from end of list.
303  *
304  * @return true on success. Otherwise an error occurred.
305  *
306  * @relates as_operations
307  * @ingroup as_operations_object
308  */
309 bool
310 as_operations_add_list_pop(as_operations* ops, const as_bin_name name, int64_t index);
311 
312 /**
313  * Remove and return N values from index.
314  *
315  * @param ops The `as_operations` to append the operation to.
316  * @param name The name of the bin to perform the operation on.
317  * @param index Index position at which to start the removal. Negative index counts from end of list.
318  * @param count Number of values to remove. If not enough values in list, will remove to list end.
319  *
320  * @return true on success. Otherwise an error occurred.
321  *
322  * @relates as_operations
323  * @ingroup as_operations_object
324  */
325 bool
326 as_operations_add_list_pop_range(as_operations* ops, const as_bin_name name, int64_t index, uint64_t count);
327 
328 /**
329  * Remove and return all values from index to the end of list.
330  *
331  * @param ops The `as_operations` to append the operation to.
332  * @param name The name of the bin to perform the operation on.
333  * @param index Index position at which to start the removal. Negative index counts from end of list.
334  *
335  * @return true on success. Otherwise an error occurred.
336  *
337  * @relates as_operations
338  * @ingroup as_operations_object
339  */
340 bool
341 as_operations_add_list_pop_range_from(as_operations* ops, const as_bin_name name, int64_t index);
342 
343 /**
344  * Remove value at index.
345  *
346  * @param ops The `as_operations` to append the operation to.
347  * @param name The name of the bin to perform the operation on.
348  * @param index Index position at which to start the removal. Negative index counts from end of list.
349  *
350  * @return true on success. Otherwise an error occurred.
351  *
352  * @relates as_operations
353  * @ingroup as_operations_object
354  */
355 bool
356 as_operations_add_list_remove(as_operations* ops, const as_bin_name name, int64_t index);
357 
358 /**
359  * Remove N values from index.
360  *
361  * @param ops The `as_operations` to append the operation to.
362  * @param name The name of the bin to perform the operation on.
363  * @param index Index position at which to start the removal. Negative index counts from end of list.
364  * @param count Number of values to remove. If not enough values in list, will remove to list end.
365  *
366  * @return true on success. Otherwise an error occurred.
367  *
368  * @relates as_operations
369  * @ingroup as_operations_object
370  */
371 bool
372 as_operations_add_list_remove_range(as_operations* ops, const as_bin_name name, int64_t index, uint64_t count);
373 
374 /**
375  * Remove all values from index until end of list.
376  *
377  * @param ops The `as_operations` to append the operation to.
378  * @param name The name of the bin to perform the operation on.
379  * @param index Index position at which to start the removal. Negative index counts from end of list.
380  *
381  * @return true on success. Otherwise an error occurred.
382  *
383  * @relates as_operations
384  * @ingroup as_operations_object
385  */
386 bool
388 
389 //-----------------------------------------------------------------------------
390 // Other list modifies
391 
392 /**
393  * Remove all values. Will leave empty list in bin.
394  *
395  * @param ops The `as_operations` to append the operation to.
396  * @param name The name of the bin to perform the operation on.
397  *
398  * @return true on success. Otherwise an error occurred.
399  *
400  * @relates as_operations
401  * @ingroup as_operations_object
402  */
403 bool
405 
406 /**
407  * Set an as_val element of the list at the index position.
408  *
409  * @param ops The `as_operations` to append the operation to.
410  * @param name The name of the bin to perform the operation on.
411  * @param index Index position to set. Negative index counts from end of list.
412  * @param val Consumes a reference of this as_val.
413  *
414  * @return true on success. Otherwise an error occurred.
415  *
416  * @relates as_operations
417  * @ingroup as_operations_object
418  */
419 bool
420 as_operations_add_list_set(as_operations* ops, const as_bin_name name, int64_t index, as_val* val);
421 
422 /**
423  * Set value at index as integer. Convenience function of as_operations_add_list_set()
424  *
425  * @param ops The `as_operations` to append the operation to.
426  * @param name The name of the bin to perform the operation on.
427  * @param index Index position to set. Negative index counts from end of list.
428  * @param value An integer value.
429  *
430  * @return true on success. Otherwise an error occurred.
431  *
432  * @relates as_operations
433  * @ingroup as_operations_object
434  */
435 bool
436 as_operations_add_list_set_int64(as_operations* ops, const as_bin_name name, int64_t index, int64_t value);
437 
438 /**
439  * Set value at index as double. Convenience function of as_operations_add_list_set()
440  *
441  * @param ops The `as_operations` to append the operation to.
442  * @param name The name of the bin to perform the operation on.
443  * @param index Index position to set. Negative index counts from end of list.
444  * @param value A double value.
445  *
446  * @return true on success. Otherwise an error occurred.
447  *
448  * @relates as_operations
449  * @ingroup as_operations_object
450  */
451 bool
452 as_operations_add_list_set_double(as_operations* ops, const as_bin_name name, int64_t index, double value);
453 
454 /**
455  * Set value at index as string. Convenience function of as_operations_add_list_set()
456  *
457  * @param ops The `as_operations` to append the operation to.
458  * @param name The name of the bin to perform the operation on.
459  * @param index Index position to set. Negative index counts from end of list.
460  * @param value A c-string.
461  * @param free If true, then the value will be freed when the operations is destroyed.
462  *
463  * @return true on success. Otherwise an error occurred.
464  *
465  * @relates as_operations
466  * @ingroup as_operations_object
467  */
468 bool
469 as_operations_add_list_set_strp(as_operations* ops, const as_bin_name name, int64_t index, const char* value, bool free);
470 
471 /**
472  * Set value at index as string. Convenience function of as_operations_add_list_set()
473  *
474  * @param ops The `as_operations` to append the operation to.
475  * @param name The name of the bin to perform the operation on.
476  * @param index Index position to set. Negative index counts from end of list.
477  * @param value A c-string.
478  *
479  * @return true on success. Otherwise an error occurred.
480  *
481  * @relates as_operations
482  * @ingroup as_operations_object
483  */
484 static inline bool
485 as_operations_add_list_set_str(as_operations* ops, const as_bin_name name, int64_t index, const char* value)
486 {
487  return as_operations_add_list_set_strp(ops, name, index, value, false);
488 }
489 
490 /**
491  * Set value at index as blob. Convenience function of as_operations_add_list_set()
492  *
493  * @param ops The `as_operations` to append the operation to.
494  * @param name The name of the bin to perform the operation on.
495  * @param index Index position to set. Negative index counts from end of list.
496  * @param value A blob.
497  * @param size Size of the blob.
498  * @param free If true, then the value will be freed when the operations is destroyed.
499  *
500  * @return true on success. Otherwise an error occurred.
501  *
502  * @relates as_operations
503  * @ingroup as_operations_object
504  */
505 bool
506 as_operations_add_list_set_rawp(as_operations* ops, const as_bin_name name, int64_t index, const uint8_t* value, uint32_t size, bool free);
507 
508 /**
509  * Set value at index as blob. Convenience function of as_operations_add_list_set()
510  *
511  * @param ops The `as_operations` to append the operation to.
512  * @param name The name of the bin to perform the operation on.
513  * @param index Index position to set. Negative index counts from end of list.
514  * @param value A blob.
515  * @param size Size of the blob.
516  *
517  * @return true on success. Otherwise an error occurred.
518  *
519  * @relates as_operations
520  * @ingroup as_operations_object
521  */
522 static inline bool
523 as_operations_add_list_set_raw(as_operations* ops, const as_bin_name name, int64_t index, const uint8_t* value, uint32_t size)
524 {
525  return as_operations_add_list_set_rawp(ops, name, index, value, size, false);
526 }
527 
528 /**
529  * Remove values NOT within range(index, count).
530  *
531  * @param ops The `as_operations` to append the operation to.
532  * @param name The name of the bin to perform the operation on.
533  * @param index Values from 0-index position are removed. Negative index counts from end of list.
534  * @param count Number of values to keep. All other values beyond count are removed.
535  *
536  * @return true on success. Otherwise an error occurred.
537  *
538  * @relates as_operations
539  * @ingroup as_operations_object
540  */
541 bool
542 as_operations_add_list_trim(as_operations* ops, const as_bin_name name, int64_t index, uint64_t count);
543 
544 /**
545  * Create list increment operation.
546  * Server increments value at index by incr and returns final result.
547  * Valid only for numbers.
548  *
549  * @relates as_operations
550  * @ingroup as_operations_object
551  */
552 bool
553 as_operations_add_list_increment(as_operations *ops, const as_bin_name name, int64_t index, as_val *incr);
554 
555 //-----------------------------------------------------------------------------
556 // Read operations
557 
558 /**
559  * Get value of list at index.
560  *
561  * @param ops The `as_operations` to append the operation to.
562  * @param name The name of the bin to perform the operation on.
563  * @param index Index position to get. Negative index counts from end of list.
564  *
565  * @return true on success. Otherwise an error occurred.
566  *
567  * @relates as_operations
568  * @ingroup as_operations_object
569  */
570 bool
571 as_operations_add_list_get(as_operations* ops, const as_bin_name name, int64_t index);
572 
573 /**
574  * Get multiple values of list starting at index.
575  *
576  * @param ops The `as_operations` to append the operation to.
577  * @param name The name of the bin to perform the operation on.
578  * @param index Index position at which to start. Negative index counts from end of list.
579  * @param count Number of values to get. If not enough in list, will return all remaining.
580  *
581  * @return true on success. Otherwise an error occurred.
582  *
583  * @relates as_operations
584  * @ingroup as_operations_object
585  */
586 bool
587 as_operations_add_list_get_range(as_operations* ops, const as_bin_name name, int64_t index, uint64_t count);
588 
589 /**
590  * Get multiple values of list starting at index until end of list.
591  *
592  * @param ops The `as_operations` to append the operation to.
593  * @param name The name of the bin to perform the operation on.
594  * @param index Index position at which to start. Negative index counts from end of list.
595  *
596  * @return true on success. Otherwise an error occurred.
597  *
598  * @relates as_operations
599  * @ingroup as_operations_object
600  */
601 bool
602 as_operations_add_list_get_range_from(as_operations* ops, const as_bin_name name, int64_t index);
603 
604 /**
605  * Get number of values in list.
606  *
607  * @param ops The `as_operations` to append the operation to.
608  * @param name The name of the bin to perform the operation on.
609  *
610  * @return true on success. Otherwise an error occurred.
611  *
612  * @relates as_operations
613  * @ingroup as_operations_object
614  */
615 bool
617 
618 #ifdef __cplusplus
619 } // end extern "C"
620 #endif