All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_list.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_bytes.h>
21 #include <aerospike/as_integer.h>
22 #include <aerospike/as_iterator.h>
23 #include <aerospike/as_string.h>
24 #include <aerospike/as_util.h>
25 #include <aerospike/as_val.h>
26 
27 #include <stdbool.h>
28 #include <stdint.h>
29 
30 /******************************************************************************
31  * TYPES
32  *****************************************************************************/
33 
34 union as_list_iterator_u;
35 
36 struct as_list_hooks_s;
37 
38 /**
39  * Callback function for `as_list_foreach()`. Called for each element in the
40  * list.
41  *
42  * @param value The value of the current element.
43  * @param udata The user-data provided to the `as_list_foreach()`.
44  *
45  * @return true to continue iterating through the list.
46  * false to stop iterating.
47  */
48 typedef bool (* as_list_foreach_callback) (as_val * value, void * udata);
49 
50 /**
51  * as_list is an interface for List based data types.
52  *
53  * Implementations:
54  * - as_arraylist
55  *
56  * @extends as_val
57  * @ingroup aerospike_t
58  */
59 typedef struct as_list_s {
60 
61  /**
62  * @private
63  * as_list is a subtype of as_val.
64  * You can cast as_list to as_val.
65  */
67 
68  /**
69  * Pointer to the data for this list.
70  */
71  void * data;
72 
73  /**
74  * Hooks for subtypes of as_list to implement.
75  */
76  const struct as_list_hooks_s * hooks;
77 
78 } as_list;
79 
80 /**
81  * List Function Hooks
82  */
83 typedef struct as_list_hooks_s {
84 
85  /***************************************************************************
86  * instance hooks
87  **************************************************************************/
88 
89  /**
90  * Releases the subtype of as_list.
91  *
92  * @param map The map instance to destroy.
93  *
94  * @return true on success. Otherwise false.
95  */
96  bool (* destroy)(as_list * list);
97 
98  /***************************************************************************
99  * info hooks
100  **************************************************************************/
101 
102  /**
103  * The hash value of an as_list.
104  *
105  * @param list The list to get the hashcode value for.
106  *
107  * @return The hashcode value.
108  */
109  uint32_t (* hashcode)(const as_list * list);
110 
111  /**
112  * The size of the as_list.
113  *
114  * @param map The map to get the size of.
115  *
116  * @return The number of entries in the map.
117  */
118  uint32_t (* size)(const as_list * list);
119 
120  /***************************************************************************
121  * get hooks
122  **************************************************************************/
123 
124  /**
125  * Get the value at a given index of the list.
126  *
127  * @param list The list to get the value from.
128  * @param index The index of the value.
129  *
130  * @return The value at the given index on success. Otherwie NULL.
131  */
132  as_val * (* get)(const as_list * list, uint32_t index);
133 
134  /**
135  * Get the int64_t value at a given index of the list.
136  *
137  * @param list The list to get the value from.
138  * @param index The index of the value.
139  *
140  * @return The value at the given index on success. Otherwie NULL.
141  */
142  int64_t (* get_int64)(const as_list * list, uint32_t index);
143 
144  /**
145  * Get the NULL-terminated string value at a given index of the list.
146  *
147  * @param list The list to get the value from.
148  * @param index The index of the value.
149  *
150  * @return The value at the given index on success. Otherwie NULL.
151  */
152  char * (* get_str)(const as_list * list, uint32_t index);
153 
154  /***************************************************************************
155  * set hooks
156  **************************************************************************/
157 
158  /**
159  * Set a value at the given index of the list.
160  *
161  * @param list The list to get the value from.
162  * @param index The index of the value.
163  * @param value The value for the given index.
164  *
165  * @return The value at the given index on success. Otherwie NULL.
166  */
167  int (* set)(as_list * list, uint32_t index, as_val * value);
168 
169  /**
170  * Set an int64_t value at the given index of the list.
171  *
172  * @param list The list to get the value from.
173  * @param index The index of the value.
174  * @param value The value for the given index.
175  *
176  * @return The value at the given index on success. Otherwie NULL.
177  */
178  int (* set_int64)(as_list * list, uint32_t index, int64_t value);
179 
180  /**
181  * Set a NULL-terminated string value at the given index of the list.
182  *
183  * @param list The list to get the value from.
184  * @param index The index of the value.
185  * @param value The value for the given index.
186  *
187  * @return The value at the given index on success. Otherwie NULL.
188  */
189  int (* set_str)(as_list * list, uint32_t index, const char * value);
190 
191  /***************************************************************************
192  * insert hooks
193  **************************************************************************/
194 
195  /**
196  * Insert a value at the given index of the list.
197  *
198  * @param list The list to insert the value into.
199  * @param index The index of the value.
200  * @param value The value for the given index.
201  *
202  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
203  */
204  int (* insert)(as_list * list, uint32_t index, as_val * value);
205 
206  /**
207  * Insert an int64_t value at the given index of the list.
208  *
209  * @param list The list to insert the value into.
210  * @param index The index of the value.
211  * @param value The value for the given index.
212  *
213  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
214  */
215  int (* insert_int64)(as_list * list, uint32_t index, int64_t value);
216 
217  /**
218  * Insert a NULL-terminated string value at the given index of the list.
219  *
220  * @param list The list to insert the value into.
221  * @param index The index of the value.
222  * @param value The value for the given index.
223  *
224  * @return AS_ARRAYLIST_OK on success. Otherwise an error occurred.
225  */
226  int (* insert_str)(as_list * list, uint32_t index, const char * value);
227 
228  /***************************************************************************
229  * append hooks
230  **************************************************************************/
231 
232  /**
233  * Append a value to the list.
234  *
235  * @param list The list to append to.
236  * @param value The value to append to the list.
237  *
238  * @return 0 on success. Otherwise an error occurred.
239  */
240  int (* append)(as_list * list, as_val * value);
241 
242  /**
243  * Append an int64_t value to the list.
244  *
245  * @param list The list to append to.
246  * @param value The value to append to the list.
247  *
248  * @return 0 on success. Otherwise an error occurred.
249  */
250  int (* append_int64)(as_list * list, int64_t value);
251 
252  /**
253  * Append a NULL-terminates string value to the list.
254  *
255  * @param list The list to append to.
256  * @param value The value to append to the list.
257  *
258  * @return 0 on success. Otherwise an error occurred.
259  */
260  int (* append_str)(as_list * list, const char * value);
261 
262  /***************************************************************************
263  * prepend hooks
264  **************************************************************************/
265 
266  /**
267  * Prepend the value to the list.
268  *
269  * @param list The list to prepend to.
270  * @param value The value to prepend to the list.
271  *
272  * @return 0 on success. Otherwise an error occurred.
273  */
274  int (* prepend)(as_list * list, as_val * value);
275 
276  /**
277  * Prepend an int64_t value to the list.
278  *
279  * @param list The list to prepend to.
280  * @param value The value to prepend to the list.
281  *
282  * @return 0 on success. Otherwise an error occurred.
283  */
284  int (* prepend_int64)(as_list * list, int64_t value);
285 
286  /**
287  * Prepend a NULL-terminates string value to the list.
288  *
289  * @param list The list to prepend to.
290  * @param value The value to prepend to the list.
291  *
292  * @return 0 on success. Otherwise an error occurred.
293  */
294  int (* prepend_str)(as_list * list, const char * value);
295 
296  /***************************************************************************
297  * remove hook
298  **************************************************************************/
299 
300  /**
301  * Remove element at specified index.
302  *
303  * Any elements beyond specified index will be shifted so their indexes
304  * decrease by 1. The element at specified index will be destroyed.
305  *
306  * @param list The list.
307  * @param index The index of the element to remove.
308  *
309  * @return 0 on success. Otherwise an error occurred.
310  */
311  int (* remove)(as_list * list, uint32_t index);
312 
313  /***************************************************************************
314  * accessor and modifier hooks
315  **************************************************************************/
316 
317  /**
318  * Append all elements of list2, in order, to list. No new list object is
319  * created.
320  *
321  * @param list The list to append to.
322  * @param list2 The list from which to append.
323  *
324  * @return 0 on success. Otherwise an error occurred.
325  */
326  int (* concat)(as_list * list, const as_list * list2);
327 
328  /**
329  * Delete (and destroy) all elements at and beyond specified index. Capacity is
330  * not reduced.
331  *
332  * @param list The list to trim.
333  * @param index The index from which to trim.
334  *
335  * @return 0 on success. Otherwise an error occurred.
336  */
337  int (* trim)(as_list * list, uint32_t index);
338 
339  /**
340  * Return the first element in the list.
341  *
342  * @param list The list to get the value from.
343  *
344  * @return The first value in the list. Otherwise NULL.
345  */
346  as_val * (* head)(const as_list * list);
347 
348  /**
349  * Return all but the first element of the list, returning a new list.
350  *
351  * @param list The list to get the list from.
352  *
353  * @return The tail of the list. Otherwise NULL.
354  */
355  as_list * (* tail)(const as_list * list);
356 
357  /**
358  * Drop the first n element of the list, returning a new list.
359  *
360  * @param list The list.
361  * @param n The number of element to drop.
362  *
363  * @return A new list containing the remaining elements. Otherwise NULL.
364  */
365  as_list * (* drop)(const as_list * list, uint32_t n);
366 
367  /**
368  * Take the first n element of the list, returning a new list.
369  *
370  * @param list The list.
371  * @param n The number of element to take.
372  *
373  * @return A new list containing the remaining elements. Otherwise NULL.
374  */
375  as_list * (* take)(const as_list * list, uint32_t n);
376 
377  /***************************************************************************
378  * iteration hooks
379  **************************************************************************/
380 
381  /**
382  * Iterate over each element in the list can call the callback function.
383  *
384  * @param map The map to iterate.
385  * @param callback The function to call for each element in the list.
386  * @param udata User-data to be passed to the callback.
387  *
388  * @return true on success. Otherwise false.
389  */
390  bool (* foreach)(const as_list * list, as_list_foreach_callback callback, void * udata);
391 
392  /**
393  * Create and initialize a new heap allocated iterator to traverse over the list.
394  *
395  * @param list The list to iterate.
396  *
397  * @return true on success. Otherwise false.
398  */
399  union as_list_iterator_u * (* iterator_new)(const as_list * list);
400 
401  /**
402  * Initializes a stack allocated iterator to traverse over the list.
403  *
404  * @param list The list to iterate.
405  *
406  * @return true on success. Otherwise false.
407  */
408  union as_list_iterator_u * (* iterator_init)(const as_list * list, union as_list_iterator_u * it);
409 
410 } as_list_hooks;
411 
412 /*******************************************************************************
413  * INSTANCE FUNCTIONS
414  ******************************************************************************/
415 
416 /**
417  * @private
418  * Utilized by subtypes of as_list to initialize the parent.
419  *
420  * @param list The list to initialize.
421  * @param free If true, then as_list_destroy() will free the list.
422  * @param data Data for the list.
423  * @param hooks Implementaton for the list interface.
424  *
425  * @return On success, the initialized list. Otherwise NULL.
426  * @relatesalso as_list
427  */
428 as_list * as_list_cons(as_list * list, bool free, void * data, const as_list_hooks * hooks);
429 
430 /**
431  * Initialize a stack allocated list.
432  *
433  * @param list Stack allocated list to initialize.
434  * @param data Data for the list.
435  * @param hooks Implementaton for the list interface.
436  *
437  * @return On succes, the initialized list. Otherwise NULL.
438  * @relatesalso as_list
439  */
440 as_list * as_list_init(as_list * list, void * data, const as_list_hooks * hooks);
441 
442 /**
443  * Create and initialize a new heap allocated list.
444  *
445  * @param data Data for the list.
446  * @param hooks Implementaton for the list interface.
447  *
448  * @return On succes, a new list. Otherwise NULL.
449  * @relatesalso as_list
450  */
451 as_list * as_list_new(void * data, const as_list_hooks * hooks);
452 
453 /**
454  * Destroy the list and associated resources.
455  *
456  * @param list The list to destroy.
457  * @relatesalso as_list
458  */
459 static inline void as_list_destroy(as_list * list)
460 {
461  as_val_destroy((as_val *) list);
462 }
463 
464 /******************************************************************************
465  * INFO FUNCTIONS
466  *****************************************************************************/
467 
468 /**
469  * Get the hashcode value for the list.
470  *
471  * @param list The list.
472  *
473  * @return The hashcode of the list.
474  * @relatesalso as_list
475  */
476 static inline uint32_t as_list_hashcode(as_list * list)
477 {
478  return as_util_hook(hashcode, 0, list);
479 }
480 
481 /**
482  * Number of elements in the list.
483  *
484  * @param list The list.
485  *
486  * @return The size of the list.
487  * @relatesalso as_list
488  */
489 static inline uint32_t as_list_size(as_list * list)
490 {
491  return as_util_hook(size, 0, list);
492 }
493 
494 /******************************************************************************
495  * ACCESSOR AND MODIFIER FUNCTIONS
496  *****************************************************************************/
497 
498 /**
499  * Append all elements of list2, in order, to list. No new list object is
500  * created.
501  *
502  * @param list The list to append to.
503  * @param list2 The list from which to append.
504  *
505  * @return 0 on success. Otherwise an error occurred.
506  * @relatesalso as_list
507  */
508 static inline int as_list_concat(as_list * list, const as_list * list2)
509 {
510  return as_util_hook(concat, 1, list, list2);
511 }
512 
513 /**
514  * Delete (and destroy) all elements at and beyond specified index. Capacity is
515  * not reduced.
516  *
517  * @param list The list to trim.
518  * @param index The index from which to trim.
519  *
520  * @return 0 on success. Otherwise an error occurred.
521  * @relatesalso as_list
522  */
523 static inline int as_list_trim(as_list * list, uint32_t index)
524 {
525  return as_util_hook(trim, 1, list, index);
526 }
527 
528 /**
529  * The first element in the list.
530  *
531  * @param list The list to get the head value from.
532  *
533  * @return The first value of the list on success. Otherwise NULL.
534  * @relatesalso as_list
535  */
536 static inline as_val * as_list_head(const as_list * list)
537 {
538  return as_util_hook(head, NULL, list);
539 }
540 
541 /**
542  * All elements after the first element in the list.
543  *
544  * @param list The list to get the tail from.
545  *
546  * @return On success, the tail of the list. Otherwise NULL.
547  * @relatesalso as_list
548  */
549 static inline as_list * as_list_tail(const as_list * list)
550 {
551  return as_util_hook(tail, NULL, list);
552 }
553 
554 /**
555  * Create a new list containing all elements, except the first n elements, of the list.
556  *
557  * @param list The list to drop elements from.
558  * @param n The number of elements to drop.
559  *
560  * @return On success, a new list containing the remaining elements. Otherwise NULL.
561  * @relatesalso as_list
562  */
563 static inline as_list * as_list_drop(const as_list * list, uint32_t n)
564 {
565  return as_util_hook(drop, NULL, list, n);
566 }
567 
568 /**
569  * Creates a new list containing the first n elements of the list.
570  *
571  * @param list The list to drop elements from.
572  * @param n The number of elements to take.
573  *
574  * @return On success, a new list containing the selected elements. Otherwise NULL.
575  * @relatesalso as_list
576  */
577 static inline as_list * as_list_take(const as_list * list, uint32_t n)
578 {
579  return as_util_hook(take, NULL, list, n);
580 }
581 
582 /******************************************************************************
583  * GET FUNCTIONS
584  *****************************************************************************/
585 
586 /**
587  * Get the value at specified index as an as_val.
588  *
589  * @param list The list to get the value from.
590  * @param i The index of the value to get from the list.
591  *
592  * @return On success, the value at the given index. Otherwise NULL.
593  * @relatesalso as_list
594  */
595 static inline as_val * as_list_get(const as_list * list, uint32_t i)
596 {
597  return as_util_hook(get, NULL, list, i);
598 }
599 
600 /**
601  * Get the value at specified index as an int64_t.
602  *
603  * @param list The list to get the value from.
604  * @param i The index of the value to get from the list.
605  *
606  * @return On success, the value at the given index. Otherwise NULL.
607  * @relatesalso as_list
608  */
609 static inline int64_t as_list_get_int64(const as_list * list, uint32_t i)
610 {
611  return as_util_hook(get_int64, 0, list, i);
612 }
613 
614 /**
615  * Get the value at specified index as an NULL terminated string.
616  *
617  * @param list The list to get the value from.
618  * @param i The index of the value to get from the list.
619  *
620  * @return On success, the value at the given index. Otherwise NULL.
621  * @relatesalso as_list
622  */
623 static inline char * as_list_get_str(const as_list * list, uint32_t i)
624 {
625  return as_util_hook(get_str, NULL, list, i);
626 }
627 
628 /**
629  * Get the value at specified index as an as_integer.
630  *
631  * @param list The list to get the value from.
632  * @param i The index of the value to get from the list.
633  *
634  * @return On success, the value at the given index. Otherwise NULL.
635  * @relatesalso as_list
636  */
637 static inline as_integer * as_list_get_integer(const as_list * list, uint32_t i)
638 {
639  return as_integer_fromval(as_list_get(list, i));
640 }
641 
642 /**
643  * Get the value at specified index as an as_val.
644  *
645  * @param list The list to get the value from.
646  * @param i The index of the value to get from the list.
647  *
648  * @return On success, the value at the given index. Otherwise NULL.
649  * @relatesalso as_list
650  */
651 static inline as_string * as_list_get_string(const as_list * list, uint32_t i)
652 {
653  return as_string_fromval(as_list_get(list, i));
654 }
655 
656 /**
657  * Get the value at specified index as an as_val.
658  *
659  * @param list The list to get the value from.
660  * @param i The index of the value to get from the list.
661  *
662  * @return On success, the value at the given index. Otherwise NULL.
663  * @relatesalso as_list
664  */
665 static inline as_bytes * as_list_get_bytes(const as_list * list, uint32_t i)
666 {
667  return as_bytes_fromval(as_list_get(list, i));
668 }
669 
670 /**
671  * Get the value at specified index as an as_val.
672  *
673  * @param list The list to get the value from.
674  * @param i The index of the value to get from the list.
675  *
676  * @return On success, the value at the given index. Otherwise NULL.
677  * @relatesalso as_list
678  */
679 static inline as_list * as_list_get_list(const as_list * list, uint32_t i)
680 {
681  as_val * v = as_list_get(list, i);
682  return (as_list *) (v && v->type == AS_LIST ? v : NULL);
683 }
684 
685 /**
686  * Get the value at specified index as an as_val.
687  *
688  * @param list The list to get the value from.
689  * @param i The index of the value to get from the list.
690  *
691  * @return On success, the value at the given index. Otherwise NULL.
692  * @relatesalso as_list
693  */
694 static inline struct as_map_s * as_list_get_map(const as_list * list, uint32_t i)
695 {
696  as_val * v = as_list_get(list, i);
697  return (struct as_map_s *) (v && v->type == AS_MAP ? v : NULL);
698 }
699 
700 /******************************************************************************
701  * SET FUNCTIONS
702  *****************************************************************************/
703 
704 /**
705  * Set the value at specified index as an as_val.
706  *
707  * @param list The list.
708  * @param i The index of the value to set in the list.
709  * @param value The value to set at the given index.
710  *
711  * @return 0 on success. Otherwise an error occurred.
712  * @relatesalso as_list
713  */
714 static inline int as_list_set(as_list * list, uint32_t i, as_val * value)
715 {
716  return as_util_hook(set, 1, list, i, value);
717 }
718 
719 /**
720  * Set an int64_t at specified index as an as_val.
721  *
722  * @param list The list.
723  * @param i The index of the value to set in the list.
724  * @param value The value to set at the given index.
725  *
726  * @return 0 on success. Otherwise an error occurred.
727  * @relatesalso as_list
728  */
729 static inline int as_list_set_int64(as_list * list, uint32_t i, int64_t value)
730 {
731  return as_util_hook(set_int64, 1, list, i, value);
732 }
733 
734 /**
735  * Set a NULL-terminated string at specified index as an as_val.
736  *
737  * @param list The list.
738  * @param i The index of the value to set in the list.
739  * @param value The value to set at the given index.
740  *
741  * @return 0 on success. Otherwise an error occurred.
742  * @relatesalso as_list
743  */
744 static inline int as_list_set_str(as_list * list, uint32_t i, const char * value)
745 {
746  return as_util_hook(set_str, 1, list, i, value);
747 }
748 
749 /**
750  * Set an as_integer at specified index as an as_val.
751  *
752  * @param list The list.
753  * @param i The index of the value to set in the list.
754  * @param value The value to set at the given index.
755  *
756  * @return 0 on success. Otherwise an error ocucrred.
757  * @relatesalso as_list
758  */
759 static inline int as_list_set_integer(as_list * list, uint32_t i, as_integer * value)
760 {
761  return as_list_set(list, i, (as_val *) value);
762 }
763 
764 /**
765  * Set an as_string at specified index as an as_val.
766  *
767  * @param list The list.
768  * @param i The index of the value to set in the list.
769  * @param value The value to set at the given index.
770  *
771  * @return 0 on success. Otherwise an error occurred.
772  * @relatesalso as_list
773  */
774 static inline int as_list_set_string(as_list * list, uint32_t i, as_string * value)
775 {
776  return as_list_set(list, i, (as_val *) value);
777 }
778 
779 /**
780  * Set an as_bytes at specified index as an as_val.
781  *
782  * @param list The list.
783  * @param i The index of the value to set in the list.
784  * @param value The value to set at the given index.
785  *
786  * @return 0 on success. Otherwise an error occurred.
787  * @relatesalso as_list
788  */
789 static inline int as_list_set_bytes(as_list * list, uint32_t i, as_bytes * value)
790 {
791  return as_list_set(list, i, (as_val *) value);
792 }
793 
794 /**
795  * Set an as_list at specified index as an as_val.
796  *
797  * @param list The list.
798  * @param i The index of the value to set in the list.
799  * @param value The value to set at the given index.
800  *
801  * @return 0 on success. Otherwise an error occurred.
802  * @relatesalso as_list
803  */
804 static inline int as_list_set_list(as_list * list, uint32_t i, as_list * value)
805 {
806  return as_list_set(list, i, (as_val *) value);
807 }
808 
809 /**
810  * Set an as_map at specified index as an as_val.
811  *
812  * @param list The list.
813  * @param i The index of the value to set in the list.
814  * @param value The value to set at the given index.
815  *
816  * @return 0 on success. Otherwise an error occurred.
817  * @relatesalso as_list
818  */
819 static inline int as_list_set_map(as_list * list, uint32_t i, struct as_map_s * value)
820 {
821  return as_list_set(list, i, (as_val *) value);
822 }
823 
824 /******************************************************************************
825  * INSERT FUNCTIONS
826  *****************************************************************************/
827 
828 /**
829  * Insert a value at the specified index of the list.
830  *
831  * Any elements at and beyond specified index will be shifted so their indexes
832  * increase by 1. It's ok to insert beyond the current end of the list.
833  *
834  * @param list The list.
835  * @param i The index at which to insert.
836  * @param value The value to insert at the given index.
837  *
838  * @return 0 on success. Otherwise an error occurred.
839  * @relatesalso as_list
840  */
841 static inline int as_list_insert(as_list * list, uint32_t i, as_val * value)
842 {
843  return as_util_hook(insert, 1, list, i, value);
844 }
845 
846 /**
847  * Insert an int64_t at specified index as an as_val.
848  *
849  * @param list The list.
850  * @param i The index at which to insert.
851  * @param value The value to insert at the given index.
852  *
853  * @return 0 on success. Otherwise an error occurred.
854  * @relatesalso as_list
855  */
856 static inline int as_list_insert_int64(as_list * list, uint32_t i, int64_t value)
857 {
858  return as_util_hook(insert_int64, 1, list, i, value);
859 }
860 
861 /**
862  * Insert a NULL-terminated string at specified index as an as_val.
863  *
864  * @param list The list.
865  * @param i The index at which to insert.
866  * @param value The value to insert at the given index.
867  *
868  * @return 0 on success. Otherwise an error occurred.
869  * @relatesalso as_list
870  */
871 static inline int as_list_insert_str(as_list * list, uint32_t i, const char * value)
872 {
873  return as_util_hook(insert_str, 1, list, i, value);
874 }
875 
876 /**
877  * Insert an as_integer at specified index as an as_val.
878  *
879  * @param list The list.
880  * @param i The index at which to insert.
881  * @param value The value to insert at the given index.
882  *
883  * @return 0 on success. Otherwise an error ocucrred.
884  * @relatesalso as_list
885  */
886 static inline int as_list_insert_integer(as_list * list, uint32_t i, as_integer * value)
887 {
888  return as_list_insert(list, i, (as_val *) value);
889 }
890 
891 /**
892  * Insert an as_string at specified index as an as_val.
893  *
894  * @param list The list.
895  * @param i The index at which to insert.
896  * @param value The value to insert at the given index.
897  *
898  * @return 0 on success. Otherwise an error occurred.
899  * @relatesalso as_list
900  */
901 static inline int as_list_insert_string(as_list * list, uint32_t i, as_string * value)
902 {
903  return as_list_insert(list, i, (as_val *) value);
904 }
905 
906 /**
907  * Insert an as_bytes at specified index as an as_val.
908  *
909  * @param list The list.
910  * @param i The index at which to insert.
911  * @param value The value to insert at the given index.
912  *
913  * @return 0 on success. Otherwise an error occurred.
914  * @relatesalso as_list
915  */
916 static inline int as_list_insert_bytes(as_list * list, uint32_t i, as_bytes * value)
917 {
918  return as_list_insert(list, i, (as_val *) value);
919 }
920 
921 /**
922  * Insert an as_list at specified index as an as_val.
923  *
924  * @param list The list.
925  * @param i The index at which to insert.
926  * @param value The value to insert at the given index.
927  *
928  * @return 0 on success. Otherwise an error occurred.
929  * @relatesalso as_list
930  */
931 static inline int as_list_insert_list(as_list * list, uint32_t i, as_list * value)
932 {
933  return as_list_insert(list, i, (as_val *) value);
934 }
935 
936 /**
937  * Insert an as_map at specified index as an as_val.
938  *
939  * @param list The list.
940  * @param i The index at which to insert.
941  * @param value The value to insert at the given index.
942  *
943  * @return 0 on success. Otherwise an error occurred.
944  * @relatesalso as_list
945  */
946 static inline int as_list_insert_map(as_list * list, uint32_t i, struct as_map_s * value)
947 {
948  return as_list_insert(list, i, (as_val *) value);
949 }
950 
951 /******************************************************************************
952  * APPEND FUNCTIONS
953  *****************************************************************************/
954 
955 /**
956  * Append a value to the list.
957  *
958  * @param list The list.
959  * @param value The value to append to the list.
960  *
961  * @return 0 on success. Otherwise an error occurred.
962  * @relatesalso as_list
963  */
964 static inline int as_list_append(as_list * list, as_val * value)
965 {
966  return as_util_hook(append, 1, list, value);
967 }
968 
969 /**
970  * Append an int64_t to the list.
971  *
972  * @param list The list.
973  * @param value The value to append to the list.
974  *
975  * @return 0 on success. Otherwise an error occurred.
976  * @relatesalso as_list
977  */
978 static inline int as_list_append_int64(as_list * list, int64_t value)
979 {
980  return as_util_hook(append_int64, 1, list, value);
981 }
982 
983 /**
984  * Append a NULL-terminated string to the list.
985  *
986  * @param list The list.
987  * @param value The value to append to the list.
988  *
989  * @return 0 on success. Otherwise an error occurred.
990  * @relatesalso as_list
991  */
992 static inline int as_list_append_str(as_list * list, const char * value)
993 {
994  return as_util_hook(append_str, 1, list, value);
995 }
996 
997 /**
998  * Append an as_integer to the list.
999  *
1000  * @param list The list.
1001  * @param value The value to append to the list.
1002  *
1003  * @return 0 on success. Otherwise an error occurred.
1004  * @relatesalso as_list
1005  */
1006 static inline int as_list_append_integer(as_list * list, as_integer * value)
1007 {
1008  return as_list_append(list, (as_val *) value);
1009 }
1010 
1011 /**
1012  * Append an as_string to the list.
1013  *
1014  * @param list The list.
1015  * @param value The value to append to the list.
1016  *
1017  * @return 0 on success. Otherwise an error occurred.
1018  * @relatesalso as_list
1019  */
1020 static inline int as_list_append_string(as_list * list, as_string * value)
1021 {
1022  return as_list_append(list, (as_val *) value);
1023 }
1024 
1025 /**
1026  * Append an as_bytes to the list.
1027  *
1028  * @param list The list.
1029  * @param value The value to append to the list.
1030  *
1031  * @return 0 on success. Otherwise an error occurred.
1032  * @relatesalso as_list
1033  */
1034 static inline int as_list_append_bytes(as_list * list, as_bytes * value)
1035 {
1036  return as_list_append(list, (as_val *) value);
1037 }
1038 
1039 /**
1040  * Append an as_list to the list.
1041  *
1042  * @param list The list.
1043  * @param value The value to append to the list.
1044  *
1045  * @return 0 on success. Otherwise an error occurred.
1046  * @relatesalso as_list
1047  */
1048 static inline int as_list_append_list(as_list * list, as_list * value)
1049 {
1050  return as_list_append(list, (as_val *) value);
1051 }
1052 
1053 /**
1054  * Append an as_map to the list.
1055  *
1056  * @param list The list.
1057  * @param value The value to append to the list.
1058  *
1059  * @return 0 on success. Otherwise an error occurred.
1060  * @relatesalso as_list
1061  */
1062 static inline int as_list_append_map(as_list * list, struct as_map_s * value)
1063 {
1064  return as_list_append(list, (as_val *) value);
1065 }
1066 
1067 /******************************************************************************
1068  * PREPEND FUNCTIONS
1069  *****************************************************************************/
1070 
1071 /**
1072  * Prepend a value to the list.
1073  *
1074  * @param list The list.
1075  * @param value The value to prepend to the list.
1076  *
1077  * @return 0 on success. Otherwise an error occurred.
1078  * @relatesalso as_list
1079  */
1080 static inline int as_list_prepend(as_list * list, as_val * value)
1081 {
1082  return as_util_hook(prepend, 1, list, value);
1083 }
1084 
1085 /**
1086  * Prepend an int64_t value to the list.
1087  *
1088  * @param list The list.
1089  * @param value The value to prepend to the list.
1090  *
1091  * @return 0 on success. Otherwise an error occurred.
1092  * @relatesalso as_list
1093  */
1094 static inline int as_list_prepend_int64(as_list * list, int64_t value)
1095 {
1096  return as_util_hook(prepend_int64, 1, list, value);
1097 }
1098 
1099 /**
1100  * Prepend a NULL-terminated string to the list.
1101  *
1102  * @param list The list.
1103  * @param value The value to prepend to the list.
1104  *
1105  * @return 0 on success. Otherwise an error occurred.
1106  * @relatesalso as_list
1107  */
1108 static inline int as_list_prepend_str(as_list * list, const char * value)
1109 {
1110  return as_util_hook(prepend_str, 1, list, value);
1111 }
1112 
1113 /**
1114  * Prepend an as_integer to the list.
1115  *
1116  * @param list The list.
1117  * @param value The value to prepend to the list.
1118  *
1119  * @return 0 on success. Otherwise an error occurred.
1120  * @relatesalso as_list
1121  */
1122 static inline int as_list_prepend_integer(as_list * list, as_integer * value)
1123 {
1124  return as_list_prepend(list, (as_val *) value);
1125 }
1126 
1127 /**
1128  * Prepend an as_string to the list.
1129  *
1130  * @param list The list.
1131  * @param value The value to prepend to the list.
1132  *
1133  * @return 0 on success. Otherwise an error occurred.
1134  * @relatesalso as_list
1135  */
1136 static inline int as_list_prepend_string(as_list * list, as_string * value)
1137 {
1138  return as_list_prepend(list, (as_val *) value);
1139 }
1140 
1141 /**
1142  * Prepend an as_bytes to the list.
1143  *
1144  * @param list The list.
1145  * @param value The value to prepend to the list.
1146  *
1147  * @return 0 on success. Otherwise an error occurred.
1148  * @relatesalso as_list
1149  */
1150 static inline int as_list_prepend_bytes(as_list * list, as_bytes * value)
1151 {
1152  return as_list_prepend(list, (as_val *) value);
1153 }
1154 
1155 /**
1156  * Prepend an as_list to the list.
1157  *
1158  * @param list The list.
1159  * @param value The value to prepend to the list.
1160  *
1161  * @return 0 on success. Otherwise an error occurred.
1162  * @relatesalso as_list
1163  */
1164 static inline int as_list_prepend_list(as_list * list, as_list * value)
1165 {
1166  return as_list_prepend(list, (as_val *) value);
1167 }
1168 
1169 /**
1170  * Prepend an as_map to the list.
1171  *
1172  * @param list The list.
1173  * @param value The value to prepend to the list.
1174  *
1175  * @return 0 on success. Otherwise an error occurred.
1176  * @relatesalso as_list
1177  */
1178 static inline int as_list_prepend_map(as_list * list, struct as_map_s * value)
1179 {
1180  return as_list_prepend(list, (as_val *) value);
1181 }
1182 
1183 /******************************************************************************
1184  * REMOVE FUNCTION
1185  *****************************************************************************/
1186 
1187 /**
1188  * Remove element at specified index.
1189  *
1190  * Any elements beyond specified index will be shifted so their indexes
1191  * decrease by 1. The element at specified index will be destroyed.
1192  *
1193  * @param list The list.
1194  * @param index The index of the element to remove.
1195  *
1196  * @return 0 on success. Otherwise an error occurred.
1197  * @relatesalso as_list
1198  */
1199 static inline int as_list_remove(as_list * list, uint32_t i)
1200 {
1201  return as_util_hook(remove, 1, list, i);
1202 }
1203 
1204 /******************************************************************************
1205  * ITERATION FUNCTIONS
1206  *****************************************************************************/
1207 
1208 /**
1209  * Call the callback function for each element in the list..
1210  *
1211  * @param list The list to iterate over.
1212  * @param callback The callback function call for each element.
1213  * @param udata User-data to send to the callback.
1214  *
1215  * @return true if iteration completes fully. false if iteration was aborted.
1216  *
1217  * @relatesalso as_list
1218  */
1219 static inline bool as_list_foreach(const as_list * list, as_list_foreach_callback callback, void * udata)
1220 {
1221  return as_util_hook(foreach, false, list, callback, udata);
1222 }
1223 
1224 /**
1225  * Creates and initializes a new heap allocated iterator over the given list.
1226  *
1227  * @param list The list to iterate.
1228  *
1229  * @return On success, a new as_iterator. Otherwise NULL.
1230  * @relatesalso as_list
1231  */
1232 static inline union as_list_iterator_u * as_list_iterator_new(const as_list * list)
1233 {
1234  return as_util_hook(iterator_new, NULL, list);
1235 }
1236 
1237 
1238 /**
1239  * Initializes a stack allocated iterator over the given list.
1240  *
1241  * @param list The list to iterate.
1242  * @param it The iterator to initialize.
1243  *
1244  * @return On success, the initializes as_iterator. Otherwise NULL.
1245  * @relatesalso as_list
1246  */
1247 static inline union as_list_iterator_u * as_list_iterator_init(union as_list_iterator_u * it, const as_list * list)
1248 {
1249  return as_util_hook(iterator_init, NULL, list, it);
1250 }
1251 
1252 /******************************************************************************
1253  * CONVERSION FUNCTIONS
1254  *****************************************************************************/
1255 
1256 /**
1257  * Convert to an as_val.
1258  * @relatesalso as_list
1259  */
1260 static inline as_val * as_list_toval(as_list * list)
1261 {
1262  return (as_val *) list;
1263 }
1264 
1265 /**
1266  * Convert from an as_val.
1267  * @relatesalso as_list
1268  */
1269 static inline as_list * as_list_fromval(as_val * v)
1270 {
1271  return as_util_fromval(v, AS_LIST, as_list);
1272 }
1273 
1274 /******************************************************************************
1275  * as_val FUNCTIONS
1276  *****************************************************************************/
1277 
1278 /**
1279  * @private
1280  * Internal helper function for destroying an as_val.
1281  */
1282 void as_list_val_destroy(as_val * v);
1283 
1284 /**
1285  * @private
1286  * Internal helper function for getting the hashcode of an as_val.
1287  */
1288 uint32_t as_list_val_hashcode(const as_val * v);
1289 
1290 /**
1291  * @private
1292  * Internal helper function for getting the string representation of an as_val.
1293  */
1294 char * as_list_val_tostring(const as_val * v);
1295