ason_iterators - Man Page

#include <ason/ason.h>
#include <ason/iter.h>

ason_iter_t *ason_iterate(ason_t *value);

int ason_iter_enter(ason_iter_t *iter);
int ason_iter_exit(ason_iter_t *iter);

int ason_iter_next(ason_iter_t *iter);
int ason_iter_prev(ason_iter_t *iter);

long ason_iter_long(ason_iter_t *iter);
double ason_iter_double(ason_iter_t *iter);
char *ason_iter_string(ason_iter_t *iter);
ason_t *ason_iter_value(ason_iter_t *iter);

char *ason_iter_key(ason_iter_t *iter);

void ason_iter_destroy(ason_iter_t *iter);

ason_type_t ason_iter_type(ason_iter_t *iter);

ASON iterators are used to traverse ASON values and query individual values within. ASON iterators are created with ason_iterate, and they should be released after use with ason_iter_destroy.

Once created, the iterator points to the object which was passed to ason_iterate. You can get a copy of this value with ason_iter_value.

ason_iter_enter is used to begin iterating sub-values of a value. It will let you iterate through operands of an irreducible operator, values in a list, and key-value pairs in an object or universal object. Values joined by union operators are merged as one value, so if you entered the value 6 | 7 | 8 you would be able to iterate through 6, 7, and 8 sequentially.

ason_iter_exit reverses the effect of ason_enter. The iterator points back to the containing value.

ason_iter_next and ason_iter_prev shift to the next and previous values being iterated respectively. If we are at the beginning or end of the set they have no effect.

ason_iter_type returns a constant indicating the type of value the iterator currently points to. See ason_values(3)

ason_iter_long, ason_iter_double, and ason_iter_string return the C value of ASON numerical values or ASON string values. It is an error to use these functions when the iterator is not pointing to a value of the type they convert. Always use ason_iter_type to verify the type first. ason_iter_string returns a pointer to a region that must be freed with free(3).

ason_iter_value Returns an ason_t * copy of the value the iterator is currently pointing to.

ason_iter_key returns the key for the value the iterator currently points to, if we are iterating through an object.

ason_iterate returns a new iterator which should be released with ason_iter_destroy.

ason_iter_enter, ason_iter_exit, ason_iter_next, and ason_iter_prev will return nonzero when and only when it was possible to move the iterator in the way prescribed.

ason_iter_type returns a constant indicating the type of the value the iterator points to.

ason_iter_long, and ason_iter_double return the numerical value that the iterator points to.

ason_iter_string, and ason_iter_key return string pointers that should be released with free(3) and which contain the string value the iterator points to, or the key for the value the iterator points to.

ason_iter_value returns a value of type ason_t * which should be released with ason_destroy(3)

libason will abort if ason_iter_long, ason_iter_double, or ason_iter_string are used when the iterator does not point to the appropriate type of value.

ason_iter_key will cause an abort if used while not iterating through an object.

ason(3) ason_values(3)

Casey Dahlin <casey.dahlin@gmail.com>

ason(3).

The man pages ason_iterate(3), ason_iter_destroy(3), ason_iter_double(3), ason_iter_enter(3), ason_iter_exit(3), ason_iter_key(3), ason_iter_long(3), ason_iter_next(3), ason_iter_prev(3), ason_iter_string(3), ason_iter_type(3) and ason_iter_value(3) are aliases of ason_iterators(3).