EMILUA(3em)

🌸 EMILUA(3em) — emilua, section 3em, the Emilua reference 🌸

okay so bestie, welcome to emilua(3em) — this is the page for byte_span, and honestly? it's iconic. it's Emilua's Lua execution engine territory, so grab a snack and let's get into it 💅

✨ NAME ✨

Emilua — Lua execution engine. that's the whole name section, short and slay 🎀

🦋 DESCRIPTION 🦋

💡 Note: byte_span is a global, so you don't need to require() it. it's just there for you, like a good bestie 🫶

so what even is it? it's a span of bytes. and in Emilua, these are used as network buffers. periodt. ✨

👑 Note: plugin authors, this one's for you This class is intended for network buffers in a proactor-based network API — and by that we mean true asynchronous IO. a NIC could literally be writing to this memory region while the program is running 😭 like, that's a real thing that can happen. the effect is the same as another thread writing to the same memory region. no cap. if you're writing state machines, do not construct the state machine on top of the memory region that a byte_span points to. it is not safe to store state here, because buggy Lua applications could mutate this area in a racy way 💀 only use the memory region as the result of operations. that's it. that's the rule. a future Emilua release could introduce read-write locks, but as of right now I'm unconvinced of their advantages here 🤷‍♀️

and the lore? it's modeled after Golang's slices — http://blog.golang.org/2011/01/go-slices-usage-and-internals.html — however, the plot twist: 1-indexed access is used 😌 as it should be, lbr.

---

💖 FUNCTIONS 💖

• new(length: integer[, capacity: integer]) → byte_span — the constructor, the main character 👑 when you leave out the capacity argument, it just defaults to the length you specified. easy.
• with_zeros(length: integer[, capacity: integer]) → byte_span — also a constructor 💅 it initializes capacity bytes with zero (the NUL byte). and if length and capacity are different, then it goes beyond the first length bytes to initialize the whole memory region pointed to by the returned byte_span — yes, the whole thing, she's thorough 🌈

and if length and capacity are equal? then it's identical to new(length):fill(0). same vibe, same result.

• sub(self[, start: integer, end: integer]) → byte_span — returns a brand new byte_span that points to a slice of the same memory region. sharing is caring 🫶

start and end are optional, obvi — they default to 1 and the byte_span's length respectively.

fun fact: we can grow a byte_span to its capacity by slicing it again. glow-up behavior, honestly ✨

⚠️ invalid ranges — like start below 1, a byte_span running beyond its capacity, negative indexes, the usual suspects — will raise EINVAL. no exceptions. well, except that one.

• first(self, count: integer) → byte_span — returns a new byte_span that points to the first count bytes of the same memory region. front of the line energy 🎀
• last(self, count: integer) → byte_span — returns a new byte_span that points to the last count bytes of the same memory region. saving the best for last, literally 💅
• copy(self, src: byte_span|string) → integer — copies src into self 🔥 and it returns the number of elements copied, so you always know what happened.

copying between slices of different lengths is supported — it'll copy only up to the smaller number of elements. and better yet, it can handle source and destination spans that share the same underlying memory, handling overlapping spans correctly 👏 like, overlap-aware. we love a considerate function.

• append() → byte_span — two overloads, bestie, keep up 😭

function append(self, ...: byte_span|string|nil) -> byte_span (1)
function append(...: byte_span|string|nil) -> byte_span       (2)

returns a new byte_span by appending the trailing arguments into self. and here's the iykyk part: if self's capacity is enough to hold all the data, the underlying memory is modified in place. otherwise, the returned byte_span will point to newly allocated memory[1] 🧚

for the second overload — that's the non-member function — a new byte span is created from scratch. fresh start, new me 🌸

• fill(self, byte: integer) → byte_span — as in C's memset(), it fills the memory area pointed to by self with byte. and it returns self, because of course it does, she's generous 💜

---

🌈 FUNCTIONS (STRING ALGORITHMS) 🌈

quick vibe check before we start: these functions operate in terms of octets/bytes — kinda like an 8-bit ASCII situation — and they have no concept of UTF-8 encoding. so don't come here expecting unicode magic, she's byte-pilled and that's the tea 🍓

• starts_with(self, prefix: string|byte_span) → boolean — returns whether self begins with prefix. yes/no, that's the whole gig.
• ends_with(self, suffix: string|byte_span) → boolean — returns whether self ends with suffix. every story needs a good ending 🎀
• find(self, tgt: string|byte_span[, start: integer]) → integer|nil — finds the first substring equal to tgt and returns its index, or nil if it's not found. no luck? nil. bye 👋
• rfind(self, tgt: string|byte_span[, end_: integer]) → integer|nil — finds the last substring equal to tgt and returns its index, or nil if not found. reverse search, reverse card 🔄
• find_first_of(self, strlist: string|byte_span[, start: integer]) → integer|nil — finds the first octet equal to any of the octets within strlist and returns its index, or nil if not found. it's a whole cast of characters and she's looking for the first one on set ✨
• find_last_of(self, strlist: string|byte_span[, end_: integer]) → integer|nil — finds the last octet equal to any of the octets within strlist and returns its index, or nil if not found. last one to leave the party 🎉
• find_first_not_of(self, strlist: string|byte_span[, start: integer]) → integer|nil — finds the first octet not equal to any of the octets within strlist and returns its index, or nil if not found. the not-like-the-other-girls search 💅
• find_last_not_of(self, strlist: string|byte_span[, end: integer]) → integer|nil — finds the last octet not equal to any of the octets within strlist and returns its index, or nil if not found. same energy, other end 🦋
• trimmed(self[, lws: string|byte_span = " \f\n\r\t\v"]) → byte_span — returns a slice from self that doesn't start nor end with any octet from lws. the default lws is " \f\n\r\t\v" — like, space, form feed, newline, carriage return, tab and vertical tab. she's neat, she's tidy, she's trimmed 🧚
• inplace_lower(self) — converts every upper ASCII character from self to its lower version. lowercase era 😌
• inplace_upper(self) — converts every lower ASCII character from self to its upper version. SHOUTING ERA 📣🔥

FUNCTIONS (PRIMITIVE TYPES SERIALIZATION)

okay bestie, these ones are the byte-nerd girlies 💅 they operate in terms of bytes, and they're endianness-aware (yes they know the difference, they're not messy). Hand them a byte_span of the wrong size and they will throw EINVAL at you, no cap. The cute part? Data doesn't need to be aligned ✨ lowkey iconic.

the unsigned getters 🍼

• get_u16be(self) → integer — reads self (has to be 2 bytes long, she checks) as an unsigned 16-bit integer in big endian order and gives you the result 🫶
• get_u16le(self) → integer — same 2-byte requirement, but this time it's an unsigned 16-bit integer in little endian order, and you get the result back
• get_u24be(self) → integer — self (3 bytes long, periodt) interpreted as an unsigned 24-bit integer, big endian order, returns the result ✨
• get_u24le(self) → integer — 3 bytes of self, unsigned 24-bit integer, little endian order, result returned
• get_u32be(self) → integer — self (4 bytes long, exactly) as an unsigned 32-bit integer, big endian order, and boom, the result 🌸
• get_u32le(self) → integer — 4 bytes long, unsigned 32-bit integer, little endian order, result returned
• get_u40be(self) → integer — 5 bytes long, unsigned 40-bit integer, big endian order, result returned 🦋
• get_u40le(self) → integer — 5 bytes long, unsigned 40-bit integer, little endian order, result returned
• get_u48be(self) → integer — 6 bytes long, unsigned 48-bit integer, big endian order, result returned 💜
• get_u48le(self) → integer — 6 bytes long, unsigned 48-bit integer, little endian order, result returned

the signed getters 😭

• get_i8(self) → integer — self (must be 1 byte long) interpreted as a signed 8-bit integer, result returned

📌 note — get_u8() doesn’t exist as you can just index instead.

• get_i16be(self) → integer — 2 bytes long, signed 16-bit integer, big endian order, result returned
• get_i16le(self) → integer — 2 bytes long, signed 16-bit integer, little endian order, result returned
• get_i24be(self) → integer — 3 bytes long, signed 24-bit integer, big endian order, result returned
• get_i24le(self) → integer — 3 bytes long, signed 24-bit integer, little endian order, result returned
• get_i32be(self) → integer — 4 bytes long, signed 32-bit integer, big endian order, result returned 🔥
• get_i32le(self) → integer — 4 bytes long, signed 32-bit integer, little endian order, result returned
• get_i40be(self) → integer — 5 bytes long, signed 40-bit integer, big endian order, result returned
• get_i40le(self) → integer — 5 bytes long, signed 40-bit integer, little endian order, result returned
• get_i48be(self) → integer — 6 bytes long, signed 48-bit integer, big endian order, result returned
• get_i48le(self) → integer — 6 bytes long, signed 48-bit integer, little endian order, result returned

the float getters 🧚

• get_f32be(self) → number — self (4 bytes long) read as a 32-bit floating point number, big endian order, result returned ✨
• get_f32le(self) → number — 4 bytes long, 32-bit floating point number, little endian order, result returned
• get_f64be(self) → number — 8 bytes long, 64-bit floating point number, big endian order, result returned 💖
• get_f64le(self) → number — 8 bytes long, 64-bit floating point number, little endian order, result returned

---

the unsigned setters 💅

bestie, these ones write into the stored byte sequence instead of reading it. same energy, opposite direction.

• set_u16be(self, n: integer) — sets the stored byte sequence (must be 2 bytes long) to represent the unsigned 16-bit integer n, big endian order 🫶
• set_u16le(self, n: integer) — 2 bytes long, unsigned 16-bit integer n, little endian order
• set_u24be(self, n: integer) — 3 bytes long, unsigned 24-bit integer n, big endian order ✨
• set_u24le(self, n: integer) — 3 bytes long, unsigned 24-bit integer n, little endian order
• set_u32be(self, n: integer) — 4 bytes long, unsigned 32-bit integer n, big endian order 🌸
• set_u32le(self, n: integer) — 4 bytes long, unsigned 32-bit integer n, little endian order
• set_u40be(self, n: integer) — 5 bytes long, unsigned 40-bit integer n, big endian order 🦋
• set_u40le(self, n: integer) — 5 bytes long, unsigned 40-bit integer n, little endian order
• set_u48be(self, n: integer) — 6 bytes long, unsigned 48-bit integer n, big endian order 💜
• set_u48le(self, n: integer) — 6 bytes long, unsigned 48-bit integer n, little endian order

the signed setters 🎀

• set_i8(self, n: integer) — sets the stored byte sequence (must be 1 bytes long) to represent the signed byte n

📌 note — set_u8() doesn’t exist as you can just index instead.

• set_i16be(self, n: integer) — 2 bytes long, signed 16-bit integer n, big endian order
• set_i16le(self, n: integer) — 2 bytes long, signed 16-bit integer n, little endian order
• set_i24be(self, n: integer) — 3 bytes long, signed 24-bit integer n, big endian order
• set_i24le(self, n: integer) — 3 bytes long, signed 24-bit integer n, little endian order
• set_i32be(self, n: integer) — 4 bytes long, signed 32-bit integer n, big endian order 🔥
• set_i32le(self, n: integer) — 4 bytes long, signed 32-bit integer n, little endian order
• set_i40be(self, n: integer) — 5 bytes long, signed 40-bit integer n, big endian order
• set_i40le(self, n: integer) — 5 bytes long, signed 40-bit integer n, little endian order
• set_i48be(self, n: integer) — 6 bytes long, signed 48-bit integer n, big endian order
• set_i48le(self, n: integer) — 6 bytes long, signed 48-bit integer n, little endian order

the float setters 🌈

• set_f32be(self, n: number) — sets the stored byte sequence (must be 4 bytes long) to represent the 32-bit floating point number n, big endian order ✨
• set_f32le(self, n: number) — 4 bytes long, 32-bit floating point number n, little endian order
• set_f64be(self, n: number) — 8 bytes long, 64-bit floating point number n, big endian order 💖
• set_f64le(self, n: number) — 8 bytes long, 64-bit floating point number n, little endian order

---

✨ PROPERTIES ✨

capacity : integer

the capacity. that's it. that's the whole property 💅 she said "I contain multitudes but today I'm just gonna tell you how much I can hold".

---

🦋 METAMETHODS 🦋

she's got the full set, bestie, the whole personality:

• __tostring()
• __len()
• __index()
• __newindex()
• __eq()

📌 note — you can index the spans by numerical valued keys, and the numerical (ASCII) value for the underlying byte will be returned (or assigned on __newindex()). iykyk 🫶

---

🌸 NOTES 🌸

• [1] Allocation strategy (the new byte_span's capacity) is left unspecified and may change among Emilua releases. so don't build your whole life plan around it, fr fr 💀

---

and that's the whole page, bestie!! 🎀 mwah 💋

this was Emilua 0.12.1-nixpkgs1, dated 1980-01-01, and yeah — it's EMILUA(3em), the one and only 👑