dnsjit.lib.trie(3)

💖 dnsjit.lib.trie(3) 💖

okay bestie, sit down, hydrate, because we're talking about dnsjit.lib.trie — it's a lib function, it lives in the Library Functions Manual, and it's genuinely one of the cutest little data structures out there. no cap.

---

✨ NAME ✨

dnsjit.lib.trie — a prefix-tree data structure that addresses values by strings or byte arrays. it's giving "lookup but make it a tree" 🌳

---

🌸 SYNOPSIS 🌸

🎀 Binary-key trie with integer values 🎀

local trie = require("dnsjit.lib.trie").new("uint64_t", true, 4)
-- assume we have a bunch of dnsjit.core.object.ip packets to process
for _, pkt in pairs(pkts) do
    local node = trie:get_ins(pkt.src)
    local value = node:get()  -- new nodes' values are initialized to 0
    node:set(value + 1)
end
-- iterate over unique IPs and print number of packets received from each
local iter = trie:iter()
local node = iter:node()
local p = require("dnsjit.lib.ip")
while node ~= nil do
    local ip_bytes = node:key()
    local npkts = tonumber(node:get())
    print(ip.tostring(ip_bytes).." sent "..npkts.." packets")
    iter:next()
    node = iter:node()
end

🦋 String-key trie with cdata values 🦋

local trie = require("dnsjit.lib.trie").new("core_object_t*")
local obj1  -- assume this contains cdata of type core_object_t*
local node = trie:get_ins("obj1")
node:set(obj1)
node = trie:get_try("obj1")
assert(node:get() == obj1)

---

👑 DESCRIPTION 👑

so basically: this is a prefix-tree data structure that stores values indexed by strings or byte arrays, like IP addresses, for example. it's the main character of key-value storage, fr fr.

here's the tea tho — values of size up to sizeof(size_t) can be stored directly. anything bigger than that and you gotta use a pointer instead. no shortcuts, bestie. 💅

💜 Functions 💜

• Trie.new(ctype, binary, keylen) — creates a shiny new Trie that stores ctype values as data. by default, keys are handled as strings (yes queen, strings). want byte arrays instead? set binary to true. optionally you can pass keylen as a default keylen for binary keys — but for string keys, their string length is used by default. iconic behavior honestly.
• Trie:log() — returns the Log object so you can control logging for this instance or module. lowkey essential for debugging your life.
• Trie:clear() — clears the trie instance, aka makes it empty. we love a clean slate ✨
• Trie:weight() — returns the number of keys in the trie. it's the trie's vibe check, its total count, its whole deal.
• Trie:get_try(key, keylen) — searches the trie and returns nil on failure. no drama, just nil. 😭
• Trie:get_ins(key, keylen) — searches the trie and, if it fails, inserts an empty node (with value set to 0). it's the "if it's not there, we're making it there" energy. 🫶
• Trie:get_first() — returns the first node (minimum). smallest key first, always. ⭐
• Trie:iter() — returns a trie iterator. heads up bestie: it is only valid as long as the key-set remains unchanged. touch the keys and that iterator is gone, periodt.

---

🌈 SEE ALSO 🌈

dnsjit.lib.trie.node(3), dnsjit.lib.trie.iter(3) — go read these next, they're the supporting cast and they ate 💅

---

🌸 AUTHORS and CONTRIBUTORS 🌸

the legends behind this:

• Jerry Lundström (DNS-OARC)
• Tomáš Křížek (CZ.NIC)
• Petr Špaček (ISC)

maintained by DNS-OARC 👑

https://www.dns-oarc.net/

---

🐛 BUGS 🐛

got issues? got feature requests? don't suffer in silence, bestie:

https://codeberg.org/DNS-OARC/dnsjit/issues

questions or need help? they're literally right there:

admin@dns-oarc.net

no gatekeeping, no being mean, just send the message. 🍓

---

and that's the whole page, angel 💖 this was dnsjit version 1.5.1, sitting pretty as dnsjit.lib.trie(3). now go forth and index your byte arrays, you absolute icon 🧚✨