ASON_ITER_VALUE(3)

🎀 NAME 🎀

okay bestie, meet the whole squad: ason_iterate, ason_iter_enter, ason_iter_exit, ason_iter_next, ason_iter_prev, ason_iter_long, ason_iter_double, ason_iter_string, ason_iter_value, ason_iter_key, ason_iter_destroy, ason_iter_type — they're all about creating and adjusting iterators so you can go explore ason_t values. this is the ASON ITERATORS(3) page from the User Manuals, and it's giving main character energy fr fr 💅

---

✨ SYNOPSIS ✨

#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);

---

💖 DESCRIPTION 💖

so like, ASON iterators are the lil tour guides you use to traverse ASON values and query the individual values hiding inside. you make one with ason_iterate, and the way that you should always release it after use with ason_iter_destroy — no leaving your iterator out in the cold, okay? 🥺

the second you create it, the iterator is pointing at the object you passed into ason_iterate. want a copy of that value? ason_iter_value has you covered, bestie.

• ason_iter_enter — this is your "go deeper" button. it starts iterating the sub-values of a value. it'll let you walk through:
  • operands of an irreducible operator,
  • values in a list,
  • and key-value pairs in an object or universal object.

plot twist: values joined by union operators get merged into one value, so if you entered 6 | 7 | 8 you'd be able to iterate through 6, 7, and 8 sequentially. iconic behavior honestly.

• ason_iter_exit — reverses the effect of ason_enter. the iterator points back to the containing value. bye, we're going back up 💅
• ason_iter_next and ason_iter_prev — shift to the next and previous values being iterated, respectively. if you're already at the beginning or the end of the set? they have no effect. nothing happens. no drama. it's fine.
• ason_iter_type — returns a constant indicating the type of value the iterator currently points to. see ason_values(3) for the tea ☕
• ason_iter_long, ason_iter_double, and ason_iter_string — these return the C value of ASON numerical values or ASON string values. and ngl, it is an error to use these functions when the iterator is not pointing to a value of the type they convert. so like... always use ason_iter_type to verify the type first. no cap. also ason_iter_string returns a pointer to a region that must be freed with free(3) — don't forget, bestie 🫶
• 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.

---

🌸 RETURN VALUE 🌸

• ason_iterate returns a new iterator which should be released with ason_iter_destroy. (yes, release it. it's the rules 💖)
• 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).

---

💀 ERRORS 💀

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. 😭 check the type first, i am literally begging.

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

---

🦋 SEE ALSO 🦋

ason(3) ason_values(3)

---

👑 AUTHOR 👑

Casey Dahlin <casey.dahlin@gmail.com>

---

okay that's the whole page, you ate that bestie ✨ this lil gem comes to you from Linux, dated JANUARY 2014, and it's the ASON ITERATORS(3) manual page. go forth and iterate responsibly, mwah 💋🎀🦋