Pointers and refrences

content/docs/pointers-references.mdx

@@ -0,0 +1,39 @@
+---
+title: Pointers & References
+description: Explicit memory access with C-style ergonomics and Rust-native safety.
+icon: MousePointer2
+---
+
+Mist simplifies Rust’s reference system by using a pointer-style syntax. While the symbols look like C-style pointers, they adhere strictly to Rust’s ownership and borrowing rules.
+
+## Basic Syntax
+
+References are defined by placing a `*` after the type. By default, pointers are immutable (shared). To allow modification of the underlying data, use the `mut*` modifier.
+
+```cpp
+void increment(i32 mut* value, i32* limit) {
+    if (value < limit) {
+        value = value + 1;
+    }
+}
+
+```
+
+## Lifetimes
+
+Lifetimes are attached directly to the type before the pointer symbol. This maintains a clean visual flow where the "type-contract" (identity, duration, and mutability) is read from left to right.
+
+```cpp
+public struct Inspector<'a> {
+    public str'a* target,
+    public u32'a mut* counter,
+}
+
+```
+
+## Key Characteristics
+
+- **Explicit Intent:** The `mut*` syntax clearly distinguishes between a reference that can read and one that can write, mapping 1:1 to Rust's `&` and `&mut`.
+- **Visual Consistency:** Lifetimes (`'a`) and mutability modifiers are integrated into the type declaration, keeping function signatures and struct fields compact.
+- **Safety Guaranteed:** Despite the "pointer" appearance, the Mist compiler enforces Rust’s borrow checker. You cannot have multiple `mut*` references to the same data, and references cannot outlive their owners.
+- **Zero Overhead:** Mist pointers are "thin" or "fat" exactly like Rust references; they carry no extra runtime metadata and compile to identical machine code.