Variables

content/docs/logic/variables.mdx

@@ -0,0 +1,53 @@
+---
+title: Variables
+description: Local state management with type inference and explicit mutability.
+icon: Variable
+---
+
+In Mist, variables follow the language-wide `type name` convention. For local scope, the `var` keyword provides type inference, while explicit types can be used for clarity or strictness.
+
+## Basic Declaration
+
+Variables are declared using the `var` keyword for automatic type inference. Like Rust, variables are immutable by default.
+
+```java
+var message = "Hello Mist"; // Inferred as str*
+var count = 42;             // Inferred as i32
+```
+
+## Mutability
+
+To allow a variable to be reassigned, use the `mut` modifier after the `var` keyword or the explicit type.
+
+```rust
+var mut score = 0;
+score = 100;
+
+f32 mut price = 19.99;
+price = 14.99;
+```
+
+## Explicit Typing
+
+While `var` handles inference, you can explicitly define the type before the identifier. This is often used for clarity in complex logic or when the specific numeric width (e.g., `u8` vs `i32`) matters.
+
+```rust
+u64 large_id = 1000234;
+bool is_active = true;
+```
+
+## Constants
+
+Constants are immutable values that are evaluated at compile time. They require an explicit type and follow the `const` keyword.
+
+```rust
+const i32 MAX_RETRIES = 5;
+const str* VERSION = "1.0.4";
+```
+
+## Key Characteristics
+
+- **Predictable Order**: Whether using `var` or an explicit type, the name of the variable always follows the "source" of its data.
+- **Safety First**: Immutability by default prevents accidental state changes, mapping directly to Rust's memory safety model.
+- **Zero-Cost Inference**: Type inference is handled entirely at compile time, ensuring there is no runtime performance penalty.
+- **Shadowing**: Mist supports variable shadowing, allowing you to reuse variable names within the same scope to transform data without changing mutability.