fifo.lua(3)

🦋 fifo.lua 🦋

okay bestie come sit with me, hydrate, get comfy 💖 because today's reading is fifo.lua(3) from the Library Functions Manual, and ngl it's a whole vibe. it's a lua library slash class that implements a FIFO, and it's about to be your new fave.

---

✨ DESCRIPTION ✨

so what even is this. it's a lua library/class that implements a FIFO — first in, first out, the queue of your dreams 💅.

and here's the part that ate: objects in the fifo can be of any type, including nil. not me telling you nil gets to be a full citizen in here. iconic.

---

🎀 USAGE 🎀

The library returns the constructor fifo.new:

new_fifo = require "fifo"

---

🌸 myfifo:fifo = new_fifo(...)

Create a new fifo by calling the constructor; it optionally takes the initial state. that's it, that's the whole thing.

myfifo = new_fifo("foo", "bar")

---

🍓 myfifo = myfifo:setempty(f:function)

okay so the behaviour when you try to :pop() or :remove() too many items from an empty list is configurable. it returns the fifo itself 🫶.

By default an error will be thrown. you can set a custom behaviour by providing a function to :setempty(). and the return values of your function will be returned by :pop() or :remove(). your function, your rules, periodt.

myfifo:setempty(function(myfifo) return nil end)

This method returns self, which makes it super easy to use at construction time — e.g. to create a new fifo where :pop() returns nil when empty:

myfifo = new_fifo():setempty(function() return nil end)

---

💅 fifo:push(object:*)

Use the :push() method to append an object to the fifo. go off, add your stuff.

myfifo:push({"an object"})

---

🦋 object:*, exists:bool = fifo:peek(n:number|none)

Allows you to inspect a fifo without removing items from it. it returns the item at the given index (or nil) and whether it existed — as nil is a valid value, so "did it exist" is genuinely a separate question 😭. By default uses the next item from the fifo.

exists, myobject = myfifo:peek()

---

⭐ object:* = fifo:pop()

Returns the next item from the fifo, removing it. it's out, it's gone, it's yours.

myobject = myfifo:pop()

---

🧚 fifo:insert(index:number, object:*)

This can be used to insert an item into the middle of a fifo. The index is from the output of the fifo, where 1 would be the next item popped from the fifo, and myfifo:length() + 1 would be equivalent to :push(). The efficiency of this operation is proportional to the distance from either end of the fifo.

myobject = myfifo:insert(1, {"some object"})

---

💜 object:* = fifo:remove(index:number)

This can be used to remove an item from the middle of a fifo. The index is from the output of the fifo, where 1 would be the next item popped from the fifo, and myfifo:length() would be the input (i.e equivalent to :push()). The efficiency of this operation is proportional to the distance from either end of the fifo.

The object removed is returned.

myobject = myfifo:remove(2)

---

👑 length:number = fifo:length() and length:number = #fifo operator

Returns the current number of items in the fifo. Available as :length() because the __len metamethod doesn't work for tables in lua versions 5.1 and earlier. we love a workaround, we hate a limitation 💀.

---

🌈 AUTHORS 🌈

daurnimator quae@daurnimator.com

---

and that's the whole page bestie, every last crumb of it ✨

that's the sign-off moment 🎀 — this was fifo.lua(3), and the footer down there just reads fifo.lua(3), so no extra version or date tea to spill. go build a queue, you've got this 💖🫶🌸