diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/std/README.md | 3 | ||||
| -rw-r--r-- | docs/std/vec.md | 90 |
2 files changed, 93 insertions, 0 deletions
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. | |