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