From 98623f2fdd63232edf0ebab1b9680cf4e33e6f10 Mon Sep 17 00:00:00 2001
From: Zuhaitz Méndez Fernández de Aránguiz <zuhaitz@debian>
Date: Fri, 23 Jan 2026 01:54:51 +0000
Subject: More docs, and a few improvements for the standard library

---
 docs/std/queue.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 docs/std/queue.md

(limited to 'docs/std/queue.md')

diff --git a/docs/std/queue.md b/docs/std/queue.md
new file mode 100644
index 0000000..d463f15
--- /dev/null
+++ b/docs/std/queue.md
@@ -0,0 +1,74 @@
+# Standard Library: Queue (`std/queue.zc`)
+
+`Queue<T>` is a generic First-In-First-Out (FIFO) queue implemented as a **Ring Buffer (Circular Buffer)**.
+
+## Usage
+
+```zc
+import "std/queue.zc"
+
+fn main() {
+    var q = Queue<int>::new();
+    
+    q.push(1);
+    q.push(2);
+    q.push(3);
+    
+    // Pop returns an Option<T>
+    if (q.pop().is_some()) {
+        println "Popped: {q.pop().unwrap()}"; // 1
+    }
+}
+```
+
+## Implementation Details
+
+- **Ring Buffer**: Uses a circular buffer with `head` and `tail` indices.
+- **Performance**:
+    - `push`: **Amortized O(1)** (resizes when full).
+    - `pop`: **O(1)** (advances head index).
+    - `clone`: **O(N)**.
+- **Safety**: Safe handling of memory wrapping and resizing.
+
+## Structure
+
+```zc
+struct Queue<T> {
+    data: T*;
+    cap: usize;
+    head: usize;
+    tail: usize;
+    count: usize;
+}
+```
+
+## Methods
+
+### Construction
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| **new** | `Queue<T>::new() -> Queue<T>` | Creates a new, empty queue. |
+| **clone** | `clone(self) -> Queue<T>` | Creates a deep copy of the queue. |
+
+### Modification
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| **push** | `push(self, value: T)` | Adds an element to the back of the queue. |
+| **pop** | `pop(self) -> Option<T>` | Removes and returns the element at the front. Returns `None` if empty. |
+| **clear** | `clear(self)` | Removes all items from the queue. |
+
+### Access / Query
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| **length** | `length(self) -> usize` | Returns the number of items. |
+| **is_empty** | `is_empty(self) -> bool` | Returns `true` if the queue is empty. |
+
+### Memory Management
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| **free** | `free(self)` | Frees the internal buffer. |
+| **Trait** | `impl Drop for Queue` | Automatically calls `free()` when out of scope. |
-- 
cgit v1.2.3