Stack(3)

💅 Stack(3) — the OCaml Stack module, explained bestie-style 🥞

okay so this is <pink>Stack</pink>, from the <purple>OCaml library</purple> — the manpage you're reading rn is literally called Stack(3). and honestly? she's iconic, she's simple, she's giving main character energy. let's get into it ✨

---

🎀 NAME 🎀

Stack — last-in first-out stacks. periodt. 💅

🌸 Module 🌸

Module Stack. yes bestie that's the whole thing. the module is the module 🫶

💖 Documentation 💖

Module Stack

that's a sig end situation — like, : sig end — and iykyk, it's just the signature wrapper, don't overthink it 💀

🦋 so what IS it 🦋

Last-in first-out stacks. fr fr.

This module implements stacks (LIFOs), with in-place modification. so like, it literally mutates the stack in place — no cap, that's the whole vibe 👑

⚠️ Alert <hotpink>unsynchronized_access</hotpink>. Unsynchronized accesses to stacks are a programming error. like, straight up a bug on your end, bestie 😭

🌈 Unsynchronized accesses — read this part, seriously 🌈

Unsynchronized accesses to a stack may lead to an invalid queue state. Thus, concurrent accesses to stacks must be synchronized (for instance with a Mutex.t).

💀 yeah. "invalid queue state" is not a vibe. lock your stacks or suffer. use a Mutex.t, she's right there.

---

✨ the types and the crew ✨

• type !'a t — the type of stacks containing elements of type 'a. that ! is doing a little something (it's there, we keep it, we love her) 🎀
• exception Empty — raised when Stack.pop or Stack.top is applied to an empty stack. she WILL yell at you. 🙈

---

🔥 the functions 🔥

🌟 the basics 🌟

• val create : unit -> 'a t — return a new stack, initially empty. fresh out the box, clean slate, new era 💖
• val push : 'a -> 'a t -> unit — push x s adds the element x at the top of stack s. she's on top, as she deserves 👑
• val pop : 'a t -> 'a — pop s removes and returns the topmost element in stack s, or raises Stack.Empty if the stack is empty. take her off the top and hand her to you — but if there's nothing there? Stack.Empty, sorry bestie 😭
• val pop_opt : 'a t -> 'a option — pop_opt s removes and returns the topmost element in stack s, or returns None if the stack is empty. same energy as pop but the chill non-dramatic version 🫶 Since 4.08
• val drop : 'a t -> unit — drop s removes the topmost element in stack s, or raises Stack.Empty if the stack is empty. no return value, she just vanishes. ghosting, but legal 💅 Since 5.1
• val top : 'a t -> 'a — top s returns the topmost element in stack s, or raises Stack.Empty if the stack is empty. peek only, no removal — look but don't touch energy ✨
• val top_opt : 'a t -> 'a option — top_opt s returns the topmost element in stack s, or None if the stack is empty. peek, but make it option 🌸 Since 4.08
• val clear : 'a t -> unit — discard all elements from a stack. block button. delete. unfollow. she's empty now 🧹
• val copy : 'a t -> 'a t — return a copy of the given stack. twin flame behavior, but like, a duplicate stack 🦋
• val is_empty : 'a t -> bool — return true if the given stack is empty, false otherwise. vibe check on the emptiness 🌈
• val length : 'a t -> int — return the number of elements in a stack. Time complexity O(1) — yes bestie, constant time, we stay efficient 🔥

🌼 the iteration girlies 🌼

• val iter : ('a -> unit) -> 'a t -> unit — iter f s applies f in turn to all elements of s, from the element at the top of the stack to the element at the bottom of the stack. The stack itself is unchanged. top to bottom, one by one, no touching the originals 💖
• val fold : ('acc -> 'a -> 'acc) -> 'acc -> 'a t -> 'acc — fold f accu s is (f (... (f (f accu x1) x2) ...) xn) where x1 is the top of the stack, x2 the second element, and xn the bottom element. The stack is unchanged. yes she's got that nesting thing going on, it's giving recursion core, we love her ✨ Since 4.03

🎀 Stacks and Sequences 🎀

• val to_seq : 'a t -> 'a Seq.t — iterate on the stack, top to bottom. It is safe to modify the stack during iteration. ooooh heads up bestie, you CAN modify mid-iteration here, that's the special sauce 🌟 Since 4.07
• val add_seq : 'a t -> 'a Seq.t -> unit — add the elements from the sequence on the top of the stack. dumping the whole seq on top, topping her off 🍓 Since 4.07
• val of_seq : 'a Seq.t -> 'a t — create a stack from the sequence. seq goes in, stack comes out, no cap 💜 Since 4.07

---

💅 tiny reminder before you go: this whole module does in-place modification, so if you're doing concurrent accesses, synchronize them (like with a Mutex.t) or you're gonna have a bad time. the alert said it, we said it, it's real.

---

🌸 that's the whole page bestie! no notes, she's complete, every function and Since tag accounted for 💖

OCamldoc — 2026-06-22 — Stack(3) 🎀 and yes, that's the version + date sign-off, cute right? 🫶