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