MTBL_ITER(3)

💖 MTBL_ITER 💖

okay bestie, welcome to the mtbl_iter(3) page — this is the whole entire manual for iterating over a sequence of key-value pairs, and yes it's short, but it's iconic, so let's get into it 🦋

✨ NAME ✨

mtbl_iter — iterate over a sequence of key-value pairs

lowkey that's the whole vibe. you got a bunch of key-value pairs, you wanna walk through them one by one, mtbl_iter is the girl for the job 💅

✨ SYNOPSIS ✨

first things first, you gotta pull in the header:

#include <mtbl.h>

then here's your three function signatures, no cap:

mtbl_res
mtbl_iter_next(struct mtbl_iter *it,
        const uint8_t **key, size_t *len_key,
        const uint8_t **val, size_t *len_val);

void
mtbl_iter_destroy(struct mtbl_iter **it);

mtbl_res
mtbl_iter_seek(struct mtbl_iter *it,
        const uint8_t *key, size_t len_key);

✨ DESCRIPTION ✨

so the mtbl_iter interface is literally just here to hand you back a sequence of one or more key-value pairs. that's the assignment. that's the job. 🎀

once you've got yourself an mtbl_iter object, the way that you use it is: you call mtbl_iter_next() over and over and over again, bestie, until there are absolutely no more key-value entries left to retrieve. and the moment you hit that point — when it's all done, when the well is dry — you must free the iterator object by calling mtbl_iter_destroy(). not optional. free your girl, she's done her service 🫶

and here's the cute part: mtbl_iter_seek() can be called on the iterator to seek to a different location in the index, and you can do this without having to destroy the iterator and build a whole new one from scratch. no wasteful breakups and makeups. you just seek. slay 💅✨

✨ RETURN VALUE ✨

okay so mtbl_iter_next() returns mtbl_res_success when a key-value entry was successfully retrieved — and when that happens, key and val will point to buffers of length len_key and len_val respectively. so good. so clean. 🌸

and then the value mtbl_res_failure gets returned in two situations, and you need to know both of them:

• there are no more entries to read 📭
• the it argument is NULL 💀

that's it. that's the whole return contract. iykyk.

✨ SEE ALSO ✨

• mtbl_source(3)

go read that one too, bestie, it's giving related 💜

and that's the page!! written under the MTBL_ITER(3) name, dated 03/29/2019 — mwah, a classic, a time capsule, we love her 🎀✨ bye pookie, go iterate responsibly 🦋