All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_arraylist.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 
18 #pragma once
19 
20 #include <aerospike/as_bytes.h>
21 #include <aerospike/as_double.h>
22 #include <aerospike/as_integer.h>
23 #include <aerospike/as_list.h>
24 #include <aerospike/as_map.h>
25 #include <aerospike/as_string.h>
26 #include <aerospike/as_val.h>
27 
28 #include <stdbool.h>
29 #include <stdint.h>
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
35 /******************************************************************************
36  * TYPES
37  *****************************************************************************/
38 
39 /**
40  * An dynamic array implementation for as_list.
41  *
42  * as_arryalist can either be initialize on the stack or the heap.
43  *
44  * For stack allocation, you have two choices:
45  * - `as_arraylist_init()` - uses `cf_malloc()` to initialize the internal storage
46  * on the heap.
47  * - `as_arraylist_inita()` - uses `alloca()` to initialize the internal storage
48  * on the stack.
49  *
50  * The key differences between the two is `as_arraylist_inita()` can't be
51  * dynamically resized and is solely on the stack.
52  *
53  * The following is using a `as_arraylist_inita()`:
54  * ~~~~~~~~~~{.c}
55  * as_arraylist list;
56  * as_arraylist_inita(&list, 2);
57  * ~~~~~~~~~~
58  *
59  * You will notice that the code is quite similar to `as_arraylist_init()`:
60  * ~~~~~~~~~~{.c}
61  * as_arraylist list;
62  * as_arraylist_init(&list, 2, 0);
63  * ~~~~~~~~~~
64  *
65  * If you need a new heap allocated list, then use `as_arraylist_new()`:
66  *
67  * ~~~~~~~~~~{.c}
68  * as_arraylist * list = as_arraylist_new(2, 0);
69  * ~~~~~~~~~~
70  *
71  * When you are finished using the list, then you should release the list and
72  * associated resources, using `as_arraylist_destroy()`:
73  *
74  * ~~~~~~~~~~{.c}
75  * as_arraylist_destroy(list);
76  * ~~~~~~~~~~
77  *
78  *
79  * The `as_arraylist` is a subtype of `as_list`. This allows you to
80  * alternatively use `as_list` functions, by typecasting `as_arraylist` to
81  * `as_list`.
82  *
83  * ~~~~~~~~~~{.c}
84  * as_arraylist list;
85  * as_list * l = (as_list *) as_arraylist_init(&list, 3, 0);
86  * as_list_append_int64(l, 1);
87  * as_list_append_int64(l, 2);
88  * as_list_append_int64(l, 3);
89  * as_list_destroy(l);
90  * ~~~~~~~~~~
91  *
92  * Each of the `as_list` functions proxy to the `as_arraylist` functions.
93  * So, calling `as_list_destroy()` is equivalent to calling
94  * `as_arraylist_destroy()`.
95  *
96  * @extends as_list
97  * @ingroup aerospike_t
98  */
99 typedef struct as_arraylist_s {
100 
101  /**
102  * @private
103  * as_arraylist is an as_list.
104  * You can cast as_arraylist to as_list.
105  */
107 
108  /**
109  * Number of elements to add, when capacity is reached.
110  * If 0 (zero), then capacity can't be expanded.
111  */
112  uint32_t block_size;
113 
114  /**
115  * The total number elements allocated.
116  */
117  uint32_t capacity;
118 
119  /**
120  * The number of elements used.
121  */
122  uint32_t size;
123 
124  /**
125  * The elements of the list.
126  */
128 
129  /**
130  * If true, then as_arraylist.elements will be freed when
131  * as_arraylist_destroy() is called.
132  */
133  bool free;
134 
135 } as_arraylist;
136 
137 /**
138  * Status codes for various as_arraylist operations.
139  */
140 typedef enum as_arraylist_status_e {
141 
142  /**
143  * Normal operation.
144  */
146 
147  /**
148  * Unable to expand capacity, because cf_realloc() failed.
149  */
151 
152  /**
153  * Unable to expand capacity, because as_arraylist.block_size is 0.
154  */
156 
157  /**
158  * Illegal array index.
159  */
161 
163 
164 /******************************************************************************
165  * MACROS
166  ******************************************************************************/
167 
168 /**
169  * Initialize a stack allocated as_arraylist, with element storage on
170  * the stack.
171  *
172  * This differs from as_arraylist_init(), in that as_arraylist_init()
173  * allocates element storage on the heap.
174  *
175  * @param __list The as_list to initialize
176  * @param __n The number of elements to allocate to the list.
177  *
178  * @return On success, the initialize list. Otherwise NULL.
179  * @relatesalso as_arraylist
180  */
181 #define as_arraylist_inita(__list, __n)\
182  as_arraylist_init((__list), 0, 0);\
183  (__list)->free = false;\
184  (__list)->capacity = __n;\
185  (__list)->size = 0;\
186  (__list)->elements = (as_val **) alloca(sizeof(as_val *) * __n);
187 
188 /*******************************************************************************
189  * INSTANCE FUNCTIONS
190  ******************************************************************************/
191 
192 /**
193  * Initialize a stack allocated as_arraylist, with element storage on the
194  * heap.
195  *
196  * This differs from as_arraylist_inita(), in that as_arraylist_inita()
197  * allocates element storage on the stack.
198  *
199  * @param list The as_list to initialize
200  * @param capacity The number of elements to allocate to the list.
201  * @param block_size The number of elements to grow the list by, when the
202  * capacity has been reached.
203  *
204  * @return On success, the initialize list. Otherwise NULL.
205  * @relatesalso as_arraylist
206  */
207 as_arraylist * as_arraylist_init(as_arraylist * list, uint32_t capacity, uint32_t block_size);
208 
209 /**
210  * Create and initialize a heap allocated list as as_arraylist.
211  *
212  * @param capacity The number of elements to allocate to the list.
213  * @param block_size The number of elements to grow the list by, when the
214  * capacity has been reached.
215  *
216  * @return On success, the new list. Otherwise NULL.
217  * @relatesalso as_arraylist
218  */
219 as_arraylist * as_arraylist_new(uint32_t capacity, uint32_t block_size);
220 
221 /**
222  * Destoy the list and release resources.
223  *
224  * @param list The list to destroy.
225  * @relatesalso as_arraylist
226  */
228 
229 /*******************************************************************************
230  * VALUE FUNCTIONS
231  ******************************************************************************/
232 
233 /**
234  * The hash value of the list.
235  *
236  * @param list The list.
237  *
238  * @return The hash value of the list.
239  * @relatesalso as_arraylist
240  */
241 uint32_t as_arraylist_hashcode(const as_arraylist * list);
242 
243 /**
244  * The number of elements in the list.
245  *
246  * @param list The list.
247  *
248  * @return The number of elements in the list.
249  * @relatesalso as_arraylist
250  */
251 uint32_t as_arraylist_size(const as_arraylist * list);
252 
253 /*******************************************************************************
254  * ACCESSOR AND MODIFIER FUNCTIONS
255  ******************************************************************************/
256 
257 /**
258  * Append all elements of list2, in order, to list. No new list object is
259  * created.
260  *
261  * @param list The list to append to.
262  * @param list2 The list from which to append.
263  *
264  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
265  * @relatesalso as_arraylist
266  */
267 int as_arraylist_concat(as_arraylist * list, const as_arraylist * list2);
268 
269 /**
270  * Delete (and destroy) all elements at and beyond specified index. Capacity is
271  * not reduced.
272  *
273  * @param list The list to trim.
274  * @param index The index from which to trim.
275  *
276  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
277  * @relatesalso as_arraylist
278  */
279 int as_arraylist_trim(as_arraylist * list, uint32_t index);
280 
281 /**
282  * Get the first element of the list.
283  *
284  * @param list The list to get the first element from.
285  *
286  * @return The first element of the list. Otherwise NULL.
287  * @relatesalso as_arraylist
288  */
289 as_val * as_arraylist_head(const as_arraylist * list);
290 
291 /**
292  * Returns a new list containing all elements other than the head
293  *
294  * @param list The list to get the elements from.
295  *
296  * @return A new list of all elements after the first element.
297  * @relatesalso as_arraylist
298  */
300 
301 /**
302  * Return a new list with the first n elements removed.
303  *
304  * @param list The list.
305  * @param n The number of elements to remove.
306  *
307  * @return A new list of all elements after the first n elements.
308  * @relatesalso as_arraylist
309  */
310 as_arraylist * as_arraylist_drop(const as_arraylist * list, uint32_t n);
311 
312 /**
313  * Return a new list containing the first n elements.
314  *
315  * @param list The list.
316  * @param n The number of elements to take.
317  *
318  * @return A new list of the first n elements.
319  * @relatesalso as_arraylist
320  */
321 as_arraylist * as_arraylist_take(const as_arraylist * list, uint32_t n);
322 
323 /******************************************************************************
324  * GET FUNCTIONS
325  ******************************************************************************/
326 
327 /**
328  * Return the value at the specified index.
329  *
330  * @param list The list.
331  * @param index The index of the element.
332  *
333  * @return The value at given index, if it exists. Otherwise NULL.
334  * @relatesalso as_arraylist
335  */
336 as_val * as_arraylist_get(const as_arraylist * list, uint32_t index);
337 
338 /**
339  * Return an int64_t value at the specified index of the list.
340  *
341  * @param list The list.
342  * @param index The index of the element.
343  *
344  * @return The value at given index, if it exists. Otherwise NULL.
345  * @relatesalso as_arraylist
346  */
347 int64_t as_arraylist_get_int64(const as_arraylist * list, uint32_t index);
348 
349 /**
350  * Return a double value at the specified index of the list.
351  *
352  * @param list The list.
353  * @param index The index of the element.
354  *
355  * @return The value at given index, if it exists. Otherwise NULL.
356  * @relatesalso as_arraylist
357  */
358 double as_arraylist_get_double(const as_arraylist * list, uint32_t index);
359 
360 /**
361  * Return a NULL-terminated value at the specified index of the list.
362  *
363  * @param list The list.
364  * @param index The index of the element.
365  *
366  * @return The value at given index, if it exists. Otherwise NULL.
367  * @relatesalso as_arraylist
368  */
369 char * as_arraylist_get_str(const as_arraylist * list, uint32_t index);
370 
371 /**
372  * Return an as_integer value at the specified index of the list.
373  *
374  * @param list The list.
375  * @param index The index of the element.
376  *
377  * @return The value at given index, if it exists. Otherwise NULL.
378  * @relatesalso as_arraylist
379  */
380 static inline as_integer * as_arraylist_get_integer(const as_arraylist * list, uint32_t index)
381 {
382  return as_integer_fromval(as_arraylist_get(list, index));
383 }
384 
385 /**
386  * Return an as_double value at the specified index of the list.
387  *
388  * @param list The list.
389  * @param index The index of the element.
390  *
391  * @return The value at given index, if it exists. Otherwise NULL.
392  * @relatesalso as_arraylist
393  */
394 static inline as_double* as_arraylist_get_as_double(const as_arraylist * list, uint32_t index)
395 {
396  return as_double_fromval(as_arraylist_get(list, index));
397 }
398 
399 /**
400  * Return an as_string value at the specified index of the list.
401  *
402  * @param list The list.
403  * @param index The index of the element.
404  *
405  * @return The value at given index, if it exists. Otherwise NULL.
406  * @relatesalso as_arraylist
407  */
408 static inline as_string * as_arraylist_get_string(const as_arraylist * list, uint32_t index)
409 {
410  return as_string_fromval(as_arraylist_get(list, index));
411 }
412 
413 /**
414  * Return an as_bytes value at the specified index of the list.
415  *
416  * @param list The list.
417  * @param index The index of the element.
418  *
419  * @return The value at given index, if it exists. Otherwise NULL.
420  * @relatesalso as_arraylist
421  */
422 static inline as_bytes * as_arraylist_get_bytes(const as_arraylist * list, uint32_t index)
423 {
424  return as_bytes_fromval(as_arraylist_get(list, index));
425 }
426 
427 /**
428  * Return an as_list value at the specified index of the list.
429  *
430  * @param list The list.
431  * @param index The index of the element.
432  *
433  * @return The value at given index, if it exists. Otherwise NULL.
434  * @relatesalso as_arraylist
435  */
436 static inline as_list * as_arraylist_get_list(const as_arraylist * list, uint32_t index)
437 {
438  return as_list_fromval(as_arraylist_get(list, index));
439 }
440 
441 /**
442  * Return an as_map value at the specified index of the list.
443  *
444  * @param list The list.
445  * @param index The index of the element.
446  *
447  * @return The value at given index, if it exists. Otherwise NULL.
448  * @relatesalso as_arraylist
449  */
450 static inline as_map * as_arraylist_get_map(const as_arraylist * list, uint32_t index)
451 {
452  return as_map_fromval(as_arraylist_get(list, index));
453 }
454 
455 /******************************************************************************
456  * SET FUNCTIONS
457  ******************************************************************************/
458 
459 /**
460  * Set a value at the specified index of the list.
461  *
462  * Notice that in order to maintain proper object/memory management, we
463  * just first destroy (as_val_destroy()) the old object at element position(i)
464  * before assigning the new element. Also note that the object at element
465  * position (i) is assumed to exist, so all element positions must be
466  * appropriately initialized to zero.
467  *
468  * @param list The list.
469  * @param index Position in the list.
470  * @param value The value to set at the given index.
471  *
472  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
473  * @relatesalso as_arraylist
474  */
475 int as_arraylist_set(as_arraylist * list, uint32_t index, as_val * value);
476 
477 /**
478  * Set an int64_t value at the specified index of the list.
479  *
480  * @param list The list.
481  * @param index Position in the list.
482  * @param value The value to set at the given index.
483  *
484  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
485  * @relatesalso as_arraylist
486  */
487 int as_arraylist_set_int64(as_arraylist * list, uint32_t index, int64_t value);
488 
489 /**
490  * Set a double value at the specified index of the list.
491  *
492  * @param list The list.
493  * @param index Position in the list.
494  * @param value The value to set at the given index.
495  *
496  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
497  * @relatesalso as_arraylist
498  */
499 int as_arraylist_set_double(as_arraylist * list, uint32_t index, double value);
500 
501 /**
502  * Set a NULL-terminated string value at the specified index of the list.
503  *
504  * @param list The list.
505  * @param index Position in the list.
506  * @param value The value to set at the given index.
507  *
508  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
509  * @relatesalso as_arraylist
510  */
511 int as_arraylist_set_str(as_arraylist * list, uint32_t index, const char * value);
512 
513 /**
514  * Set an as_integer value at the specified index of the list.
515  *
516  * @param list The list.
517  * @param index Position in the list.
518  * @param value The value to set at the given index.
519  *
520  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
521  * @relatesalso as_arraylist
522  */
523 static inline int as_arraylist_set_integer(as_arraylist * list, uint32_t index, as_integer * value)
524 {
525  return as_arraylist_set(list, index, (as_val *) value);
526 }
527 
528 /**
529  * Set an as_double value at the specified index of the list.
530  *
531  * @param list The list.
532  * @param index Position in the list.
533  * @param value The value to set at the given index.
534  *
535  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
536  * @relatesalso as_arraylist
537  */
538 static inline int as_arraylist_set_as_double(as_arraylist * list, uint32_t index, as_double * value)
539 {
540  return as_arraylist_set(list, index, (as_val *) value);
541 }
542 
543 /**
544  * Set an as_string value at the specified index of the list.
545  *
546  * @param list The list.
547  * @param index Position in the list.
548  * @param value The value to set at the given index.
549  *
550  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
551  * @relatesalso as_arraylist
552  */
553 static inline int as_arraylist_set_string(as_arraylist * list, uint32_t index, as_string * value)
554 {
555  return as_arraylist_set(list, index, (as_val *) value);
556 }
557 
558 /**
559  * Set an as_bytes value at the specified index of the list.
560  *
561  * @param list The list.
562  * @param index Position in the list.
563  * @param value The value to set at the given index.
564  *
565  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
566  * @relatesalso as_arraylist
567  */
568 static inline int as_arraylist_set_bytes(as_arraylist * list, uint32_t index, as_bytes * value)
569 {
570  return as_arraylist_set(list, index, (as_val *) value);
571 }
572 
573 /**
574  * Set an as_list value at the specified index of the list.
575  *
576  * @param list The list.
577  * @param index Position in the list.
578  * @param value The value to set at the given index.
579  *
580  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
581  * @relatesalso as_arraylist
582  */
583 static inline int as_arraylist_set_list(as_arraylist * list, uint32_t index, as_list * value)
584 {
585  return as_arraylist_set(list, index, (as_val *) value);
586 }
587 
588 /**
589  * Set an as_map value at the specified index of the list.
590  *
591  * @param list The list.
592  * @param index Position in the list.
593  * @param value The value to set at the given index.
594  *
595  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
596  * @relatesalso as_arraylist
597  */
598 static inline int as_arraylist_set_map(as_arraylist * list, uint32_t index, as_map * value)
599 {
600  return as_arraylist_set(list, index, (as_val *) value);
601 }
602 
603 /******************************************************************************
604  * INSERT FUNCTIONS
605  ******************************************************************************/
606 
607 /**
608  * Insert a value at the specified index of the list.
609  *
610  * Any elements at and beyond specified index will be shifted so their indexes
611  * increase by 1. It's ok to insert beyond the current end of the list.
612  *
613  * @param list The list.
614  * @param index Position in the list.
615  * @param value The value to insert at the given index.
616  *
617  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
618  * @relatesalso as_arraylist
619  */
620 int as_arraylist_insert(as_arraylist * list, uint32_t index, as_val * value);
621 
622 /**
623  * Insert an int64_t value at the specified index of the list.
624  *
625  * @param list The list.
626  * @param index Position in the list.
627  * @param value The value to insert at the given index.
628  *
629  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
630  * @relatesalso as_arraylist
631  */
632 int as_arraylist_insert_int64(as_arraylist * list, uint32_t index, int64_t value);
633 
634 /**
635  * Insert a double value at the specified index of the list.
636  *
637  * @param list The list.
638  * @param index Position in the list.
639  * @param value The value to insert at the given index.
640  *
641  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
642  * @relatesalso as_arraylist
643  */
644 int as_arraylist_insert_double(as_arraylist * list, uint32_t index, double value);
645 
646 /**
647  * Insert a NULL-terminated string value at the specified index of the list.
648  *
649  * @param list The list.
650  * @param index Position in the list.
651  * @param value The value to insert at the given index.
652  *
653  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
654  * @relatesalso as_arraylist
655  */
656 int as_arraylist_insert_str(as_arraylist * list, uint32_t index, const char * value);
657 
658 /**
659  * Insert an as_integer value at the specified index of the list.
660  *
661  * @param list The list.
662  * @param index Position in the list.
663  * @param value The value to insert at the given index.
664  *
665  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
666  * @relatesalso as_arraylist
667  */
668 static inline int as_arraylist_insert_integer(as_arraylist * list, uint32_t index, as_integer * value)
669 {
670  return as_arraylist_insert(list, index, (as_val *) value);
671 }
672 
673 /**
674  * Insert an as_double value at the specified index of the list.
675  *
676  * @param list The list.
677  * @param index Position in the list.
678  * @param value The value to insert at the given index.
679  *
680  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
681  * @relatesalso as_arraylist
682  */
683 static inline int as_arraylist_insert_as_double(as_arraylist * list, uint32_t index, as_double * value)
684 {
685  return as_arraylist_insert(list, index, (as_val *) value);
686 }
687 
688 /**
689  * Insert an as_string value at the specified index of the list.
690  *
691  * @param list The list.
692  * @param index Position in the list.
693  * @param value The value to insert at the given index.
694  *
695  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
696  * @relatesalso as_arraylist
697  */
698 static inline int as_arraylist_insert_string(as_arraylist * list, uint32_t index, as_string * value)
699 {
700  return as_arraylist_insert(list, index, (as_val *) value);
701 }
702 
703 /**
704  * Insert an as_bytes value at the specified index of the list.
705  *
706  * @param list The list.
707  * @param index Position in the list.
708  * @param value The value to insert at the given index.
709  *
710  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
711  * @relatesalso as_arraylist
712  */
713 static inline int as_arraylist_insert_bytes(as_arraylist * list, uint32_t index, as_bytes * value)
714 {
715  return as_arraylist_insert(list, index, (as_val *) value);
716 }
717 
718 /**
719  * Insert an as_list value at the specified index of the list.
720  *
721  * @param list The list.
722  * @param index Position in the list.
723  * @param value The value to insert at the given index.
724  *
725  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
726  * @relatesalso as_arraylist
727  */
728 static inline int as_arraylist_insert_list(as_arraylist * list, uint32_t index, as_list * value)
729 {
730  return as_arraylist_insert(list, index, (as_val *) value);
731 }
732 
733 /**
734  * Insert an as_map value at the specified index of the list.
735  *
736  * @param list The list.
737  * @param index Position in the list.
738  * @param value The value to insert at the given index.
739  *
740  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
741  * @relatesalso as_arraylist
742  */
743 static inline int as_arraylist_insert_map(as_arraylist * list, uint32_t index, as_map * value)
744 {
745  return as_arraylist_insert(list, index, (as_val *) value);
746 }
747 
748 /******************************************************************************
749  * APPEND FUNCTIONS
750  ******************************************************************************/
751 
752 /**
753  * Add the value to the end of the list.
754  *
755  * @param list The list.
756  * @param value The value to prepend.
757  *
758  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
759  * @relatesalso as_arraylist
760  */
761 int as_arraylist_append(as_arraylist * list, as_val * value);
762 
763 /**
764  * Add an int64_t to the end of the list.
765  *
766  * @param list The list.
767  * @param value The value to prepend.
768  *
769  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
770  * @relatesalso as_arraylist
771  */
772 int as_arraylist_append_int64(as_arraylist * list, int64_t value);
773 
774 /**
775  * Add a double to the end of the list.
776  *
777  * @param list The list.
778  * @param value The value to prepend.
779  *
780  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
781  * @relatesalso as_arraylist
782  */
783 int as_arraylist_append_double(as_arraylist * list, double value);
784 
785 /**
786  * Add a NULL-terminated string to the end of the list.
787  *
788  * @param list The list.
789  * @param value The value to prepend.
790  *
791  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
792  * @relatesalso as_arraylist
793  */
794 int as_arraylist_append_str(as_arraylist * list, const char * value);
795 
796 /**
797  * Add an as_integer to the end of the list.
798  *
799  * @param list The list.
800  * @param value The value to prepend.
801  *
802  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
803  * @relatesalso as_arraylist
804  */
805 static inline int as_arraylist_append_integer(as_arraylist * list, as_integer * value)
806 {
807  return as_arraylist_append(list, (as_val *) value);
808 }
809 
810 /**
811  * Add an as_double to the end of the list.
812  *
813  * @param list The list.
814  * @param value The value to prepend.
815  *
816  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
817  * @relatesalso as_arraylist
818  */
819 static inline int as_arraylist_append_as_double(as_arraylist * list, as_double * value)
820 {
821  return as_arraylist_append(list, (as_val *) value);
822 }
823 
824 /**
825  * Add an as_string to the end of the list.
826  *
827  * @param list The list.
828  * @param value The value to prepend.
829  *
830  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
831  * @relatesalso as_arraylist
832  */
833 static inline int as_arraylist_append_string(as_arraylist * list, as_string * value)
834 {
835  return as_arraylist_append(list, (as_val *) value);
836 }
837 
838 /**
839  * Add an as_bytes to the end of the list.
840  *
841  * @param list The list.
842  * @param value The value to prepend.
843  *
844  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
845  * @relatesalso as_arraylist
846  */
847 static inline int as_arraylist_append_bytes(as_arraylist * list, as_bytes * value)
848 {
849  return as_arraylist_append(list, (as_val *) value);
850 }
851 
852 /**
853  * Add an as_list to the end of the list.
854  *
855  * @param list The list.
856  * @param value The value to prepend.
857  *
858  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
859  * @relatesalso as_arraylist
860  */
861 static inline int as_arraylist_append_list(as_arraylist * list, as_list * value)
862 {
863  return as_arraylist_append(list, (as_val *) value);
864 }
865 
866 /**
867  * Add an as_map to the end of the list.
868  *
869  * @param list The list.
870  * @param value The value to prepend.
871  *
872  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
873  * @relatesalso as_arraylist
874  */
875 static inline int as_arraylist_append_map(as_arraylist * list, as_map * value)
876 {
877  return as_arraylist_append(list, (as_val *) value);
878 }
879 
880 /******************************************************************************
881  * PREPEND FUNCTIONS
882  ******************************************************************************/
883 
884 /**
885  * Add the value to the beginning of the list.
886  *
887  * @param list The list.
888  * @param value The value to prepend.
889  *
890  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
891  * @relatesalso as_arraylist
892  */
893 int as_arraylist_prepend(as_arraylist * list, as_val * value);
894 
895 /**
896  * Add an int64_t to the beginning of the list.
897  *
898  * @param list The list.
899  * @param value The value to prepend.
900  *
901  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
902  * @relatesalso as_arraylist
903  */
904 int as_arraylist_prepend_int64(as_arraylist * list, int64_t value);
905 
906 /**
907  * Add a double to the beginning of the list.
908  *
909  * @param list The list.
910  * @param value The value to prepend.
911  *
912  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
913  * @relatesalso as_arraylist
914  */
915 int as_arraylist_prepend_double(as_arraylist * list, double value);
916 
917 /**
918  * Add a NULL-terminated string to the beginning of the list.
919  *
920  * @param list The list.
921  * @param value The value to prepend.
922  *
923  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
924  * @relatesalso as_arraylist
925  */
926 int as_arraylist_prepend_str(as_arraylist * list, const char * value);
927 
928 /**
929  * Add an as_integer to the beginning of the list.
930  *
931  * @param list The list.
932  * @param value The value to prepend.
933  *
934  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
935  * @relatesalso as_arraylist
936  */
937 static inline int as_arraylist_prepend_integer(as_arraylist * list, as_integer * value)
938 {
939  return as_arraylist_prepend(list, (as_val *) value);
940 }
941 
942 /**
943  * Add an as_double to the beginning of the list.
944  *
945  * @param list The list.
946  * @param value The value to prepend.
947  *
948  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
949  * @relatesalso as_arraylist
950  */
951 static inline int as_arraylist_prepend_as_double(as_arraylist * list, as_double * value)
952 {
953  return as_arraylist_prepend(list, (as_val *) value);
954 }
955 
956 /**
957  * Add an as_string to the beginning of the list.
958  *
959  * @param list The list.
960  * @param value The value to prepend.
961  *
962  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
963  * @relatesalso as_arraylist
964  */
965 static inline int as_arraylist_prepend_string(as_arraylist * list, as_string * value)
966 {
967  return as_arraylist_prepend(list, (as_val *) value);
968 }
969 
970 /**
971  * Add an as_bytes to the beginning of the list.
972  *
973  * @param list The list.
974  * @param value The value to prepend.
975  *
976  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
977  * @relatesalso as_arraylist
978  */
979 static inline int as_arraylist_prepend_bytes(as_arraylist * list, as_bytes * value)
980 {
981  return as_arraylist_prepend(list, (as_val *) value);
982 }
983 
984 /**
985  * Add an as_list to the beginning of the list.
986  *
987  * @param list The list.
988  * @param value The value to prepend.
989  *
990  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
991  * @relatesalso as_arraylist
992  */
993 static inline int as_arraylist_prepend_list(as_arraylist * list, as_list * value)
994 {
995  return as_arraylist_prepend(list, (as_val *) value);
996 }
997 
998 /**
999  * Add an as_map to the beginning of the list.
1000  *
1001  * @param list The list.
1002  * @param value The value to prepend.
1003  *
1004  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
1005  * @relatesalso as_arraylist
1006  */
1007 static inline int as_arraylist_prepend_map(as_arraylist * list, as_map * value)
1008 {
1009  return as_arraylist_prepend(list, (as_val *) value);
1010 }
1011 
1012 /*******************************************************************************
1013  * REMOVE FUNCTION
1014  ******************************************************************************/
1015 
1016 /**
1017  * Remove element at specified index.
1018  *
1019  * Any elements beyond specified index will be shifted so their indexes
1020  * decrease by 1. The element at specified index will be destroyed.
1021  *
1022  * @param list The list.
1023  * @param index The index of the element to remove.
1024  *
1025  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
1026  * @relatesalso as_arraylist
1027  */
1028 int as_arraylist_remove(as_arraylist * list, uint32_t index);
1029 
1030 /******************************************************************************
1031  * ITERATION FUNCTIONS
1032  ******************************************************************************/
1033 
1034 /**
1035  * Call the callback function for each element in the list.
1036  *
1037  * @param list The list to iterate.
1038  * @param callback The function to call for each element in the list.
1039  * @param udata User-data to be sent to the callback.
1040  *
1041  * @return true if iteration completes fully. false if iteration was aborted.
1042  *
1043  * @relatesalso as_arraylist
1044  */
1045 bool as_arraylist_foreach(const as_arraylist * list, as_list_foreach_callback callback, void * udata);
1046 
1047 #ifdef __cplusplus
1048 } // end extern "C"
1049 #endif