From 3af5dcf34d705cc52c1ffe5b85c2a90b5104e4c9 Mon Sep 17 00:00:00 2001
From: Zuhaitz Méndez Fernández de Aránguiz <zuhaitz@debian>
Date: Mon, 19 Jan 2026 22:18:33 +0000
Subject: Improve 'std/cuda.zc' and 'std/vec.zc' + iteration...

---
 docs/std/README.md |  3 ++
 docs/std/vec.md    | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 93 insertions(+)
 create mode 100644 docs/std/README.md
 create mode 100644 docs/std/vec.md

(limited to 'docs')

diff --git a/docs/std/README.md b/docs/std/README.md
new file mode 100644
index 0000000..8202192
--- /dev/null
+++ b/docs/std/README.md
@@ -0,0 +1,3 @@
+# Standard Library
+
+- [Vector (Vec)](./vec.md) - A growable dynamic array.
diff --git a/docs/std/vec.md b/docs/std/vec.md
new file mode 100644
index 0000000..a0422bb
--- /dev/null
+++ b/docs/std/vec.md
@@ -0,0 +1,90 @@
+# Standard Library: Vector (`std/vec.zc`)
+
+`Vec<T>` is a contiguous, growable array type. It is the standard dynamic array used in Zen-C.
+
+## Overview
+
+- **Generic**: Works with any type `T`.
+- **Dynamic**: Automatically resizes as elements are added.
+- **Safe**: Bounds checks on access (panics on failure).
+- **RAII**: Automatically frees memory when it goes out of scope (implements `Drop`).
+
+## Usage
+
+```zc
+import "std/vec.zc"
+
+fn main() {
+    var v = Vec<int>::new();
+    v.push(10);
+    v.push(20);
+    
+    // Iteration
+    for x in &v {
+        println "{(*x)}";
+    }
+} // v is freed automatically here
+```
+
+## Struct Definition
+
+```zc
+struct Vec<T> {
+    data: T*;
+    len: usize;
+    cap: usize;
+}
+```
+
+## Methods
+
+### Construction
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| **new** | `Vec<T>::new() -> Vec<T>` | Creates a new, empty vector. Does not allocate memory until the first push. |
+| **with_capacity** | `Vec<T>::with_capacity(cap: usize) -> Vec<T>` | Creates a new vector with an initial capacity of `cap`. Useful for optimization if you know the number of elements in advance. |
+
+### Modification
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| **push** | `push(self, item: T)` | Appends an element to the back. Panics if allocation fails. |
+| **pop** | `pop(self) -> T` | Removes the last element and returns it. Panics if empty. |
+| **pop_opt** | `pop_opt(self) -> Option<T>` | Removes the last element and returns `Some(val)`. Returns `None` if empty. Safe usage. |
+| **insert** | `insert(self, idx: usize, item: T)` | Inserts an element at `idx`. Shifts elements right. Panics if `idx > len`. |
+| **remove** | `remove(self, idx: usize) -> T` | Removes and returns the element at `idx`. Shifts elements left. Panics if `idx >= len`. |
+| **clear** | `clear(self)` | Removes all values. Has no effect on allocated capacity. |
+| **reverse** | `reverse(self)` | Reverses the order of elements in place. |
+
+### Access
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| **get** | `get(self, idx: usize) -> T` | Returns a copy of the element at `idx`. Panics if out of bounds. |
+| **set** | `set(self, idx: usize, item: T)` | Overwrites the element at `idx`. Panics if out of bounds. |
+| **first** | `first(self) -> T` | Returns a copy of the first element. Panics if empty. |
+| **last** | `last(self) -> T` | Returns a copy of the last element. Panics if empty. |
+
+### Utility
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| **length** | `length(self) -> usize` | Returns the number of elements. |
+| **is_empty** | `is_empty(self) -> bool` | Returns `true` if the vector contains no elements. |
+| **contains** | `contains(self, item: T) -> bool` | Returns `true` if vector contains an element equal to `item` (byte-wise). |
+| **clone** | `clone(self) -> Vec<T>` | Returns a new vector with a deep copy of the data. |
+
+### Iteration
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| **iterator** | `iterator(self) -> VecIter<T>` | Returns an iterator yielding copies. Used by `for x in v`. |
+| **iter_ref** | `iter_ref(self) -> VecIterRef<T>` | Returns an iterator yielding pointers. Used by `for x in &v` (sugar) or `for x in v.iter_ref()`. Allows in-place mod. |
+
+## Memory Management
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| **Free** | `free(self)` | Manually frees memory. Safe to call multiple times. |
+| **Trait** | `impl Drop for Vec` | Automatically calls `free()` when `Vec` goes out of scope. |
-- 
cgit v1.2.3