1ASON ITERATORS(3)                User Manuals                ASON ITERATORS(3)
2
3
4

NAME

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
11

SYNOPSIS

13       #include <ason/ason.h>
14       #include <ason/iter.h>
15
16       ason_iter_t *ason_iterate(ason_t *value);
17
18       int ason_iter_enter(ason_iter_t *iter);
19       int ason_iter_exit(ason_iter_t *iter);
20
21       int ason_iter_next(ason_iter_t *iter);
22       int ason_iter_prev(ason_iter_t *iter);
23
24       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
29       char *ason_iter_key(ason_iter_t *iter);
30
31       void ason_iter_destroy(ason_iter_t *iter);
32
33       ason_type_t ason_iter_type(ason_iter_t *iter);
34
35

DESCRIPTION

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
41       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
44       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
51       ason_iter_exit reverses the effect of ason_enter. The  iterator  points
52       back to the containing value.
53
54       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
58       ason_iter_type  returns  a  constant  indicating  the type of value the
59       iterator currently points to. See ason_values(3)
60
61       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
68       ason_iter_value  Returns  an ason_t * copy of the value the iterator is
69       currently pointing to.
70
71       ason_iter_key returns the key for  the  value  the  iterator  currently
72       points to, if we are iterating through an object.
73

RETURN VALUE

75       ason_iterate  returns  a  new  iterator  which  should be released with
76       ason_iter_destroy.
77
78       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
82       ason_iter_type returns a constant indicating the type of the value  the
83       iterator points to.
84
85       ason_iter_long,  and  ason_iter_double  return the numerical value that
86       the iterator points to.
87
88       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
92       ason_iter_value returns a value  of  type  ason_t  *  which  should  be
93       released with ason_destroy(3)
94

ERRORS

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
100       ason_iter_key  will  cause an abort if used while not iterating through
101       an object.
102

SEE ALSO

104       ason(3) ason_values(3)
105

AUTHOR

107       Casey Dahlin <casey.dahlin@gmail.com>
108
109
110
111Linux                            JANUARY 2014                ASON ITERATORS(3)
Impressum