🦀 Rust Algorithms & Data Structures

Rust Algorithms & Data Structures is an engineering laboratory and low-level systems showcase featuring fundamental computer science abstractions built from scratch without standard library collections or third-party crates. Guided by the core tenets of Single Ownership, Fearless Concurrency, and Zero-Cost Abstractions, each tool demonstrates how to write robust, high-performance systems code.

Rather than relying on mock visualizers, this suite executes authentic Rust code directly inside an online interactive terminal connected to the official compiler toolchain. Each module provides a dual-panel IDE layout: architectural decisions, memory layout diagrams, and mathematical complexity proofs on the left, alongside an asynchronous compiler and live terminal output on the right.

🌐 Launch Interactive Rust Suite

---

🎯 Curated Modules & Technical Capabilities

#	Module	Core Rust Idiom / Pattern	Systems & Algorithmic Problem Solved
01	Doubly Linked List	NonNull<T>, Raw Pointers & Custom Drop	Memory-safe bidirectional traversal bypassing Borrow Checker limitations with $O(1)$ stack cleanup.
02	Lock-Free Queue	AtomicPtr, CAS (compare_exchange) & Acquire-Release	High-throughput non-blocking MPMC queue based on the Michael-Scott algorithm with zero mutex contention.
03	Custom HashMap	Linear Probing, Tombstone Pattern & Load Factor	Cache-friendly open addressing table eliminating heap fragmentation and cache misses via $O(1)$ lookups.
04	Self-Balancing AVL Tree	Subtree Rotations & Option::take() Ownership	Preventing $O(N)$ binary search tree degradation through strict height invariants ($
05	Zero-Dependency JSON Parser	Recursive Descent, Lexical Span & Tagged Enums	RFC 8259 grammar parsing with compiler-grade positional diagnostics and pretty-printing without Serde.
06	High-Performance LRU Cache	Hybrid HashMap + Doubly Linked List via NonNull	Constant-time $O(1)$ cache lookups, temporal access promotion (MRU), and deterministic eviction (LRU).

---

🏗️ Architectural Overview & Execution Pipeline

                               Browser Client (GitHub Pages)
                                             │ 
                           ┌─────────────────┴─────────────────┐
                           ▼                                   ▼
                Left: Architectural Spec             Right: Live Cargo Terminal
              ┌─────────────────────────┐         ┌──────────────────────────┐
              │ • Memory Layout Specs   │         │ • Interactive Terminal   │
              │ • Cache Locality & SIMD │         │ • Compilation Log Stream │
              │ • Standalone Copy-Paste │         │ • Real-time stdout/stderr│
              │ • Idiomatic Rust Source │         │ • Clean ANSI Stripping   │
              └─────────────────────────┘         └────────────┬─────────────┘
                                                               │
                                                               ▼
                                                  ┌──────────────────────────┐
                                                  │ rustc / Cargo Playground │
                                                  │(Rust 2021  Stable Engine)│
                                                  └──────────────────────────┘

Zero-Cost Abstractions: Every data structure is handwritten from bare primitives (NonNull, atomic types, contiguous vectors), demonstrating control over heap allocation and layout.

Safe Encapsulation: Low-level pointer manipulation is strictly isolated behind safe public APIs, upholding Rust's type guarantees across external boundaries.

Non-Blocking Systems Concurrency: The concurrent queue leverages explicit CPU memory orderings (Acquire, Release, Relaxed) to coordinate threads across hardware cores without OS kernel context switches.

📂 Repository Blueprint

algorithms-and-data-structures-rust/
├── index.html                       # Central hub connecting all 6 interactive modules
├── assets/
│   ├── favicon.svg                  # High-definition Rust gear vector badge
│   ├── preview-banner.svg           # Social preview and repository banner
│   ├── css/
│   │   └── style.css                # Global styling, IDE scrollbars, and terminal glow
│   └── js/
│       └── runner.js                # Universal execution runner and playground API bridge
└── modules/
    ├── 01-custom-linked-list/
    │   ├── index.html               # Dual-pane lab (Architecture + Terminal)
    │   └── src.rs                   # Doubly linked list with NonNull and Drop trait
    ├── 02-lock-free-queue/
    │   ├── index.html               # Dual-pane lab
    │   └── src.rs                   # Lock-free MPMC queue with atomic CAS
    ├── 03-custom-hashmap/
    │   ├── index.html               # Dual-pane lab
    │   └── src.rs                   # Open addressing hash table with tombstones
    ├── 04-avl-tree/
    │   ├── index.html               # Dual-pane lab
    │   └── src.rs                   # Self-balancing AVL tree with ASCII visualizer
    ├── 05-json-parser/
    │   ├── index.html               # Dual-pane lab
    │   └── src.rs                   # Lexer and recursive descent parser for JSON
    └── 06-lru-cache/
        ├── index.html               # Dual-pane lab
        └── src.rs                   # Hybrid hash map + linked list LRU cache

🚀 Getting Started

Option 1: Run Locally via Web (Interactive Suite)

Clone the repository and start any static HTTP server:

# Clone the repository
git clone [https://github.com/bryanwessantana/algorithms-and-data-structures-rust.git](https://github.com/bryanwessantana/algorithms-and-data-structures-rust.git)

# Navigate to the project root
cd algorithms-and-data-structures-rust

# Start a local static HTTP server
python3 -m http.server 3000

Open your browser and navigate to http://localhost:3000.

Option 2: Run Any Module Directly in Your Local CLI (Rust Toolchain)

Each module contains a standalone, zero-dependency src.rs file ready for compilation with rustc:

# Example: Compile and run the Doubly Linked List
rustc modules/01-custom-linked-list/src.rs -o linked_list && ./linked_list

# Example: Compile and run the Lock-Free Concurrent Queue
rustc modules/02-lock-free-queue/src.rs -o lock_free_queue && ./lock_free_queue

# Example: Compile and run the Custom HashMap
rustc modules/03-custom-hashmap/src.rs -o custom_hashmap && ./custom_hashmap

# Example: Compile and run the AVL Tree
rustc modules/04-avl-tree/src.rs -o avl_tree && ./avl_tree

# Example: Compile and run the JSON Parser
rustc modules/05-json-parser/src.rs -o json_parser && ./json_parser

# Example: Compile and run the LRU Cache
rustc modules/06-lru-cache/src.rs -o lru_cache && ./lru_cache

📄 License & Open-Source Use

This project is open-source and available under the MIT License. You are free to inspect, fork, and embed these algorithms into your own systems projects.