1# @ajax/mesh-omap
2
3An ordered map from fixed-width u64 keys (1 to 6 words, compared word by word) to fixed-size values:
4an AVL tree. It is the C port's stand-in for Rust's `BTreeMap` wherever order matters: iteration in
5key order, the first and last entries, and range queries (`floor`, `ceil`, `next`, `prev`,
6`split_off`).
7
8```c
9#include "mesh/omap.h"
10momap *m = momap_new(1, sizeof(uint64_t), NULL, NULL);
11*(uint64_t *)momap_put1(m, 7, NULL) = 42;
12uint64_t k;
13for (uint64_t *v = momap_first(m, &k); v; v = momap_next(m, &k, &k)) { ... }
14```
15
16Values live in the nodes; a pointer to one is valid until the map changes. Iterating by key (as
17above) stays correct when the loop body removes or adds entries. A value that owns memory gets a
18release function (and a deep-copy function for `momap_clone`).
19
20## Ported from
21
22[alpha-rust-mesh](https://github.com/rsafier/alpha-rust-mesh) (Richard Safier, MIT) uses
23`std::collections::BTreeMap` throughout `crates/mesh-host`; this is the C port's equivalent, written
24for the jobs and blobs packages (`jobs.rs`, `blobs.rs`, `blobd.rs`).
25
26## Tests
27
28`tests/omap.c`: random puts, deletes and takes against a sorted-array reference with one- and
29three-word keys, every navigation query, deep clones, `split_off`, and a count of owned values (each
30released exactly once).
31
32## Licence
33
34MIT. See the repository's LICENSE.