From 8945e4fc90e7611d6f86218c5edc5fe0d343b239 Mon Sep 17 00:00:00 2001
From: Klesti Selimaj <klesti.selimay@icloud.com>
Date: Tue, 12 May 2026 03:10:18 +0200
Subject: [PATCH] Pointers and refrences

---
 content/docs/pointers-references.mdx | 39 ++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)
 create mode 100644 content/docs/pointers-references.mdx

diff --git a/content/docs/pointers-references.mdx b/content/docs/pointers-references.mdx
new file mode 100644
index 0000000..9a93fd5
--- /dev/null
+++ b/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.