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