1ASON ITERATORS(3) User Manuals ASON ITERATORS(3)
2
6 ason_iterate, ason_iter_enter, ason_iter_exit, ason_iter_next,
7 ason_iter_prev, ason_iter_long, ason_iter_double, ason_iter_string,
8 ason_iter_value, ason_iter_key, ason_iter_destroy, ason_iter_type -
9 Create and adjust iterators to explore ason_t values.
10
13 #include <ason/ason.h>
14 #include <ason/iter.h>
15 ason_iter_t *ason_iterate(ason_t *value);
17 int ason_iter_enter(ason_iter_t *iter);
19 int ason_iter_exit(ason_iter_t *iter);
20 int ason_iter_next(ason_iter_t *iter);
22 int ason_iter_prev(ason_iter_t *iter);
23 long ason_iter_long(ason_iter_t *iter);
25 double ason_iter_double(ason_iter_t *iter);
26 char *ason_iter_string(ason_iter_t *iter);
27 ason_t *ason_iter_value(ason_iter_t *iter);
28 char *ason_iter_key(ason_iter_t *iter);
30 void ason_iter_destroy(ason_iter_t *iter);
32 ason_type_t ason_iter_type(ason_iter_t *iter);
34
37 ASON iterators are used to traverse ASON values and query individual
38 values within. ASON iterators are created with ason_iterate, and they
39 should be released after use with ason_iter_destroy.
40 Once created, the iterator points to the object which was passed to
42 ason_iterate. You can get a copy of this value with ason_iter_value.
43 ason_iter_enter is used to begin iterating sub-values of a value. It
45 will let you iterate through operands of an irreducible operator, val‐
46 ues in a list, and key-value pairs in an object or universal object.
47 Values joined by union operators are merged as one value, so if you
48 entered the value 6 | 7 | 8 you would be able to iterate through 6, 7,
49 and 8 sequentially.
50 ason_iter_exit reverses the effect of ason_enter. The iterator points
52 back to the containing value.
53 ason_iter_next and ason_iter_prev shift to the next and previous values
55 being iterated respectively. If we are at the beginning or end of the
56 set they have no effect.
57 ason_iter_type returns a constant indicating the type of value the
59 iterator currently points to. See ason_values(3)
60 ason_iter_long, ason_iter_double, and ason_iter_string return the C
62 value of ASON numerical values or ASON string values. It is an error to
63 use these functions when the iterator is not pointing to a value of the
64 type they convert. Always use ason_iter_type to verify the type first.
65 ason_iter_string returns a pointer to a region that must be freed with
66 free(3).
67 ason_iter_value Returns an ason_t * copy of the value the iterator is
69 currently pointing to.
70 ason_iter_key returns the key for the value the iterator currently
72 points to, if we are iterating through an object.
73
75 ason_iterate returns a new iterator which should be released with
76 ason_iter_destroy.
77 ason_iter_enter, ason_iter_exit, ason_iter_next, and ason_iter_prev
79 will return nonzero when and only when it was possible to move the
80 iterator in the way prescribed.
81 ason_iter_type returns a constant indicating the type of the value the
83 iterator points to.
84 ason_iter_long, and ason_iter_double return the numerical value that
86 the iterator points to.
87 ason_iter_string, and ason_iter_key return string pointers that should
89 be released with free(3) and which contain the string value the itera‐
90 tor points to, or the key for the value the iterator points to.
91 ason_iter_value returns a value of type ason_t * which should be
93 released with ason_destroy(3)
94
96 libason will abort if ason_iter_long, ason_iter_double, or
97 ason_iter_string are used when the iterator does not point to the
98 appropriate type of value.
99 ason_iter_key will cause an abort if used while not iterating through
101 an object.
102
104 ason(3) ason_values(3)
105
107 Casey Dahlin <casey.dahlin@gmail.com>
108Linux JANUARY 2014 ASON ITERATORS(3)