Personal notes on engineering, systems, and software. Zola 2026-06-12T00:00:00+00:00 https://blog.sheerluck.dev/atom.xml 2026-06-12T00:00:00+00:00 2026-06-12T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/learn-rust-concurrency-by-building-a-thread-pool/ <p>In this post, we are going to learn about concurrency in Rust. We will learn about OS threads, message passing with channels, shared mutable state with <code>Arc&lt;Mutex&lt;T&gt;&gt;</code>, and graceful shutdown. Once we cover all the concepts, we will build a <strong>Thread Pool from Scratch</strong>, a fixed number of worker threads, a job queue behind <code>Arc&lt;Mutex&lt;&gt;&gt;</code>, an <code>mpsc</code> channel for dispatching tasks, graceful shutdown that processes remaining queued jobs before exiting, and backpressure when the queue is full. I am really excited for this project and I hope you are too. I won't go too deep in theory, just practical and we will build our knowledge of these concepts over time with more articles.</p> <p>The only prerequisite is that you have read the previous articles in this series, as I will assume you know ownership, borrowing, structs, enums, pattern matching, error handling, generics, traits, lifetimes, HashMap, iterators, closures, and smart pointers.</p> <p>In the last article, we learned about <code>Rc</code> and <code>RefCell</code> for shared mutable state in single-threaded code. I teased that the smart pointer family has one more member: <code>Arc&lt;T&gt;</code>, the atomic reference counter for multi-threaded code. Today we will cover <code>Arc</code> together with <code>Mutex</code> and concurrency primitives, and we will build a thread pool that puts all of it to work.</p> <p>Get the source code from <a rel="external" href="https://github.com/MrSheerluck/threadpool">here</a></p> <h2 id="what-is-a-thread-pool">What Is a Thread Pool</h2> <p>Think of a restaurant kitchen. You have a fixed number of chefs. Orders come in, and each chef picks up the next available order, cooks it, and goes back to wait for the next one. You do not hire a new chef for every order and fire them afterwards, that would be wasteful. You also do not let the order queue grow infinitely, if the kitchen is too backed up, you tell the front of house to wait before sending more orders.</p> <p>A thread pool is the same idea. You spawn a fixed number of worker threads once, and they live for the lifetime of the pool. Jobs are sent to the pool through a channel. Idle workers receive jobs from the shared receiver. When the pool shuts down, workers continue processing queued jobs until the channel becomes empty and disconnected, then exit cleanly. If the queue is full, the sender blocks until there is space.</p> <h2 id="spawning-threads">Spawning Threads</h2> <p>Let's start with the basics. Create a new project:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> new threadpool</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> threadpool</span></span></code></pre> <p>Open <code>src/main.rs</code> and replace everything with:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span>thread</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">time</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Duration</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> handle</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> thread</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">||</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> i</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;">..=</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;spawned thread: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> i</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> thread</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">sleep</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Duration</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_millis</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">100</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> i</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;">..=</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;main thread: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> i</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> thread</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">sleep</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Duration</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_millis</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">150</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> handle</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Run it:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> run</span></span></code></pre> <p>You will see output from both threads interleaved. Something like:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">main</span><span style="color: #A6E3A1;"> thread:</span><span style="color: #FAB387;"> 1</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">spawned</span><span style="color: #A6E3A1;"> thread:</span><span style="color: #FAB387;"> 1</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">spawned</span><span style="color: #A6E3A1;"> thread:</span><span style="color: #FAB387;"> 2</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">main</span><span style="color: #A6E3A1;"> thread:</span><span style="color: #FAB387;"> 2</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">spawned</span><span style="color: #A6E3A1;"> thread:</span><span style="color: #FAB387;"> 3</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">main</span><span style="color: #A6E3A1;"> thread:</span><span style="color: #FAB387;"> 3</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">spawned</span><span style="color: #A6E3A1;"> thread:</span><span style="color: #FAB387;"> 4</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">spawned</span><span style="color: #A6E3A1;"> thread:</span><span style="color: #FAB387;"> 5</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>thread::spawn</code> takes a closure and runs it on a brand new OS thread. The OS scheduler decides when each thread runs, so the output is interleaved unpredictably. <code>thread::spawn</code> returns a <code>JoinHandle&lt;T&gt;</code> where <code>T</code> is whatever the closure returns. The handle's <code>.join()</code> method blocks the calling thread until the spawned thread finishes. We call <code>.unwrap()</code> on <code>.join()</code> because if the spawned thread panicked, <code>join</code> returns the panic payload as an <code>Err</code>. The spawned thread gets five iterations with 100ms sleeps, while the main thread runs three iterations with 150ms sleeps. Even though main finishes its loop first, it blocks on <code>handle.join()</code> until the spawned thread is done.</p> <h2 id="threads-need-ownership-move-closures">Threads Need Ownership: <code>move</code> Closures</h2> <p>In the example above the closure captures nothing. Let's try capturing a variable:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> name</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;worker&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> handle</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> thread</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">||</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello from </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> name</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> handle</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Try to compile this. You will get an error:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">error[E0373]:</span><span style="color: #A6E3A1;"> closure may outlive the current function, but it borrows</span><span style="color: #94E2D5;"> `</span><span style="color: #89B4FA;font-style: italic;">name</span><span style="color: #94E2D5;">`</span><span style="color: #89B4FA;font-style: italic;">,</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">which</span><span style="color: #A6E3A1;"> is owned by the current function</span></span></code></pre> <p>The compiler is telling us something important about threads: the spawned thread could outlive the scope that owns <code>name</code>. If <code>main</code> finishes and drops <code>name</code> while the spawned thread is still running, the reference would dangle. Rust prevents this at compile time.</p> <p>The fix is the <code>move</code> keyword:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> handle</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> thread</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">move</span><span style="color: #94E2D5;"> ||</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello from </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> name</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">});</span></span></code></pre> <p>We already learned about <code>move</code> in the closures article. The <code>move</code> keyword forces the closure to take ownership of every variable it captures. <code>name</code> moves into the closure. It is no longer accessible in <code>main</code> after <code>spawn</code>. The spawned thread now owns the string and can use it safely for as long as it runs.</p> <p>This is the core rule of threads: anything a thread uses must either be owned by the thread, or be guaranteed to outlive the thread (like a <code>&amp;'static str</code> literal).</p> <h2 id="message-passing-with-mpsc">Message Passing with <code>mpsc</code></h2> <p>Threads need to communicate. Rust provides channels in <code>std::sync::mpsc</code>. The name stands for multiple producer, single consumer. You can clone the <code>Sender</code> and send messages from many threads, but there is only one <code>Receiver</code>.</p> <p>Here is a minimal example:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">sync</span><span style="color: #94E2D5;">::</span><span>mpsc</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span>thread</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span style="color: #9399B2;"> (</span><span>tx</span><span style="color: #9399B2;">,</span><span> rx</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> mpsc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">channel</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;"> thread</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">move</span><span style="color: #94E2D5;"> ||</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> tx</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">send</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello from the spawned thread&quot;</span><span style="color: #9399B2;">))</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> msg</span><span style="color: #94E2D5;"> =</span><span> rx</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">recv</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;received: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> msg</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>mpsc::channel()</code> returns a <code>(Sender&lt;T&gt;, Receiver&lt;T&gt;)</code> tuple. <code>T</code> is inferred from the first <code>send</code> call. <code>Sender::send</code> takes ownership of the message being sent, but only borrows the sender itself. A single sender can be reused to send many messages. If you want multiple threads to send messages concurrently, you can call <code>clone()</code> on the sender to create additional sending handles. <code>Receiver::recv</code> blocks the calling thread until a message arrives. It returns <code>Result&lt;T, RecvError&gt;</code>, where the error means all senders have been dropped and the channel is closed.</p> <p>There are other methods on <code>Receiver</code>:</p> <table><thead><tr><th>Method</th><th>Behaviour</th></tr></thead><tbody> <tr><td><code>recv()</code></td><td>Blocks until a message is available. Returns <code>Err(RecvError)</code> if all senders are dropped.</td></tr> <tr><td><code>try_recv()</code></td><td>Does not block. Returns <code>Ok(msg)</code>, <code>Err(TryRecvError::Empty)</code>, or <code>Err(TryRecvError::Disconnected)</code>.</td></tr> <tr><td><code>iter()</code></td><td>Returns an iterator that yields messages until the channel is closed. This is how workers will loop.</td></tr> </tbody></table> <p><code>Sender::send</code> also has a counterpart:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span style="color: #9399B2;"> (</span><span>tx</span><span style="color: #9399B2;">,</span><span> rx</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> mpsc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">sync_channel</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // bounded channel, capacity 2</span></span></code></pre> <p>A <code>sync_channel</code> has a fixed capacity. When the channel is full, <code>send</code> blocks the calling thread until space is freed. This is how we implement backpressure: the producer is forced to wait if the workers are overwhelmed.</p> <h2 id="multiple-producers">Multiple Producers</h2> <p><code>Sender</code> implements <code>Clone</code>. Here is a pattern with two sending threads:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">sync</span><span style="color: #94E2D5;">::</span><span>mpsc</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span>thread</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span style="color: #9399B2;"> (</span><span>tx</span><span style="color: #9399B2;">,</span><span> rx</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> mpsc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">channel</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> tx1</span><span style="color: #94E2D5;"> =</span><span> tx</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> thread</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">move</span><span style="color: #94E2D5;"> ||</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> i</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 0</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> tx1</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">send</span><span style="color: #9399B2;">(</span><span>i</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;"> thread</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">move</span><span style="color: #94E2D5;"> ||</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> i</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 10</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">13</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> tx</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">send</span><span style="color: #9399B2;">(</span><span>i</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> msg</span><span style="color: #CBA6F7;"> in</span><span> rx</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;received: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> msg</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>tx.clone()</code> creates a second sender. Both threads send messages. The main thread uses <code>for msg in rx</code> to iterate over the receiver. This loop runs until all senders are dropped and the channel is empty, at which point the iterator ends and the loop exits. You do not need to know how many messages there are ahead of time. The channel closing is detected automatically.</p> <h2 id="arc-the-thread-safe-rc">Arc: The Thread-Safe Rc</h2> <p>In the smart pointers article, we learned about <code>Rc&lt;T&gt;</code> for shared ownership in single-threaded code. <code>Rc</code> uses non-atomic reference counting, which is faster but not safe across threads. The compiler enforces this: <code>Rc</code> does not implement <code>Send</code> or <code>Sync</code>, so you cannot send an <code>Rc</code> to another thread.</p> <p><code>Arc&lt;T&gt;</code> - Atomic Reference Counted is the thread-safe version. It uses atomic operations for the reference count, which are slightly slower than <code>Rc</code>'s non-atomic counter, but safe across threads. The usage is identical:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">sync</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Arc</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span>thread</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> data</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Arc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">vec!</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">]);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> data1</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Arc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>data</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> handle1</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> thread</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">move</span><span style="color: #94E2D5;"> ||</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;thread 1: </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">:?</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> data1</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> data2</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Arc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>data</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> handle2</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> thread</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">move</span><span style="color: #94E2D5;"> ||</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;thread 2: </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">:?</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> data2</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> handle1</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> handle2</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>Arc::new</code> allocates a reference-counted allocation containing the value and returns an <code>Arc</code> handle to it. <code>Arc::clone</code> increments the atomic reference count and returns another handle to the same allocation. Unlike <code>Rc</code>, <code>Arc::clone</code> does not actually deep-clone the data - it just increments the counter. <code>Arc</code> uses atomic operations for reference counting, making shared ownership safe across threads. <code>Arc&lt;T&gt;</code> implements <code>Send</code> and <code>Sync</code> when <code>T</code> itself satisfies the necessary thread-safety requirements. This allows us to move cloned <code>Arc</code> handles into threads with <code>move</code> closures. The three handles (<code>data</code>, <code>data1</code>, <code>data2</code>) all point to the same heap allocation. When the last handle is dropped, the reference count reaches zero and the data is freed.</p> <h2 id="mutex-mutual-exclusion">Mutex: Mutual Exclusion</h2> <p><code>Arc</code> gives us shared ownership, but it gives us immutable shared ownership. You cannot mutate through an <code>Arc</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> data</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Arc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">42</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// *data += 1; // ERROR: cannot modify through Arc</span></span></code></pre> <p>If multiple threads all hold an <code>Arc</code> to the same value, they can all read it safely. But what if they need to write? Or what if the value is something like a <code>Vec</code> that needs to be modified?</p> <p>This is where <code>Mutex&lt;T&gt;</code> comes in. A <code>Mutex</code> provides mutual exclusion: only one thread can access the data at a time. Other threads block until the lock is released.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">sync</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Mutex</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span>thread</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> counter</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Mutex</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> num</span><span style="color: #94E2D5;"> =</span><span> counter</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">lock</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> *</span><span>num</span><span style="color: #94E2D5;"> +=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #9399B2;font-style: italic;"> // lock released here</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;counter = </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> *</span><span>counter</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">lock</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>Mutex::new(0)</code> wraps the integer in a mutex. <code>counter.lock()</code> blocks until we can acquire the lock, then returns a <code>MutexGuard&lt;T&gt;</code>. The <code>MutexGuard</code> derefs to <code>&amp;mut T</code>, so we can mutate the value through it. When the guard goes out of scope (at the end of the block), the lock is automatically released. We call <code>.unwrap()</code> on <code>lock()</code> because it returns a <code>Result</code>, the error case is if the mutex is poisoned, which means another thread panicked while holding the lock.</p> <p>The <code>Mutex</code> pattern is similar to <code>RefCell</code> which we learned in the previous article. Both provide interior mutability. The difference is: <code>RefCell</code> panics at runtime if you violate borrowing rules. <code>Mutex</code> blocks the thread until the lock is available. <code>RefCell</code> is for single threads. <code>Mutex</code> is for multiple threads.</p> <h2 id="arc-mutex-t-shared-mutable-state-across-threads"><code>Arc&lt;Mutex&lt;T&gt;&gt;</code>: Shared Mutable State Across Threads</h2> <p>Now combine them. <code>Arc</code> provides shared ownership. <code>Mutex</code> provides safe mutation. Together, they give us shared mutable state across threads:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">sync</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">Arc</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Mutex</span><span style="color: #9399B2;">};</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span>thread</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> counter</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Arc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Mutex</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> handles</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> _</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 0</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> counter</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Arc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>counter</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> handle</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> thread</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">move</span><span style="color: #94E2D5;"> ||</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> num</span><span style="color: #94E2D5;"> =</span><span> counter</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">lock</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> *</span><span>num</span><span style="color: #94E2D5;"> +=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span> handles</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>handle</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> handle</span><span style="color: #CBA6F7;"> in</span><span> handles</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> handle</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;counter = </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> *</span><span>counter</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">lock</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p>We create an <code>Arc&lt;Mutex&lt;i32&gt;&gt;</code>. Inside the loop, we clone the <code>Arc</code> and move the clone into a thread. Each thread acquires the lock, increments the counter, and releases the lock when the guard goes out of scope. Only one thread can hold the lock at any moment, so the increments are serialised and there are no data races. After all threads finish, the counter is exactly 5.</p> <p>Let me read <code>Arc&lt;Mutex&lt;T&gt;&gt;</code> from the inside out:</p> <ul> <li><code>T</code> is the actual data</li> <li><code>Mutex&lt;T&gt;</code> wraps the data with a lock</li> <li><code>Arc&lt;Mutex&lt;T&gt;&gt;</code> stores the <code>Mutex&lt;T&gt;</code> inside an <code>Arc</code> managed heap allocation and enables multiple owners</li> </ul> <p>You will see this pattern everywhere in multi-threaded Rust code. It is the thread-safe counterpart of <code>Rc&lt;RefCell&lt;T&gt;&gt;</code> from the previous article.</p> <h2 id="the-problem-with-sharing-the-receiver">The Problem with Sharing the Receiver</h2> <p>For our thread pool, every worker thread needs to receive jobs from the same queue. The natural approach is to share the <code>Receiver</code> from an <code>mpsc</code> channel. But let me show you why this does not work directly:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">sync</span><span style="color: #94E2D5;">::</span><span>mpsc</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span style="color: #9399B2;"> (</span><span>tx</span><span style="color: #9399B2;">,</span><span> rx</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> mpsc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">channel</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // ERROR: Receiver is not Sync, cannot be shared</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // let shared_rx = std::sync::Arc::new(rx);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>Receiver&lt;T&gt;</code> does not implement <code>Sync</code>. The reason is that receiving from a channel is inherently stateful: only one thread should receive each message. If multiple threads tried to call <code>recv()</code> simultaneously on the same <code>Receiver</code>, they would race.</p> <p>The solution is <code>Arc&lt;Mutex&lt;Receiver&lt;T&gt;&gt;&gt;</code>. The <code>Mutex</code> ensures only one worker can receive at a time. The worker locks the mutex, calls <code>recv</code> (which blocks until a message arrives), then releases the lock for the next worker:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">sync</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">Arc</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Mutex</span><span style="color: #9399B2;">,</span><span> mpsc</span><span style="color: #9399B2;">};</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span>thread</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span style="color: #9399B2;"> (</span><span>tx</span><span style="color: #9399B2;">,</span><span> rx</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> mpsc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">channel</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> rx</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Arc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Mutex</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>rx</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> rx1</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Arc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>rx</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> thread</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">move</span><span style="color: #94E2D5;"> ||</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> msg</span><span style="color: #94E2D5;"> =</span><span> rx1</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">lock</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">recv</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;worker 1 got: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> msg</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> rx2</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Arc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>rx</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> thread</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">move</span><span style="color: #94E2D5;"> ||</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> msg</span><span style="color: #94E2D5;"> =</span><span> rx2</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">lock</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">recv</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;worker 2 got: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> msg</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> tx</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">send</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">10</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> tx</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">send</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">20</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>rx</code> is an <code>Arc&lt;Mutex&lt;Receiver&lt;i32&gt;&gt;&gt;</code>. Each worker clones the <code>Arc</code> and moves the clone into its thread. To receive a job, the worker calls <code>rx.lock().unwrap().recv().unwrap()</code>. The <code>.lock()</code> blocks until the mutex is available. The <code>.recv()</code> blocks until a message arrives. Both workers are racing to acquire the lock. Whichever wins gets to receive the next message. The other worker blocks on <code>.lock()</code> until the first worker releases the lock (which happens when the guard goes out of scope at the end of the statement).</p> <p>This means exactly one message goes to exactly one worker. No duplication. No missed messages. The mutex serialises access to the receiver. An important detail is that the mutex is held during the blocking <code>recv()</code> call. This means only one worker can wait on the receiver at a time. Workers still execute jobs concurrently, but receiving jobs from the channel is serialised through the mutex.</p> <h2 id="the-thread-pool-architecture">The Thread Pool Architecture</h2> <p>Now let's design our thread pool. Here is the architecture:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>main thread thread pool</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> |-- tx.send(job) --------&gt; | (mpsc::Sender&lt;Job&gt;)</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> | +-- Worker 1 -- rx.lock().recv() -&gt; execute job</span></span> <span class="giallo-l"><span> | +-- Worker 2 -- rx.lock().recv() -&gt; execute job</span></span> <span class="giallo-l"><span> | +-- Worker 3 -- rx.lock().recv() -&gt; execute job</span></span> <span class="giallo-l"><span> | +-- Worker 4 -- rx.lock().recv() -&gt; execute job</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> |-- drop(tx) ------------&gt; | (workers finish queued jobs, then exit once the channel is empty)</span></span></code></pre> <p>The <code>ThreadPool</code> struct holds a <code>Sender&lt;Job&gt;</code> and a <code>Vec&lt;JoinHandle&lt;()&gt;&gt;</code> for the worker threads. When a user calls <code>pool.execute(closure)</code>, the closure is boxed into a <code>Job</code> and sent through the channel. All workers loop. Each worker acquires the mutex protecting the receiver, waits for and receives the next available job, then releases the mutex before executing the job. When the pool is dropped, the <code>Sender</code> is dropped, the channel closes, each worker's <code>recv()</code> returns <code>Err</code>, and the loop exits.</p> <h2 id="the-project-thread-pool-from-scratch">The Project: Thread Pool from Scratch</h2> <p>Our program will:</p> <ul> <li>Define a <code>Job</code> type as <code>Box&lt;dyn FnOnce() + Send + 'static&gt;</code></li> <li>Create a <code>Worker</code> struct that holds a thread handle and an ID</li> <li>Create a <code>ThreadPool</code> struct that holds a sender and worker handles</li> <li>Implement <code>ThreadPool::new(size)</code> that spawns <code>size</code> workers</li> <li>Implement <code>pool.execute(closure)</code> that sends a job to the workers</li> <li>Implement graceful shutdown: workers continue receiving and executing queued jobs until the channel becomes both disconnected and empty, then exit cleanly</li> <li>Use <code>sync_channel</code> with a bounded capacity for backpressure</li> <li>Write a demo <code>main</code> that shows it working</li> </ul> <h2 id="project-setup">Project Setup</h2> <p>Delete the test code from <code>src/main.rs</code>. We will build the entire pool from scratch:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> new threadpool</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> threadpool</span></span></code></pre> <p>We do not need any external crates. Everything is in <code>std</code>. Open <code>src/main.rs</code> and we will build everything step by step.</p> <h2 id="the-job-type">The Job Type</h2> <p>A job is something that can be executed once. The most natural way to represent this in Rust is a trait object:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">type</span><span style="color: #F9E2AF;font-style: italic;"> Job</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Box</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">dyn</span><span style="color: #F9E2AF;font-style: italic;"> FnOnce</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> +</span><span style="color: #F9E2AF;font-style: italic;"> Send</span><span style="color: #94E2D5;"> +</span><span style="color: #9399B2;"> &#39;</span><span style="color: #89B4FA;font-style: italic;">static</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">;</span></span></code></pre> <p>Let me read this from inside out:</p> <ul> <li><code>FnOnce()</code> means a closure that takes no arguments and returns nothing, and can be called exactly once.</li> <li><code>Send</code> means the closure can be transferred safely between threads.</li> <li><code>'static</code> means the closure cannot contain borrowed references with shorter lifetimes.</li> <li><code>Box&lt;dyn ...&gt;</code> heap-allocates the closure and erases its concrete type.</li> </ul> <p>This is exactly the same pattern we used in the linter article where we stored <code>Box&lt;dyn Fn(&amp;str) -&gt; Vec&lt;Violation&gt;&gt;</code>. The only new bits are <code>Send</code> (for threads) and <code>FnOnce</code> (because a job is consumed when executed).</p> <h2 id="the-worker-struct">The Worker Struct</h2> <p>A <code>Worker</code> is a thread that loops forever, receiving and executing jobs:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span>thread</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Worker</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> thread</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;"> thread</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">JoinHandle</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The <code>id</code> field is for debug printing (we will print "worker 2 got a job" etc.). The <code>thread</code> field holds the join handle so we can wait for the worker to finish during shutdown.</p> <h2 id="the-worker-loop">The Worker Loop</h2> <p>A worker needs to receive jobs from the shared receiver. The worker runs a loop:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Worker</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> new</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> id</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> receiver</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Arc</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Mutex</span><span style="color: #89DCEB;">&lt;</span><span style="color: #EBA0AC;">mpsc</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Receiver</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Job</span><span style="color: #89DCEB;">&gt;&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> )</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Worker</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> thread</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> thread</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">move</span><span style="color: #94E2D5;"> ||</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> loop</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> job</span><span style="color: #94E2D5;"> =</span><span> receiver</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">lock</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">recv</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> job</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>job</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;worker </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> got a job; executing.&quot;</span><span style="color: #9399B2;">,</span><span> id</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> job</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;worker </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> shutting down.&quot;</span><span style="color: #9399B2;">,</span><span> id</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Worker</span><span style="color: #9399B2;"> {</span><span> id</span><span style="color: #9399B2;">,</span><span> thread</span><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>Worker::new</code> takes an <code>id</code> and an <code>Arc&lt;Mutex&lt;Receiver&lt;Job&gt;&gt;&gt;</code>. Inside <code>thread::spawn(move || ...)</code>, the closure starts with a <code>loop</code>. In each iteration, the worker:</p> <ol> <li>Calls <code>receiver.lock().unwrap()</code> to acquire the mutex. This blocks if another worker is currently receiving a message.</li> <li>Calls <code>.recv()</code> on the receiver. This blocks if the channel is empty but not closed.</li> <li>Matches on the result. <code>Ok(job)</code> means we got a job, so we call <code>job()</code> to execute it and print the worker ID. <code>Err(_)</code> means all senders have been dropped (the channel is closed), so we <code>break</code> out of the loop.</li> <li>When the loop exits, the thread function returns and the thread terminates.</li> </ol> <p>The <code>move</code> keyword is essential here. It moves ownership of <code>id</code> and <code>receiver</code> into the closure. <code>id</code> is a <code>usize</code> (which is <code>Copy</code>), but <code>receiver</code> is an <code>Arc</code> which must be moved so the thread can share ownership of the receiver.</p> <h2 id="the-threadpool-struct">The ThreadPool Struct</h2> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">sync</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">Arc</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Mutex</span><span style="color: #9399B2;">,</span><span> mpsc</span><span style="color: #9399B2;">};</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> ThreadPool</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> workers</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Worker</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> sender</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span>mpsc</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Sender</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Job</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>workers</code> is a <code>Vec&lt;Worker&gt;</code>. We store the workers so we can join them during shutdown. <code>sender</code> is <code>Option&lt;mpsc::Sender&lt;Job&gt;&gt;</code>. When we want to shut down, we set <code>sender</code> to <code>None</code> by calling <code>take()</code>. This drops the sender, which closes the channel, which causes every worker's <code>recv()</code> to return <code>Err</code>, which causes every worker to <code>break</code> out of its loop. The <code>Option</code> is the standard Rust pattern for dropping something during <code>Drop</code> that you also need to access during the struct's normal lifetime.</p> <h2 id="threadpool-new">ThreadPool::new</h2> <p>Now let's implement <code>ThreadPool::new</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> ThreadPool</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> new</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">size</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> ThreadPool</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> assert!</span><span style="color: #9399B2;">(</span><span>size</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;ThreadPool must have at least 1 worker&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span style="color: #9399B2;"> (</span><span>sender</span><span style="color: #9399B2;">,</span><span> receiver</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> mpsc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">channel</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> receiver</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Arc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Mutex</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>receiver</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> workers</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">with_capacity</span><span style="color: #9399B2;">(</span><span>size</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> id</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 0</span><span style="color: #94E2D5;">..</span><span>size</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> workers</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Worker</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>id</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;"> Arc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>receiver</span><span style="color: #9399B2;">)));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> ThreadPool</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> workers</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> sender</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>sender</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p>We use <code>mpsc::channel()</code> to create an unbounded channel for jobs. The receiver is wrapped in <code>Arc::new(Mutex::new(receiver))</code> so it can be shared across all workers. For each worker (from 0 to <code>size</code>), we clone the <code>Arc</code> and pass it to <code>Worker::new</code>. Each worker gets its own clone of the <code>Arc</code>, so all workers share the same <code>Mutex&lt;Receiver&lt;Job&gt;&gt;</code>. The sender is wrapped in <code>Some</code> so we can later <code>take()</code> it during shutdown.</p> <p>The <code>assert!</code> ensures we never create a pool with zero workers. A pool with zero workers would never execute any jobs.</p> <h2 id="the-execute-method">The <code>execute</code> Method</h2> <p>The <code>execute</code> method takes a closure, boxes it into a <code>Job</code>, and sends it through the channel:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> ThreadPool</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> execute</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">F</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> f</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> F</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> where</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> F</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> FnOnce</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> +</span><span style="color: #F9E2AF;font-style: italic;"> Send</span><span style="color: #94E2D5;"> +</span><span style="color: #9399B2;"> &#39;</span><span style="color: #89B4FA;font-style: italic;">static</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> job</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Box</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>f</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>sender</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">as_ref</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">send</span><span style="color: #9399B2;">(</span><span>job</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>execute</code> is generic over <code>F</code>, which must implement <code>FnOnce() + Send + 'static</code>. These are the same bounds as on <code>Job</code> itself. Inside, we box the closure into a <code>Box&lt;dyn FnOnce() + Send + 'static&gt;</code> and send it through the channel. We call <code>unwrap()</code> on both the <code>as_ref()</code> (the sender should always exist during normal operation) and <code>send()</code> (we assume the channel is healthy). A production implementation would return a <code>Result</code>, but for learning purposes <code>unwrap</code> is fine.</p> <p>When <code>execute</code> returns, the job is in the queue. One of the workers will eventually pick it up and run it.</p> <h2 id="graceful-shutdown-the-drop-implementation">Graceful Shutdown: The Drop Implementation</h2> <p>When the pool is dropped, we want every worker to finish its current job, drain any remaining jobs in the queue, and then shut down. Here is the Drop implementation:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Drop</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> ThreadPool</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> drop</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Drop the sender to close the channel.</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Workers will see the channel close after draining remaining messages.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> drop</span><span style="color: #9399B2;">(</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">sender</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">take</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Wait for every worker to finish.</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> worker</span><span style="color: #CBA6F7;"> in</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>workers</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">drain</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">..</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;shutting down worker </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> worker</span><span style="color: #94E2D5;">.</span><span>id</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> worker</span><span style="color: #94E2D5;">.</span><span>thread</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p>This is a two-part shutdown. First, we call <code>self.sender.take()</code> to get the <code>Option&lt;mpsc::Sender&lt;Job&gt;&gt;</code> and extract the sender, then immediately <code>drop</code> it. This closes the channel. Workers currently blocked on <code>recv()</code> will unblock and:</p> <ul> <li>If there are still messages in the channel, they will receive those messages (the <code>Ok(job)</code> arm) and execute them.</li> <li>Once the channel is drained, the next <code>recv()</code> returns <code>Err(RecvError)</code> (the <code>Err(_)</code> arm) and the worker breaks out of its loop.</li> </ul> <p>So all remaining jobs in the queue are processed before any worker shuts down.</p> <p>Second, we iterate over <code>self.workers.drain(..)</code>. The <code>drain(..)</code> removes every element from the <code>Vec</code>, yielding ownership of each <code>Worker</code>. For each worker, we call <code>thread.join().unwrap()</code> to block until that worker's thread has finished. The order of joining does not matter: some workers may finish sooner than others, but by the time the <code>for</code> loop finishes, all workers have exited.</p> <p>This is true graceful shutdown. No work is lost, and the program waits for everything to finish. This assumes the pool owns the last sender. If other sender clones still exist, the channel remains open and workers will continue waiting for new jobs.</p> <h2 id="adding-backpressure-bounded-channels">Adding Backpressure: Bounded Channels</h2> <p>Our current implementation uses <code>mpsc::channel()</code>, which creates an unbounded channel. The queue can grow infinitely. If jobs are submitted faster than workers can process them, the program's memory grows without bound.</p> <p>We solve this with <code>mpsc::sync_channel(capacity)</code>, which creates a bounded channel. When the channel is full, <code>send()</code> blocks until a worker frees a slot by receiving a job. This is backpressure: the producer is forced to slow down.</p> <p>Update <code>ThreadPool::new</code> to use <code>sync_channel</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> ThreadPool</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> new</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">size</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> ThreadPool</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> assert!</span><span style="color: #9399B2;">(</span><span>size</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;ThreadPool must have at least 1 worker&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span style="color: #9399B2;"> (</span><span>sender</span><span style="color: #9399B2;">,</span><span> receiver</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> mpsc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">sync_channel</span><span style="color: #9399B2;">(</span><span>size</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> receiver</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Arc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Mutex</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>receiver</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> workers</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">with_capacity</span><span style="color: #9399B2;">(</span><span>size</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> id</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 0</span><span style="color: #94E2D5;">..</span><span>size</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> workers</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Worker</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>id</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;"> Arc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>receiver</span><span style="color: #9399B2;">)));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> ThreadPool</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> workers</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> sender</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>sender</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p>The only change is <code>mpsc::channel()</code> becoming <code>mpsc::sync_channel(size * 2)</code>. The capacity is twice the number of workers, which gives a small buffer. The choice of capacity is a tuning parameter. A larger capacity means more queueing but smoother throughput. A smaller capacity means tighter backpressure but more blocking. Twice the worker count is a reasonable default.</p> <p>Note that <code>sync_channel</code> returns <code>SyncSender&lt;Job&gt;</code> instead of <code>Sender&lt;Job&gt;</code>. The two types are different: <code>SyncSender</code> is used with bounded channels and <code>Sender</code> is used with unbounded channels. Since <code>Worker::new</code> is now receiving from a bounded channel, the type in <code>Worker::new</code> must also change to <code>Arc&lt;Mutex&lt;mpsc::Receiver&lt;Job&gt;&gt;&gt;</code>. The <code>Receiver</code> type is the same for both bounded and unbounded channels. The <code>Sender</code> field in <code>ThreadPool</code> changes from <code>Option&lt;mpsc::Sender&lt;Job&gt;&gt;</code> to <code>Option&lt;mpsc::SyncSender&lt;Job&gt;&gt;</code>.</p> <h2 id="running-the-project">Running the Project</h2> <p>Type this in your terminal:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> run</span></span></code></pre> <p>You should see output like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Creating</span><span style="color: #A6E3A1;"> thread pool with</span><span style="color: #FAB387;"> 4</span><span style="color: #A6E3A1;"> workers</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">All</span><span style="color: #A6E3A1;"> jobs submitted. Pool will shut down when scope ends.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 0</span><span style="color: #A6E3A1;"> got a job</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;font-style: italic;"> executing.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 2</span><span style="color: #A6E3A1;"> got a job</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;font-style: italic;"> executing.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 1</span><span style="color: #A6E3A1;"> got a job</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;font-style: italic;"> executing.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 3</span><span style="color: #A6E3A1;"> got a job</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;font-style: italic;"> executing.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 0: starting</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 1: starting</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 2: starting</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 3: starting</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 0: finished</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 1: finished</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 2: finished</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 0</span><span style="color: #A6E3A1;"> got a job</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;font-style: italic;"> executing.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 3: finished</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 2</span><span style="color: #A6E3A1;"> got a job</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;font-style: italic;"> executing.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 1</span><span style="color: #A6E3A1;"> got a job</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;font-style: italic;"> executing.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 3</span><span style="color: #A6E3A1;"> got a job</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;font-style: italic;"> executing.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 4: starting</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 5: starting</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 6: starting</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 7: starting</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 4: finished</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 5: finished</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 6: finished</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 7: finished</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 0</span><span style="color: #A6E3A1;"> shutting down.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">shutting</span><span style="color: #A6E3A1;"> down worker</span><span style="color: #FAB387;"> 0</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 2</span><span style="color: #A6E3A1;"> shutting down.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">shutting</span><span style="color: #A6E3A1;"> down worker</span><span style="color: #FAB387;"> 2</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 1</span><span style="color: #A6E3A1;"> shutting down.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">shutting</span><span style="color: #A6E3A1;"> down worker</span><span style="color: #FAB387;"> 1</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 3</span><span style="color: #A6E3A1;"> shutting down.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">shutting</span><span style="color: #A6E3A1;"> down worker</span><span style="color: #FAB387;"> 3</span></span></code></pre> <p>Now, let me explain what happened.</p> <p>The first four jobs were picked up immediately by the four idle workers. They all started roughly at the same time. The remaining four jobs were queued in the channel. As soon as a worker finished its job, it picked up the next one from the queue. After all eight jobs were done and the channel was empty, each worker's <code>recv()</code> returned <code>Err</code>, the loop broke, and the worker printed its shutdown message. The main thread then joined each worker and printed the final shutdown messages.</p> <p>Four workers processed eight jobs, with no more than four jobs running at any time.</p> <h2 id="running-with-only-one-worker">Running with Only One Worker</h2> <p>Let's test with a single worker to see that jobs are truly serialised. Change <code>ThreadPool::new(4)</code> to <code>ThreadPool::new(1)</code> and run again:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Creating</span><span style="color: #A6E3A1;"> thread pool with</span><span style="color: #FAB387;"> 1</span><span style="color: #A6E3A1;"> workers</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">All</span><span style="color: #A6E3A1;"> jobs submitted. Pool will shut down when scope ends.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 0</span><span style="color: #A6E3A1;"> got a job</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;font-style: italic;"> executing.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 0: starting</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 0: finished</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 0</span><span style="color: #A6E3A1;"> got a job</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;font-style: italic;"> executing.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 1: starting</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 1: finished</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 0</span><span style="color: #A6E3A1;"> got a job</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;font-style: italic;"> executing.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 2: starting</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 2: finished</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 0</span><span style="color: #A6E3A1;"> got a job</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;font-style: italic;"> executing.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 3: starting</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 3: finished</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 0</span><span style="color: #A6E3A1;"> got a job</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;font-style: italic;"> executing.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 4: starting</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 4: finished</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 0</span><span style="color: #A6E3A1;"> got a job</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;font-style: italic;"> executing.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 5: starting</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 5: finished</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 0</span><span style="color: #A6E3A1;"> got a job</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;font-style: italic;"> executing.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 6: starting</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 6: finished</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 0</span><span style="color: #A6E3A1;"> got a job</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;font-style: italic;"> executing.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 7: starting</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">job</span><span style="color: #A6E3A1;"> 7: finished</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">worker</span><span style="color: #FAB387;"> 0</span><span style="color: #A6E3A1;"> shutting down.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">shutting</span><span style="color: #A6E3A1;"> down worker</span><span style="color: #FAB387;"> 0</span></span></code></pre> <p>Now, let me explain what happened.</p> <p>With one worker, jobs are processed one at a time. Each job starts and finishes before the next one begins. No concurrency, but the thread pool abstraction is still useful: it prevents unbounded thread creation and gives you a bounded queue.</p> <h2 id="verifying-backpressure">Verifying Backpressure</h2> <p>Let's write a test that proves backpressure works. Replace <code>main</code> with:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Creating thread pool with 2 workers (bounded channel capacity 4)&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> pool</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> ThreadPool</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Submit many long-running jobs to fill the queue and block the main thread</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> i</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 0</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">10</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;main: submitting job </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> i</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> pool</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">execute</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">move</span><span style="color: #94E2D5;"> ||</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;job </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">: starting&quot;</span><span style="color: #9399B2;">,</span><span> i</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> thread</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">sleep</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Duration</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_secs</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;job </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">: finished&quot;</span><span style="color: #9399B2;">,</span><span> i</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;main: job </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> accepted&quot;</span><span style="color: #9399B2;">,</span><span> i</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;All jobs submitted.&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>With a <code>sync_channel</code> of capacity 4 (2 workers * 2), jobs are accepted until the channel's buffer becomes full. Since the workers are simultaneously consuming jobs, the exact point at which <code>send()</code> begins blocking depends on thread scheduling. What is guaranteed is that if jobs are submitted faster than workers can process them, the producer will eventually block once the queue reaches capacity. Once the channel buffer reaches capacity, further calls to <code>send()</code> block until a worker receives a job and frees a slot.</p> <h2 id="what-we-skipped">What We Skipped</h2> <p>There are a few things I am intentionally skipping in this article that we will cover in future ones:</p> <ul> <li><strong>Async/await</strong>: Threads are OS-level concurrency. Async is cooperative concurrency within a single thread. We will build an async HTTP server in a future article and learn Tokio.</li> <li><strong><code>rayon</code> crate</strong>: Rayon provides data parallelism with work-stealing thread pools. It is a higher-level abstraction built on top of the primitives we used today.</li> <li><strong>Panic handling in workers</strong>: Our implementation uses <code>unwrap()</code> on <code>lock()</code> and <code>join()</code>. A production thread pool would handle poisoned mutexes and panicked threads gracefully.</li> <li><strong>Configurable queue capacity</strong>: The capacity is hardcoded to <code>size * 2</code>. A production library would expose this as a parameter.</li> <li><strong>Atomic counters for active jobs</strong>: A production pool might track how many jobs are currently executing using an <code>AtomicUsize</code>.</li> </ul> <h2 id="conclusion">Conclusion</h2> <p>In this post, you learned about OS threads (<code>std::thread::spawn</code>), message passing (<code>mpsc::channel</code> and <code>sync_channel</code>), shared ownership across threads (<code>Arc</code>), mutual exclusion (<code>Mutex</code>), and the <code>Arc&lt;Mutex&lt;T&gt;&gt;</code> pattern for shared mutable state. You built a Thread Pool from scratch with a fixed number of workers, a bounded job queue, an <code>execute</code> method that accepts closures, and graceful shutdown that continues processing queued jobs before exiting.</p> <p>This project ties together everything from the smart pointers article and the closures article. <code>Arc</code> is the thread-safe sibling of <code>Rc</code>. <code>Mutex</code> is the thread-safe sibling of <code>RefCell</code>. <code>Box&lt;dyn FnOnce() + Send&gt;</code> is the thread-safe version of the closure stores we built in the linter.</p> <p>In the next article, we will learn about <strong>async/await</strong> and <strong>Tokio</strong> and <strong>build an HTTP/1.1 server from scratch</strong>. See you soon.</p> <p>If you like reading this, please subscribe and share this with others. It'll really help me and motivate me to keep publishing more such articles.</p> 2026-06-03T00:00:00+00:00 2026-06-03T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/learn-rust-smart-pointers-and-interior-mutability-by-building-git-commit-graph-viewer/ <p>In this post, we are going to learn about smart pointers and interior mutability in Rust. Once we cover all the concepts, we will build a <strong>Git Commit Graph Viewer</strong> that reads a real <code>.git</code> directory, parses every commit, builds a connected DAG (directed acyclic graph) using <code>Rc&lt;RefCell&lt;CommitNode&gt;&gt;</code> with <code>Weak</code> edges, and renders an ASCII graph of your commit history. I am really excited for this project and I hope you are too. I won't go too deep in theory, just practical and we will build our knowledge of these concepts over time with more articles.</p> <p>The only prerequisite is that you have read the previous articles in this series, as I will assume you know ownership, borrowing, structs, enums, pattern matching, error handling, generics, traits, lifetimes, HashMap, iterators, and closures.</p> <p>Get the source code from <a rel="external" href="https://github.com/MrSheerluck/git-commit-graph">here</a></p> <h2 id="what-is-a-smart-pointer">What is a Smart Pointer</h2> <p>A pointer is a variable that holds a memory address. A smart pointer is a data structure that acts like a pointer but also has additional metadata and capabilities. In Rust, <code>String</code> and <code>Vec&lt;T&gt;</code> are technically smart pointers. They own heap-allocated data and manage it automatically.</p> <p>But when people say "smart pointers" in Rust, they usually mean the types in the standard library that provide ownership and borrowing patterns beyond the basic reference: <code>Box&lt;T&gt;</code>, <code>Rc&lt;T&gt;</code>, <code>RefCell&lt;T&gt;</code>, <code>Weak&lt;T&gt;</code>, and later <code>Arc&lt;T&gt;</code> and <code>Mutex&lt;T&gt;</code>.</p> <p>We will start with <code>Box</code> (which you have already seen) and build up to the more complex ones.</p> <h2 id="box-recap">Box Recap</h2> <p>You saw <code>Box&lt;T&gt;</code> in the article on closures. A <code>Box&lt;T&gt;</code> is the simplest smart pointer. It allocates a value on the heap and owns it. When the <code>Box</code> is dropped, the heap memory is freed.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Box</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">42</span><span style="color: #9399B2;">);</span></span></code></pre> <p>This stores <code>42</code> on the heap. The <code>Box</code> on the stack holds a pointer to it. You use <code>x</code> like a regular <code>i32</code> thanks to deref coercion.</p> <p>The two main use cases for <code>Box</code> are recursive types (like our JSON parser's recursive <code>JsonValue</code> enum) and trait objects (<code>Box&lt;dyn Trait&gt;</code>). Both require heap allocation because the compiler cannot know the size of the type at compile time.</p> <h2 id="rc-reference-counted-smart-pointer">Rc: Reference-Counted Smart Pointer</h2> <p>Now let's talk about <code>Rc&lt;T&gt;</code>. <code>Rc</code> stands for "Reference Counted." It enables multiple ownership. Multiple parts of your code can share ownership of the same value, and the value is dropped only when all owners are gone.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">rc</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Rc</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> a</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">42</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> b</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>a</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> c</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>a</span><span style="color: #9399B2;">);</span></span></code></pre> <p>Here, <code>a</code>, <code>b</code>, and <code>c</code> all point to the same heap allocation containing <code>42</code>. <code>Rc::clone</code> does not deep-copy the data. It increments a reference counter. When <code>a</code>, <code>b</code>, and <code>c</code> all go out of scope, the counter reaches zero and the data is freed.</p> <p>Let me explain what <code>Rc</code> gives us. Without <code>Rc</code>, each value has exactly one owner. If we want to share a value between multiple structs, we could use references with lifetimes, but lifetimes force us to think about who outlives whom. <code>Rc</code> says: "Instead of enforcing a single owner, I will keep a runtime reference count and free the data when the last owner disappears."</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">rc</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Rc</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> data</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">vec!</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">]);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> shared1</span><span style="color: #94E2D5;"> =</span><span> data</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> shared2</span><span style="color: #94E2D5;"> =</span><span> data</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Reference count: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">strong_count</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>data</span><span style="color: #9399B2;">));</span></span></code></pre> <p><code>Rc::strong_count</code> tells you how many handles point to the same allocation. In this case, it would print <code>3</code> because <code>data</code>, <code>shared1</code>, and <code>shared2</code> all share ownership.</p> <p>There is an important limitation: <code>Rc</code> is not thread-safe. It uses non-atomic reference counting, which is faster but unsafe across threads. For multi-threaded code, you use <code>Arc</code> (Atomic Reference Counted), which we will cover in a future article.</p> <h2 id="refcell-interior-mutability">RefCell: Interior Mutability</h2> <p>Now we get to the interesting one. <code>RefCell&lt;T&gt;</code> provides interior mutability. "Interior mutability" is the ability to mutate data even when the <code>RefCell</code> itself is immutable.</p> <p>Normally, Rust's borrow rules are enforced at compile time:</p> <ul> <li>You can have either many immutable references or one mutable reference</li> <li>These rules are checked and enforced before your program runs</li> </ul> <p><code>RefCell&lt;T&gt;</code> moves these checks from compile time to runtime. You can always call <code>borrow</code> or <code>borrow_mut</code> on a <code>RefCell</code>. If you violate the rules, your program will panic at runtime.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">cell</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RefCell</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> RefCell</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">42</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> r1</span><span style="color: #94E2D5;"> =</span><span> x</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> r2</span><span style="color: #94E2D5;"> =</span><span> x</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// Both immutable borrows are fine</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{} {}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> r1</span><span style="color: #9399B2;">,</span><span> r2</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> r3</span><span style="color: #94E2D5;"> =</span><span> x</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow_mut</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #94E2D5;">*</span><span>r3</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 100</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// This would panic: already immutably borrowed</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// let r4 = x.borrow();</span></span></code></pre> <p><code>borrow</code> returns a <code>Ref&lt;T&gt;</code>, which derefs to <code>&amp;T</code>. <code>borrow_mut</code> returns a <code>RefMut&lt;T&gt;</code>, which derefs to <code>&amp;mut T</code>. Both types automatically release the borrow when they go out of scope.</p> <p>The runtime checking is why this pattern is called "interior mutability." The <code>RefCell</code> can be accessed through an immutable binding or immutable reference, yet the value inside it can still be mutated through <code>borrow_mut</code>.</p> <p>Why would you want this? Consider a struct with a method that takes <code>&amp;self</code> but needs to modify internal state:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">cell</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RefCell</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Counter</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> count</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> RefCell</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">u32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Counter</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> increment</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> *</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>count</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow_mut</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> +=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> value</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> u32</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> *</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>count</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The <code>increment</code> method takes <code>&amp;self</code> (an immutable reference), but it can still mutate <code>count</code> through <code>RefCell</code>. Without <code>RefCell</code>, we would need <code>&amp;mut self</code> everywhere, which would make the code harder to use.</p> <h2 id="rc-refcell-t-the-shared-mutable-pattern"><code>Rc&lt;RefCell&lt;T&gt;&gt;</code>: The Shared Mutable Pattern</h2> <p>Now combine <code>Rc</code> and <code>RefCell</code>. <code>Rc</code> gives us shared ownership. <code>RefCell</code> gives us interior mutability. Together, they give us shared mutable state.</p> <p>This is one of the most common patterns in single-threaded Rust code.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">rc</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Rc</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">cell</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RefCell</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> shared</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">RefCell</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">42</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> a</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>shared</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> b</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>shared</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #94E2D5;">*</span><span>a</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow_mut</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> +=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> shared</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">());</span><span style="color: #9399B2;font-style: italic;"> // 43</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> a</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">());</span><span style="color: #9399B2;font-style: italic;"> // 43</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> b</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">());</span><span style="color: #9399B2;font-style: italic;"> // 43</span></span></code></pre> <p>All three handles see the same value because they share the same <code>RefCell</code>. Modifying through any handle affects all of them.</p> <p>Let me read <code>Rc&lt;RefCell&lt;T&gt;&gt;</code> from the inside out:</p> <ul> <li><code>T</code> is the actual data</li> <li><code>RefCell&lt;T&gt;</code> wraps the data with runtime borrow checking</li> <li><code>Rc&lt;RefCell&lt;T&gt;&gt;</code> stores a <code>RefCell&lt;T&gt;</code> inside an <code>Rc</code>-managed heap allocation and enables multiple owners.</li> </ul> <p>You will see this pattern everywhere in Rust code that needs shared mutable state.</p> <h2 id="the-problem-rc-cycles">The Problem: Rc Cycles</h2> <p><code>Rc</code> has a problem. If two <code>Rc</code> values reference each other, they form a cycle. Neither will ever have a reference count of zero. The memory leaks.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">rc</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Rc</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">cell</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RefCell</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Node</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> value</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> next</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Rc</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RefCell</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Node</span><span style="color: #89DCEB;">&gt;&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> a</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">RefCell</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Node</span><span style="color: #9399B2;"> {</span><span> value</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">,</span><span> next</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #9399B2;"> }));</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> b</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">RefCell</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Node</span><span style="color: #9399B2;"> {</span><span> value</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span> next</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #9399B2;"> }));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>a</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow_mut</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span>next </span><span style="color: #94E2D5;">=</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>b</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span>b</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow_mut</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span>next </span><span style="color: #94E2D5;">=</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>a</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// Now a and b point to each other. Neither will ever be dropped.</span></span></code></pre> <p>This is a memory leak. <code>Rc</code> cannot detect cycles.</p> <p>Now, a Git commit graph is a DAG (directed acyclic graph), but that does not automatically mean <code>Rc</code> is safe to use in every direction. The important distinction is between the commit graph and the ownership graph created by our smart pointers.</p> <p>Suppose a parent stores an <code>Rc</code> to its child, and the child stores an <code>Rc</code> back to its parent. The commit graph is still a DAG, but the ownership graph now contains a cycle. Neither node can ever reach a strong reference count of zero, so the memory leaks.</p> <p><code>Weak&lt;T&gt;</code> solves this problem. We make the graph edges non-owning references. The <code>HashMap</code> is the sole owner of every node through <code>Rc</code>, while the parent/child relationships are represented using <code>Weak</code>. When the <code>HashMap</code> is dropped, every strong reference disappears and the entire graph is freed correctly.</p> <h2 id="weak-non-owning-references">Weak: Non-Owning References</h2> <p><code>Weak&lt;T&gt;</code> is the solution. <code>Weak</code> is a version of <code>Rc</code> that does not own the value. It does not increment the strong reference count. The value can be dropped even while <code>Weak</code> references exist.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">rc</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">Rc</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Weak</span><span style="color: #9399B2;">};</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">cell</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RefCell</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> strong</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">42</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> weak</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">downgrade</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>strong</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// strong_count = 1, weak_count = 1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">drop</span><span style="color: #9399B2;">(</span><span>strong</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// strong_count = 0, data is freed</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> weak</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">upgrade</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>value</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Still alive: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> value</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Data was dropped&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>Rc::downgrade</code> creates a <code>Weak</code> reference from an <code>Rc</code>. <code>Weak::upgrade</code> tries to get back an <code>Option&lt;Rc&lt;T&gt;&gt;</code>. If the data has been dropped (all strong references are gone), <code>upgrade</code> returns <code>None</code>.</p> <p>The naming comes from strong references vs weak references. A strong reference keeps the value alive. A weak reference allows the value to be dropped.</p> <table><thead><tr><th>Pointer</th><th>Ownership</th><th>Can access data</th><th>Prevents drop</th><th>Use case</th></tr></thead><tbody> <tr><td><code>Rc&lt;T&gt;</code></td><td>Shared</td><td>Yes</td><td>Yes</td><td>Multiple owners</td></tr> <tr><td><code>Weak&lt;T&gt;</code></td><td>None</td><td>Via <code>upgrade</code></td><td>No</td><td>Break cycles, caches, graph edges</td></tr> </tbody></table> <p>This is exactly what we need for our commit graph. A parent commit can be referenced by many children through <code>Weak</code> pointers. The HashMap holds the strong references. When we finish traversing the graph, the HashMap is dropped, all strong counts hit zero, and all nodes are freed, even though they still have <code>Weak</code> edges pointing between them.</p> <h2 id="the-project-git-commit-graph-viewer">The Project: Git Commit Graph Viewer</h2> <p>Now that you understand <code>Box</code>, <code>Rc</code>, <code>RefCell</code>, and <code>Weak</code>, let's build a Git Commit Graph Viewer.</p> <p>Our program will:</p> <ul> <li>Accept a path to a <code>.git</code> directory</li> <li>Read and decompress every commit object from <code>.git/objects/</code></li> <li>Build a connected graph of <code>CommitNode</code> structs using <code>Rc&lt;RefCell&lt;&gt;&gt;</code></li> <li>Wire up parent and child edges as <code>Weak&lt;&gt;</code> references</li> <li>Render an ASCII graph showing the commit history with branch labels</li> </ul> <p>You already built a Git Object Store Reader in Phase 8. That project parsed commits and rendered <code>git log --oneline</code> output. In this project, we build on that code, but instead of a flat HashMap of disconnected commits, we build a <strong>fully connected graph</strong> where each node knows its parents and children through smart pointers.</p> <h2 id="project-setup">Project Setup</h2> <p>Open your terminal and run:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> new commit_graph</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> commit_graph</span></span></code></pre> <p>Now open <code>Cargo.toml</code> and add the dependency:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;">[</span><span>package</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>name</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;commit_graph&quot;</span></span> <span class="giallo-l"><span>version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.1.0&quot;</span></span> <span class="giallo-l"><span>edition</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;2024&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>dependencies</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>flate2</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&quot;</span></span></code></pre> <p>The only external dependency is <code>flate2</code> for zlib decompression. Everything else <code>Rc</code>, <code>RefCell</code>, <code>Weak</code>, <code>HashMap</code> comes from the standard library.</p> <p>Open <code>src/main.rs</code> and delete everything.</p> <h3 id="imports">Imports</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> flate2</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">read</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">ZlibDecoder</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">cell</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RefCell</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">collections</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">HashMap</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> HashSet</span><span style="color: #9399B2;">};</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span>fs</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">io</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Read</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">path</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Path</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">rc</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">Rc</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Weak</span><span style="color: #9399B2;">};</span></span></code></pre> <ul> <li><code>flate2::read::ZlibDecoder</code> decompresses Git's zlib-compressed object files</li> <li><code>std::cell::RefCell</code> provides interior mutability for our graph edges</li> <li><code>std::collections::HashMap</code> stores the node lookup (hash → <code>Rc&lt;RefCell&lt;CommitNode&gt;&gt;</code>)</li> <li><code>std::rc::{Rc, Weak}</code> provides shared ownership and non-owning references</li> </ul> <h3 id="the-commitnode-struct">The CommitNode Struct</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> CommitNode</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> hash</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> short_hash</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> timestamp</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> u64</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> parents</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> RefCell</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Weak</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RefCell</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">CommitNode</span><span style="color: #89DCEB;">&gt;&gt;&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> children</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> RefCell</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Weak</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RefCell</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">CommitNode</span><span style="color: #89DCEB;">&gt;&gt;&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Let me read this struct from the inside out:</p> <ul> <li><code>CommitNode</code> is a vertex in our graph. It represents one git commit.</li> <li><code>hash</code> is the full 40-character SHA-1 hash. <code>short_hash</code> is the first 7 characters for display.</li> <li><code>message</code> is the first line of the commit message.</li> <li><code>timestamp</code> is the Unix timestamp from the commit's author line.</li> </ul> <p>Now the key parts: <code>parents</code> and <code>children</code> are both <code>RefCell&lt;Vec&lt;Weak&lt;RefCell&lt;CommitNode&gt;&gt;&gt;&gt;</code>.</p> <ul> <li><code>Weak&lt;RefCell&lt;CommitNode&gt;&gt;</code> is a non-owning reference to another node in the graph. The node lives in a <code>HashMap</code> behind an <code>Rc</code>. The <code>Weak</code> points to it without keeping it alive.</li> <li><code>Vec&lt;Weak&lt;...&gt;&gt;</code> holds multiple such edges (a commit can have multiple parents and multiple children).</li> <li><code>RefCell&lt;Vec&lt;...&gt;&gt;</code> enables interior mutability. We can push edges into these <code>Vec</code>s even when we only have an immutable reference to the node.</li> </ul> <p>Why <code>RefCell</code>? Because after we create a <code>CommitNode</code> and store it behind <code>Rc</code>, we need to wire up its edges. The node already exists, the <code>Rc</code> is in the HashMap. Without <code>RefCell</code>, we would need <code>&amp;mut CommitNode</code> to push into the <code>Vec</code>s, and you cannot get <code>&amp;mut</code> from an <code>Rc</code>. With <code>RefCell</code>, we call <code>borrow_mut()</code> on the <code>RefCell</code>, which gives us runtime-checked mutable access to the <code>Vec</code>, and we push our <code>Weak</code> edges into it.</p> <h3 id="the-raw-commit">The Raw Commit</h3> <p>We need a temporary struct to hold the raw data we parse from git objects:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> RawCommit</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> parent_hashes</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> author</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> timestamp</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> u64</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>RawCommit</code> holds the data as it comes out of the object file. It stores parent hashes as <code>String</code>s (not references) because after we parse all commits, we do a second pass to resolve those strings into actual <code>Weak</code> references to the corresponding nodes.</p> <h3 id="reading-git-objects">Reading Git Objects</h3> <p>These functions are the same as in Phase 8. I will include them here with brief explanations so the code is self-contained.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> read_head</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">git_dir</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">Path</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> content</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> fs</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">read_to_string</span><span style="color: #9399B2;">(</span><span>git_dir</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;HEAD&quot;</span><span style="color: #9399B2;">))</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">ok</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>content</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">trim</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">())</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> resolve_ref</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">git_dir</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">Path</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> reference</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> reference</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">starts_with</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;ref: &quot;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> ref_path</span><span style="color: #94E2D5;"> = &amp;</span><span>reference</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">5</span><span style="color: #94E2D5;">..</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> fs</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">read_to_string</span><span style="color: #9399B2;">(</span><span>git_dir</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">(</span><span>ref_path</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">ok</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>s</span><span style="color: #94E2D5;">|</span><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">trim</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">())</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>reference</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">())</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> read_object</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">git_dir</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">Path</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> hash</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">u8</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> object_path</span><span style="color: #94E2D5;"> =</span><span> git_dir</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;objects&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>hash</span><span style="color: #9399B2;">[</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">])</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>hash</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">2</span><span style="color: #94E2D5;">..</span><span style="color: #9399B2;">]);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> compressed</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> fs</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">read</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>object_path</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">unwrap_or_else</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>_</span><span style="color: #94E2D5;">|</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Failed to read object: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> hash</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> decoder</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> ZlibDecoder</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>compressed</span><span style="color: #9399B2;">[</span><span style="color: #94E2D5;">..</span><span style="color: #9399B2;">]);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> decompressed</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> decoder</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">read_to_end</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span> decompressed</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">unwrap_or_else</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>_</span><span style="color: #94E2D5;">|</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Failed to decompress object: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> hash</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span> decompressed</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. <code>read_head</code> reads the <code>.git/HEAD</code> file to find out which branch we are on. <code>resolve_ref</code> follows a symbolic reference like <code>ref: refs/heads/main</code> to its actual commit hash. <code>read_object</code> constructs the path <code>.git/objects/XX/YYYY...</code>, reads the file, and decompresses it with zlib.</p> <h3 id="parsing-object-headers-and-commits">Parsing Object Headers and Commits</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> parse_object</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">data</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">[</span><span style="color: #CBA6F7;">u8</span><span style="color: #9399B2;">])</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #9399B2;"> (</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #9399B2;">[</span><span style="color: #CBA6F7;">u8</span><span style="color: #9399B2;">]) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> header_end</span><span style="color: #94E2D5;"> =</span><span> data</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">position</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|&amp;</span><span>b</span><span style="color: #94E2D5;">|</span><span> b</span><span style="color: #94E2D5;"> ==</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">expect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid object: no null byte&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> header</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_utf8</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>data</span><span style="color: #9399B2;">[</span><span style="color: #94E2D5;">..</span><span>header_end</span><span style="color: #9399B2;">])</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">expect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid object: header not valid UTF-8&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> content</span><span style="color: #94E2D5;"> = &amp;</span><span>data</span><span style="color: #9399B2;">[</span><span>header_end</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;">..</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> parts</span><span style="color: #94E2D5;"> =</span><span> header</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">splitn</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">, &#39; &#39;);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> obj_type</span><span style="color: #94E2D5;"> =</span><span> parts</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">next</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> _size</span><span style="color: #94E2D5;"> =</span><span> parts</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">next</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span>obj_type</span><span style="color: #9399B2;">,</span><span> content</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> parse_commit</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">content</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">[</span><span style="color: #CBA6F7;">u8</span><span style="color: #9399B2;">])</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> RawCommit</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> content_str</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_utf8</span><span style="color: #9399B2;">(</span><span>content</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">expect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid commit: not valid UTF-8&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> parent_hashes</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> author</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> timestamp</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> u64</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> message</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> in_message</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> line</span><span style="color: #CBA6F7;"> in</span><span> content_str</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">lines</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> in_message</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> !</span><span>message</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_empty</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #F5C2E7;">\n</span><span style="color: #9399B2;">&#39;);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push_str</span><span style="color: #9399B2;">(</span><span>line</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> continue</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_empty</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span> in_message</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> continue</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>hash</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">strip_prefix</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;parent &quot;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> parent_hashes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>author_line</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">strip_prefix</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;author &quot;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> author</span><span style="color: #94E2D5;"> =</span><span> author_line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>last_space</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> author_line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">rfind</span><span style="color: #9399B2;">(&#39; &#39;) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>prev_space</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> author_line</span><span style="color: #9399B2;">[</span><span style="color: #94E2D5;">..</span><span>last_space</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">rfind</span><span style="color: #9399B2;">(&#39; &#39;) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> ts_str</span><span style="color: #94E2D5;"> = &amp;</span><span>author_line</span><span style="color: #9399B2;">[</span><span>prev_space</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;">..</span><span>last_space</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>ts</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> ts_str</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">parse</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">u64</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span> timestamp</span><span style="color: #94E2D5;"> =</span><span> ts</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> RawCommit</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> parent_hashes</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> author</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> timestamp</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> message</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. <code>parse_object</code> splits the decompressed bytes into the header (before the null byte) and the content (after it). The header contains the object type and size. <code>parse_commit</code> walks through the lines of the commit content, collecting parent hashes, the author timestamp, and the commit message. We skip the <code>tree</code> line since we only care about the graph structure. The timestamp parsing extracts the Unix seconds from the author line, which looks like <code>author Name &lt;email&gt; 1234567890 +0000</code>.</p> <h3 id="reading-all-commits">Reading All Commits</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> read_all_commits</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">git_dir</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">Path</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> head_hash</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> HashMap</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> RawCommit</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> raw_commits</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> HashMap</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> read_commit_recursive</span><span style="color: #9399B2;">(</span><span>git_dir</span><span style="color: #9399B2;">,</span><span> head_hash</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span> raw_commits</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> raw_commits</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> read_commit_recursive</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> git_dir</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">Path</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> hash</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> raw_commits</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> HashMap</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> RawCommit</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> raw_commits</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">contains_key</span><span style="color: #9399B2;">(</span><span>hash</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> data</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> read_object</span><span style="color: #9399B2;">(</span><span>git_dir</span><span style="color: #9399B2;">,</span><span> hash</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span style="color: #9399B2;"> (</span><span>obj_type</span><span style="color: #9399B2;">,</span><span> content</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> parse_object</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>data</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> obj_type</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;commit&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> commit</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> parse_commit</span><span style="color: #9399B2;">(</span><span>content</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> parent</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>commit</span><span style="color: #94E2D5;">.</span><span>parent_hashes </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> read_commit_recursive</span><span style="color: #9399B2;">(</span><span>git_dir</span><span style="color: #9399B2;">,</span><span> parent</span><span style="color: #9399B2;">,</span><span> raw_commits</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> raw_commits</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span>hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span><span> commit</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Expected commit object, got </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> obj_type</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. <code>read_commit_recursive</code> walks the entire commit graph from a starting hash, recursively reading every parent. The <code>HashMap</code> acts as a cache: if we have already read a commit hash, we return immediately so we never read the same object twice. This handles the case where two branches share common ancestors, the shared history is parsed only once. After this function returns, <code>raw_commits</code> contains every commit reachable from <code>head_hash</code>.</p> <h3 id="reading-all-branches">Reading All Branches</h3> <p>To support rendering branch labels, we also read every branch reference:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> read_all_branches</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">git_dir</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">Path</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> branches</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> heads_dir</span><span style="color: #94E2D5;"> =</span><span> git_dir</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;refs&quot;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;heads&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>entries</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> fs</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">read_dir</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>heads_dir</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> entry</span><span style="color: #CBA6F7;"> in</span><span> entries</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">flatten</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> path</span><span style="color: #94E2D5;"> =</span><span> entry</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">path</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>name</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> path</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">file_name</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">and_then</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>n</span><span style="color: #94E2D5;">|</span><span> n</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_str</span><span style="color: #9399B2;">()) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>hash</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> fs</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">read_to_string</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>path</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> branches</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">((</span><span>name</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span><span> hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">trim</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">()));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> branches</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. <code>read_all_branches</code> reads loose local branch references from <code>.git/refs/heads/</code>. In many repositories, each local branch appears as a file containing the branch tip's commit hash. Git can also store references in <code>packed-refs</code>, but for simplicity this implementation only reads loose branch references.</p> <h3 id="building-the-graph-first-pass-creating-nodes">Building the Graph: First Pass - Creating Nodes</h3> <p>Now we get to the core of the article: building the graph using smart pointers. This happens in two passes.</p> <p>In the first pass, we create an <code>Rc&lt;RefCell&lt;CommitNode&gt;&gt;</code> for every raw commit and store it in a <code>HashMap</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> build_graph</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> raw_commits</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">HashMap</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> RawCommit</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> HashMap</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RefCell</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">CommitNode</span><span style="color: #89DCEB;">&gt;&gt;&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> nodes</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> HashMap</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RefCell</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">CommitNode</span><span style="color: #89DCEB;">&gt;&gt;&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> HashMap</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>hash</span><span style="color: #9399B2;">,</span><span> raw</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span> raw_commits</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> node</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">RefCell</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">CommitNode</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> hash</span><span style="color: #94E2D5;">:</span><span> hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> short_hash</span><span style="color: #94E2D5;">:</span><span> hash</span><span style="color: #9399B2;">[</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">7</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">:</span><span> raw</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">message</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">lines</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">next</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap_or</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;&quot;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> timestamp</span><span style="color: #94E2D5;">:</span><span> raw</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">timestamp</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> parents</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;"> RefCell</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">()),</span></span> <span class="giallo-l"><span> children</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;"> RefCell</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">()),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }));</span></span> <span class="giallo-l"><span> nodes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span>hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(),</span><span> node</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> nodes</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. For each raw commit, we create an <code>Rc::new(RefCell::new(CommitNode { ... }))</code>. The <code>RefCell</code> enables interior mutability so we can later wire up edges. The <code>Rc</code> enables shared ownership: the HashMap holds one strong reference, and later each child will hold a <code>Weak</code> reference pointing back to the parent. Both <code>parents</code> and <code>children</code> start as empty <code>Vec</code>s, we populate them in the second pass.</p> <p>Let me trace the memory layout. The <code>HashMap</code> key is a <code>String</code> (the commit hash). The value is an <code>Rc&lt;RefCell&lt;CommitNode&gt;&gt;</code>. The <code>Rc</code> stored in the HashMap points to a heap allocation containing the <code>RefCell&lt;CommitNode&gt;</code>. The <code>CommitNode</code> itself lives inside that allocation.</p> <p>Fields such as <code>String</code> and <code>Vec</code> are stored inline inside the <code>CommitNode</code>, but they manage their own heap allocations for their contents. For example, the <code>hash</code> field contains a <code>String</code> value inside the struct, while the actual string bytes live in a separate heap allocation. Likewise, <code>parents</code> and <code>children</code> contain <code>Vec</code>s whose elements live in separate heap allocations.</p> <h3 id="building-the-graph-second-pass-wiring-edges">Building the Graph: Second Pass - Wiring Edges</h3> <p>In the second pass, we walk through every node and wire up its parent and child edges using <code>Weak</code> references:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> wire_edges</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> nodes</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">HashMap</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RefCell</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">CommitNode</span><span style="color: #89DCEB;">&gt;&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> raw_commits</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">HashMap</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> RawCommit</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>hash</span><span style="color: #9399B2;">,</span><span> node</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span> nodes</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>raw</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> raw_commits</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span>hash</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> parent_hash</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>raw</span><span style="color: #94E2D5;">.</span><span>parent_hashes </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>parent_node</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> nodes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span>parent_hash</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Add parent as Weak reference to current node</span></span> <span class="giallo-l"><span> node</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span>parents</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">borrow_mut</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">downgrade</span><span style="color: #9399B2;">(</span><span>parent_node</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Add current node as child (Weak) to parent node</span></span> <span class="giallo-l"><span> parent_node</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span>children</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">borrow_mut</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">downgrade</span><span style="color: #9399B2;">(</span><span>node</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. This is where <code>RefCell</code>'s interior mutability shines.</p> <p>We iterate over every node in the graph. For each node, we look at its raw commit to find its parent hashes. For each parent hash, we look up the parent's <code>Rc&lt;RefCell&lt;CommitNode&gt;&gt;</code> in the <code>nodes</code> HashMap.</p> <p>Then we do two things:</p> <ol> <li> <p><strong>Parent edge</strong>: We push a <code>Weak</code> reference to the parent into the current node's <code>parents</code> Vec. We get mutable access to the Vec through <code>node.borrow().parents.borrow_mut()</code>. The first <code>.borrow()</code> gets an immutable reference to the <code>RefCell&lt;CommitNode&gt;</code>. The second <code>.borrow_mut()</code> gets mutable access to the <code>Vec</code> inside it.</p> </li> <li> <p><strong>Child edge</strong>: We push a <code>Weak</code> reference to the current node into the parent node's <code>children</code> Vec. This is the reverse direction. After this second pass, every node knows both its parents and its children.</p> </li> </ol> <p><code>Rc::downgrade</code> takes an <code>&amp;Rc&lt;T&gt;</code> and returns a <code>Weak&lt;T&gt;</code>. The strong count does not change. The weak count increments. This is important: the <code>HashMap</code> is the only thing keeping nodes alive through strong references. The edges are all <code>Weak</code>, so they do not prevent any node from being dropped if we remove it from the <code>HashMap</code>.</p> <p>Let me also highlight why we need <code>RefCell</code> here. We already have an <code>Rc&lt;RefCell&lt;CommitNode&gt;&gt;</code> from the HashMap. We could also get the node by borrowing the HashMap: <code>nodes.get(parent_hash)</code> gives us an <code>Option&lt;&amp;Rc&lt;RefCell&lt;CommitNode&gt;&gt;&gt;</code>. But we cannot call <code>parent_node.borrow_mut()</code> directly on the CommitNode because we only have a shared reference through <code>Rc</code>. The <code>RefCell</code> layer is what gives us the ability to call <code>borrow()</code> and <code>borrow_mut()</code> on a shared reference.</p> <h3 id="walking-the-graph">Walking the Graph</h3> <p>Now let's write functions that walk the graph using <code>Weak::upgrade</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> walk_first_parent_chain</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> nodes</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">HashMap</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RefCell</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">CommitNode</span><span style="color: #89DCEB;">&gt;&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> start_hash</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> path</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> current_hash</span><span style="color: #94E2D5;"> =</span><span> start_hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> loop</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>node</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> nodes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>current_hash</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> n</span><span style="color: #94E2D5;"> =</span><span> node</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> path</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>current_hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> n</span><span style="color: #94E2D5;">.</span><span>parents</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">first</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>first_parent</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> match</span><span> first_parent</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">upgrade</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>parent</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> current_hash</span><span style="color: #94E2D5;"> =</span><span> parent</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span>hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> path</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. This function walks the first-parent chain from a starting hash to the root commit. For each commit, it:</p> <ol> <li>Looks up the node in the <code>nodes</code> HashMap</li> <li>Borrows it to access <code>parents</code></li> <li>Takes the first parent (the one in the <code>first()</code> position)</li> <li>Calls <code>upgrade()</code> on the <code>Weak</code> reference. If the parent node still exists (strong count &gt; 0), <code>upgrade</code> returns <code>Some(Rc&lt;RefCell&lt;CommitNode&gt;&gt;)</code>. If the parent was dropped (strong count == 0), it returns <code>None</code>.</li> <li>Extracts the parent's hash and continues the loop</li> </ol> <p>The <code>upgrade()</code> call is the bridge between the <code>Weak</code> world and the <code>Rc</code> world. Since the HashMap holds all strong references, every node is guaranteed to exist. But the type system forces us to handle the <code>Option</code> case anyway, because <code>Weak&lt;T&gt;</code> makes no compile-time guarantee that the allocation is still alive.</p> <h3 id="rendering-the-graph">Rendering the Graph</h3> <p>Now let's render the commit graph as ASCII art. The output is inspired by <code>git log --graph --oneline --all</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #94E2D5;">*</span><span> 7a8b9c0 (</span><span style="color: #89B4FA;font-style: italic;">HEAD</span><span> -</span><span style="color: #94E2D5;">&gt;</span><span style="color: #A6E3A1;"> main</span><span>) Latest commit</span></span> <span class="giallo-l"><span style="color: #94E2D5;">*</span><span> 1b2c3d4 Add feature X</span></span> <span class="giallo-l"><span style="color: #94E2D5;">|</span><span style="color: #F5C2E7;">\</span></span> <span class="giallo-l"><span style="color: #94E2D5;">|</span><span style="color: #89B4FA;font-style: italic;"> *</span><span style="color: #A6E3A1;"> 5e6f7g8</span><span> (feature) Fix bug in sidebar</span></span> <span class="giallo-l"><span style="color: #94E2D5;">|</span><span style="color: #89B4FA;font-style: italic;">/</span></span> <span class="giallo-l"><span style="color: #94E2D5;">*</span><span> 1a2b3c4 Initial commit</span></span></code></pre> <p>The <code>*</code> marks a commit. The <code>|\</code> marks a merge point. The <code>| *</code> lines represent commits that belong to a merged side branch. The <code>|/</code> marks where that branch reconnects to the main line in our simplified renderer.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> render_graph</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> nodes</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">HashMap</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RefCell</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">CommitNode</span><span style="color: #89DCEB;">&gt;&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> head_hash</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> branches</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">[(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">)],</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> branch_map</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> HashMap</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> branches</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;">(</span><span>name</span><span style="color: #9399B2;">,</span><span> hash</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;"> (</span><span>hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">as_str</span><span style="color: #9399B2;">(),</span><span> name</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">as_str</span><span style="color: #9399B2;">()))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> main_line</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> walk_first_parent_chain</span><span style="color: #9399B2;">(</span><span>nodes</span><span style="color: #9399B2;">,</span><span> head_hash</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> main_set</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> HashSet</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> main_line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>h</span><span style="color: #94E2D5;">|</span><span> h</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">as_str</span><span style="color: #9399B2;">())</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> shown</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> HashMap</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> bool</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> HashMap</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> hash</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>main_line</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>node</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> nodes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span>hash</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> n</span><span style="color: #94E2D5;"> =</span><span> node</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> shown</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span>hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(),</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Check if this commit has additional parents (merge commit)</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> parents</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Rc</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RefCell</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">CommitNode</span><span style="color: #89DCEB;">&gt;&gt;&gt;</span><span style="color: #94E2D5;"> =</span><span> n</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span>parents</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">filter_map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>w</span><span style="color: #94E2D5;">|</span><span> w</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">upgrade</span><span style="color: #9399B2;">())</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> parents</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &gt;</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // This is a merge commit. Show merged branches before showing the merge.</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> parent</span><span style="color: #CBA6F7;"> in</span><span> parents</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">skip</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> p</span><span style="color: #94E2D5;"> =</span><span> parent</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> side_line</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> walk_first_parent_chain</span><span style="color: #9399B2;">(</span><span>nodes</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>p</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">hash</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;|</span><span style="color: #F5C2E7;">\\</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> side_hash</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>side_line</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> main_set</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">contains</span><span style="color: #9399B2;">(</span><span>side_hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">as_str</span><span style="color: #9399B2;">()) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> label</span><span style="color: #94E2D5;"> =</span><span> branch_map</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span>side_hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">as_str</span><span style="color: #9399B2;">())</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>name</span><span style="color: #94E2D5;">|</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot; (</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">)&quot;</span><span style="color: #9399B2;">,</span><span> name</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">unwrap_or_default</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>side_node</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> nodes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span>side_hash</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> sn</span><span style="color: #94E2D5;"> =</span><span> side_node</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;| * </span><span style="color: #9399B2;">{} {}{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> sn</span><span style="color: #94E2D5;">.</span><span>short_hash</span><span style="color: #9399B2;">,</span><span> sn</span><span style="color: #94E2D5;">.</span><span>message</span><span style="color: #9399B2;">,</span><span> label</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> shown</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span>side_hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(),</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;|/&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> label</span><span style="color: #94E2D5;"> =</span><span> branch_map</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span>hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">as_str</span><span style="color: #9399B2;">())</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>name</span><span style="color: #94E2D5;">|</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot; (</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">)&quot;</span><span style="color: #9399B2;">,</span><span> name</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">unwrap_or_default</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;* </span><span style="color: #9399B2;">{} {}{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> n</span><span style="color: #94E2D5;">.</span><span>short_hash</span><span style="color: #9399B2;">,</span><span> n</span><span style="color: #94E2D5;">.</span><span>message</span><span style="color: #9399B2;">,</span><span> label</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Show any branches whose tips weren&#39;t on the main line</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>branch_name</span><span style="color: #9399B2;">,</span><span> branch_hash</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span> branches</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> !</span><span>shown</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">contains_key</span><span style="color: #9399B2;">(</span><span>branch_hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">as_str</span><span style="color: #9399B2;">()) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>_node</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> nodes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span>branch_hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">as_str</span><span style="color: #9399B2;">()) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> side_line</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> walk_first_parent_chain</span><span style="color: #9399B2;">(</span><span>nodes</span><span style="color: #9399B2;">,</span><span> branch_hash</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #F5C2E7;">\n</span><span style="color: #A6E3A1;"> (unconnected branch &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39;)&quot;</span><span style="color: #9399B2;">,</span><span> branch_name</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> side_hash</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>side_line</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>side_node</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> nodes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span>side_hash</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> sn</span><span style="color: #94E2D5;"> =</span><span> side_node</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot; * </span><span style="color: #9399B2;">{} {}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> sn</span><span style="color: #94E2D5;">.</span><span>short_hash</span><span style="color: #9399B2;">,</span><span> sn</span><span style="color: #94E2D5;">.</span><span>message</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> shown</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">contains_key</span><span style="color: #9399B2;">(</span><span>side_hash</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Print graph statistics</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #F5C2E7;">\n</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;-&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">repeat</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">50</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Graph statistics:&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot; Total commits: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> nodes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot; Branch refs: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> branches</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> merge_count</span><span style="color: #94E2D5;"> =</span><span> nodes</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">values</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">filter</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>node</span><span style="color: #94E2D5;">|</span><span> node</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">parents</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &gt;</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">count</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot; Merge commits: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> merge_count</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> root_count</span><span style="color: #94E2D5;"> =</span><span> nodes</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">values</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">filter</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>node</span><span style="color: #94E2D5;">|</span><span> node</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">parents</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_empty</span><span style="color: #9399B2;">())</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">count</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot; Root commits: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> root_count</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> timestamps</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">u64</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> nodes</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">values</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>node</span><span style="color: #94E2D5;">|</span><span> node</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">borrow</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">timestamp</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">Some</span><span style="color: #9399B2;">(</span><span>min</span><span style="color: #9399B2;">),</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>max</span><span style="color: #9399B2;">))</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span>timestamps</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">min</span><span style="color: #9399B2;">(),</span><span> timestamps</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">max</span><span style="color: #9399B2;">()) {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot; Oldest commit: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> (Unix epoch)&quot;</span><span style="color: #9399B2;">,</span><span> min</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot; Newest commit: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> (Unix epoch)&quot;</span><span style="color: #9399B2;">,</span><span> max</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. The renderer walks the first-parent chain from HEAD (the "main line"). For each commit on the main line, it checks if the commit is a merge commit (has more than one parent). If it does, it walks the first-parent chain of each additional parent and prints them as side branches with pipe characters.</p> <p>The key detail is <code>main_set: HashSet&lt;&amp;str&gt;</code>, a set of all hashes on the main line. When rendering side branches, if we hit a commit that's already in the main line (the merge base), we <code>break</code>. This prevents shared ancestors from appearing twice. Only commits unique to the feature branch are shown in the <code>| *</code> section.</p> <p>The <code>branch_map</code> is a lookup from commit hash to branch name. We use it to label commits that are at the tip of a branch. For example, if <code>refs/heads/main</code> points to hash <code>7a8b9c0</code>, we label that commit <code>(main)</code>.</p> <p>After rendering the main line, we check for branches whose tips weren't on the main line. This can happen if you have an unmerged branch. We render those separately.</p> <p>Finally, we print graph statistics and use the <code>timestamp</code> field (extracted from the commit's author line) to show the oldest and newest commit.</p> <h3 id="demonstrating-refcounts">Demonstrating RefCounts</h3> <p>Let's write a small function that demonstrates the reference counting in action:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> print_refcounts</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">nodes</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">HashMap</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RefCell</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">CommitNode</span><span style="color: #89DCEB;">&gt;&gt;&gt;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Reference counts (nodes with at least one weak edge):&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>hash</span><span style="color: #9399B2;">,</span><span> node</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span> nodes</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> strong</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">strong_count</span><span style="color: #9399B2;">(</span><span>node</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> weak</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Rc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">weak_count</span><span style="color: #9399B2;">(</span><span>node</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> weak</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;</span><span style="color: #9399B2;"> {}</span><span style="color: #A6E3A1;"> has </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> strong, </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> weak references&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &amp;</span><span>hash</span><span style="color: #9399B2;">[</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">7</span><span style="color: #9399B2;">],</span><span> strong</span><span style="color: #9399B2;">,</span><span> weak</span></span> <span class="giallo-l"><span style="color: #9399B2;"> );</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. <code>Rc::strong_count</code> tells us how many <code>Rc</code> handles point to this allocation. In our case, this should always be 1 because only the HashMap holds an <code>Rc</code>. All edges are <code>Weak</code>. <code>Rc::weak_count</code> tells us how many <code>Weak</code> handles point to this allocation. For example, a commit with one parent and two children may have three weak references associated with it: one stored in its own <code>parents</code> list and two stored in its children's <code>parents</code> lists. The exact weak count depends on the structure of the graph.</p> <h3 id="putting-it-all-together-in-main">Putting It All Together in main</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> args</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">env</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">args</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> git_dir</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if</span><span> args</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &gt;</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Path</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>args</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">])</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_path_buf</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Path</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;.git&quot;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_path_buf</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> head</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #89B4FA;font-style: italic;"> read_head</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>git_dir</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>h</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> h</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> eprintln!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Error: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> is not a git repository (no HEAD file)&quot;</span><span style="color: #9399B2;">,</span><span> git_dir</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">display</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> head_hash</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #89B4FA;font-style: italic;"> resolve_ref</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>git_dir</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>head</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>h</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> h</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> eprintln!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Error: failed to resolve HEAD reference &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39;&quot;</span><span style="color: #9399B2;">,</span><span> head</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> branches</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> read_all_branches</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>git_dir</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Reading commits from </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">...&quot;</span><span style="color: #9399B2;">,</span><span> git_dir</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">display</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> raw_commits</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> read_all_commits</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>git_dir</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>head_hash</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Parsed </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> commits.</span><span style="color: #F5C2E7;">\n</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> raw_commits</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Step 1: Create nodes (first pass)</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> graph</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> build_graph</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>raw_commits</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Step 2: Wire edges (second pass, uses interior mutability)</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> wire_edges</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>graph</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>raw_commits</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Show ref counts before rendering</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> print_refcounts</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>graph</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Render the graph</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #F5C2E7;">\n</span><span style="color: #A6E3A1;">Commit Graph:</span><span style="color: #F5C2E7;">\n</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> render_graph</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>graph</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>head_hash</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>branches</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. <code>main</code> reads command-line arguments, resolves HEAD, and reads all branches. If the <code>.git</code> directory doesn't exist or HEAD can't be resolved, it prints a clear error and exits gracefully instead of panicking. Then it parses all commits, builds the graph in two passes, prints reference counts, and renders the graph. The two-pass approach for <code>build_graph</code> and <code>wire_edges</code> is the key pattern: you cannot wire edges until all nodes exist, because a parent hash can only be resolved to a <code>Weak</code> reference if the parent node's <code>Rc</code> already exists in the HashMap.</p> <h3 id="running-the-project">Running The Project</h3> <p>Type this in your terminal:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> run -- /path/to/some/.git</span></span></code></pre> <p>Or from inside a git repository:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> run</span></span></code></pre> <p>You should see output like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Reading</span><span style="color: #A6E3A1;"> commits from .git...</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Parsed</span><span style="color: #FAB387;"> 12</span><span style="color: #A6E3A1;"> commits.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Reference</span><span style="color: #A6E3A1;"> counts:</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> a1b2c3d</span><span style="color: #A6E3A1;"> has</span><span style="color: #FAB387;"> 1</span><span style="color: #A6E3A1;"> strong,</span><span style="color: #FAB387;"> 3</span><span style="color: #A6E3A1;"> weak references</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> d4e5f6g</span><span style="color: #A6E3A1;"> has</span><span style="color: #FAB387;"> 1</span><span style="color: #A6E3A1;"> strong,</span><span style="color: #FAB387;"> 2</span><span style="color: #A6E3A1;"> weak references</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> 7a8b9c0</span><span style="color: #A6E3A1;"> has</span><span style="color: #FAB387;"> 1</span><span style="color: #A6E3A1;"> strong,</span><span style="color: #FAB387;"> 1</span><span style="color: #A6E3A1;"> weak references</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Commit</span><span style="color: #A6E3A1;"> Graph:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #94E2D5;">*</span><span> 7a8b9c0 (</span><span style="color: #89B4FA;font-style: italic;">main</span><span>) Latest commit</span></span> <span class="giallo-l"><span style="color: #94E2D5;">*</span><span> 1b2c3d4 Add feature X</span></span> <span class="giallo-l"><span style="color: #94E2D5;">|</span><span style="color: #F5C2E7;">\</span></span> <span class="giallo-l"><span style="color: #94E2D5;">|</span><span style="color: #89B4FA;font-style: italic;"> *</span><span style="color: #A6E3A1;"> 5e6f7g8</span><span> (feature) Fix bug in sidebar</span></span> <span class="giallo-l"><span style="color: #94E2D5;">|</span><span style="color: #89B4FA;font-style: italic;">/</span></span> <span class="giallo-l"><span style="color: #94E2D5;">*</span><span> 1a2b3c4 Refactor utils</span></span> <span class="giallo-l"><span style="color: #94E2D5;">*</span><span> f8e7d6c Initial commit</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">--------------------------------------------------</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Graph</span><span style="color: #A6E3A1;"> statistics:</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Total</span><span style="color: #A6E3A1;"> commits:</span><span style="color: #FAB387;"> 12</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Branch</span><span style="color: #A6E3A1;"> refs:</span><span style="color: #FAB387;"> 2</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Merge</span><span style="color: #A6E3A1;"> commits:</span><span style="color: #FAB387;"> 1</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Root</span><span style="color: #A6E3A1;"> commits:</span><span style="color: #FAB387;"> 1</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Oldest</span><span style="color: #A6E3A1;"> commit:</span><span style="color: #FAB387;"> 1746316800</span><span> (Unix</span><span style="color: #A6E3A1;"> epoch</span><span>)</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Newest</span><span style="color: #A6E3A1;"> commit:</span><span style="color: #FAB387;"> 1748736000</span><span> (Unix</span><span style="color: #A6E3A1;"> epoch</span><span>)</span></span></code></pre> <p>The first parent of the merge commit <code>1b2c3d4</code> is <code>1a2b3c4</code> (the main line), so that's where the main line continues. The second parent is <code>5e6f7g8</code> (the feature branch), which is rendered as a side branch. The <code>main_set</code> check ensures only the unique feature branch commits appear under <code>| *</code>, shared ancestors stay on the main line.</p> <h2 id="how-it-all-fits-together">How It All Fits Together</h2> <p>Let's trace through the lifecycle of a commit node in our graph:</p> <ol> <li> <p><strong>Creation</strong>: <code>Rc::new(RefCell::new(CommitNode { ... }))</code> allocates the node on the heap. The <code>Rc</code> lives in the HashMap, which is the sole strong owner. Strong count = 1.</p> </li> <li> <p><strong>Wiring</strong>: During <code>wire_edges</code>, for a commit with one parent and two children, <code>Rc::downgrade</code> is called three times: once for the parent edge in this node, and twice for the child edges from the parent and child nodes into this node. Strong count stays at 1. Weak count becomes 3.</p> </li> <li> <p><strong>Walking</strong>: When <code>render_graph</code> traverses the graph, each call to <code>walk_first_parent_chain</code> calls <code>upgrade()</code> on <code>Weak</code> handles. Each <code>upgrade()</code> temporarily increments the strong count (so the node cannot be dropped mid-traversal), gives us an <code>Rc&lt;RefCell&lt;CommitNode&gt;&gt;</code>, lets us borrow and read it, then the temporary <code>Rc</code> is dropped and the strong count returns to 1.</p> </li> <li> <p><strong>Cleanup</strong>: When <code>main</code> returns, the <code>HashMap</code> is dropped, which drops all its keys (Strings) and values (Rcs). The last strong reference to each node is dropped. Strong count hits 0 for every node. All nodes are freed. The <code>Weak</code> handles in parents and children become invalid. Any future <code>upgrade()</code> would return <code>None</code>.</p> </li> </ol> <h2 id="conclusion">Conclusion</h2> <p>In this post, you learned about Rust's smart pointers: <code>Box&lt;T&gt;</code>, <code>Rc&lt;T&gt;</code>, <code>RefCell&lt;T&gt;</code>, and <code>Weak&lt;T&gt;</code>. You learned how <code>Rc&lt;RefCell&lt;T&gt;&gt;</code> provides shared mutable state in single-threaded code, and how <code>Weak&lt;T&gt;</code> enables non-owning references that do not prevent deallocation. You built a Git Commit Graph Viewer that reads real <code>.git</code> directories, parses commit objects, builds a connected graph where each node knows its parents and children through <code>Weak</code> edges, and renders an ASCII visualization of your commit history.</p> <p>The smart pointer family has one more member we did not cover: <code>Arc&lt;T&gt;</code>, the atomic reference counter for multi-threaded code. We will cover <code>Arc</code> together with <code>Mutex</code> and concurrency in the next article, where we build a Thread Pool from Scratch.</p> <p>If you like reading this, please subscribe and share this with others. It will really help me and motivate me to keep publishing more such articles.</p> 2026-05-30T00:00:00+00:00 2026-05-30T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/learn-bevy-states-timers-by-building-snake/ <p>In this post, we are going to build <strong>Snake</strong>, the classic arcade game where you guide a growing snake to eat food while avoiding walls and yourself. If you read the Bevy Pong article, you already know the basics of ECS, queries, and resources. Now we level up.</p> <p>We'll learn about <strong>timers</strong> for tick-based movement, <strong>game states</strong> to manage playing and game-over screens, <strong>grid-based movement</strong> that constrains objects to discrete positions, <strong>movement queuing</strong> so the snake doesn't accidentally reverse into itself, and <strong>score tracking</strong> with state transitions.</p> <p>Get the full source code from <a rel="external" href="https://github.com/MrSheerluck/bevy-snake">here</a>. Published game link is <a rel="external" href="https://mrsheerluck.itch.io/snake-with-bevy-engine">here</a>.</p> <h3 id="new-concepts">New Concepts</h3> <p>Before writing any code, let's understand the new ideas we haven't seen yet.</p> <p><strong>Timers.</strong> In Pong, the ball moved continuously every frame by adding <code>velocity * delta</code>. Snake is different. The snake moves one cell at a time at a fixed rate. It doesn't slide smoothly, it teleports to the next cell every N milliseconds. This is called <strong>tick-based</strong> movement. Bevy provides a <code>Timer</code> type. You create it with a duration, call <code>tick(delta)</code> every frame, and when <code>just_finished()</code> returns true, it's time to move the snake. Reset and repeat.</p> <p><strong>Game states.</strong> Snake has two distinct modes: <strong>playing</strong> (the game is active) and <strong>game over</strong> (the player lost). In each mode, different systems should run. During game over, the snake shouldn't move and input should be different. Bevy's <strong>state system</strong> lets us define states and attach systems to specific ones. Only systems whose state matches the current state run.</p> <p><strong>Grid coordinates.</strong> Pong used continuous positions, the ball could be at x = 173.42 pixels. Snake uses a discrete grid. Every object sits on a <code>(col, row)</code> cell. We convert grid positions to world positions using a simple formula.</p> <p><strong>Movement queuing.</strong> Here is a classic Snake bug: the player presses Right then Down very quickly within one tick. If you change direction immediately, the snake goes right, then the same tick processes Down and the snake turns down. But what if the player pressed Left then Right? The snake reverses into itself and dies. We need to have a fix for this: a <strong>queue</strong> of directions. Each tick, pop one direction off the queue.</p> <h3 id="project-setup">Project Setup</h3> <p>Open your terminal and create a new Rust project:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo new bevy_snake</span></span> <span class="giallo-l"><span>cd bevy_snake</span></span></code></pre> <p>Now open <code>Cargo.toml</code> and replace its contents with:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;">[</span><span>package</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>name</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;bevy_snake&quot;</span></span> <span class="giallo-l"><span>version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.1.0&quot;</span></span> <span class="giallo-l"><span>edition</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;2024&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>dependencies</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>bevy</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.18&quot;</span><span style="color: #9399B2;">,</span><span> features</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> [</span><span style="color: #A6E3A1;">&quot;wav&quot;</span><span style="color: #9399B2;">] }</span></span> <span class="giallo-l"><span>rand</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.8&quot;</span></span></code></pre> <p>We add <code>rand</code> because we need random positions for food. We enable the <code>wav</code> feature for Bevy audio support. We pin <code>rand</code> to <code>0.8</code> deliberately. Bevy 0.18's internal rand dependency was upgraded in 0.17 with breaking API changes, and <code>0.8</code> keeps our usage stable.</p> <p>Now run:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo build</span></span></code></pre> <p>This will take a few minutes. Bevy is a large engine.</p> <h3 id="the-skeleton-constants-and-window">The Skeleton: Constants and Window</h3> <p>Open <code>src/main.rs</code> and start with this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> bevy</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">prelude</span><span style="color: #94E2D5;">::*</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">collections</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">VecDeque</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span style="color: #FAB387;"> GRID_WIDTH</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 20</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span style="color: #FAB387;"> GRID_HEIGHT</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 20</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span style="color: #FAB387;"> CELL_SIZE</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 30</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span style="color: #FAB387;"> SNAKE_MOVE_INTERVAL</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">15</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> App</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">add_plugins</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">DefaultPlugins</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">set</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">WindowPlugin</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> primary_window</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Window</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> title</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;Snake&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> resolution</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;"> bevy</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">window</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">WindowResolution</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">600</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 680</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> resizable</span><span style="color: #94E2D5;">:</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ..</span><span style="color: #89B4FA;font-style: italic;">default</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }),</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ..</span><span style="color: #89B4FA;font-style: italic;">default</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">add_systems</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Startup</span><span style="color: #9399B2;">,</span><span> setup</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">run</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> setup</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">mut</span><span style="color: #EBA0AC;"> commands</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Commands</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> asset_server</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Res</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AssetServer</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Camera2d</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Let me explain the constants.</p> <p><code>GRID_WIDTH</code> and <code>GRID_HEIGHT</code> are both 20, a 20x20 grid. <code>CELL_SIZE</code> is 30 pixels per cell. The play area is 20 * 30 = 600 pixels square. <code>SNAKE_MOVE_INTERVAL</code> is 0.15 seconds between each snake movement.</p> <p>Note that <code>setup</code> takes <code>asset_server: Res&lt;AssetServer&gt;</code> from the start. We need it to load sound files, and Bevy injects it automatically as a system parameter.</p> <p>Run <code>cargo run</code>. You should see a dark grey window.</p> <h3 id="grid-position-component">Grid Position Component</h3> <p>Every object in Snake lives on a discrete grid cell. Let's define a component for that:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Component</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Clone</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Copy</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> PartialEq</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Eq</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Debug</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> row</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>#[derive(Component)]</code> registers it as a Bevy component. <code>Clone</code> and <code>Copy</code> let us pass it around easily. <code>PartialEq</code> lets us compare positions, we use that for collision detection.</p> <h3 id="direction-and-helpers">Direction and Helpers</h3> <p>Snake has four directions:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Clone</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Copy</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> PartialEq</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Eq</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Debug</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Up</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Down</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Left</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Right</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>We also need a function to convert grid positions to world positions (pixels on screen):</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> grid_to_world</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">pos</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec3</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> half_w</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> GRID_WIDTH</span><span style="color: #CBA6F7;"> as f32</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> CELL_SIZE</span><span style="color: #94E2D5;"> /</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> half_h</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> GRID_HEIGHT</span><span style="color: #CBA6F7;"> as f32</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> CELL_SIZE</span><span style="color: #94E2D5;"> /</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Vec3</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span> pos</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">col </span><span style="color: #CBA6F7;">as f32</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> CELL_SIZE</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> CELL_SIZE</span><span style="color: #94E2D5;"> /</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> -</span><span> half_w</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> pos</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">row </span><span style="color: #CBA6F7;">as f32</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> CELL_SIZE</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> CELL_SIZE</span><span style="color: #94E2D5;"> /</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> -</span><span> half_h</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> )</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The math: <code>col * CELL_SIZE</code> gives the left edge of the cell. Adding <code>CELL_SIZE / 2</code> centers us in the cell. Subtracting <code>half_w</code> shifts the whole grid so the center of the screen is the center of the grid. Cell <code>(10, 10)</code> is right in the middle.</p> <h3 id="marker-components">Marker Components</h3> <p>Add these marker components to tag entities so we can find them in queries:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Component</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> SnakeSegment</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Component</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> FoodSprite</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Component</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> ScoreText</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Component</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> GameOverText</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Component</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> ScorePop</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Timer</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Component</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Particle</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> velocity</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec2</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> lifetime</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Timer</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>These are the same pattern as <code>ScoreText</code> in Pong, empty structs (or small structs) that act as labels or lightweight state on entities. <code>ScorePop</code> and <code>Particle</code> carry per-entity timer and physics data rather than living in a global resource, because multiple of them can exist simultaneously.</p> <h3 id="resources">Resources</h3> <p>The game data lives in resources. In Pong we had a <code>Score</code> resource. Snake needs more:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Resource</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Snake</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> segments</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">GridPosition</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> direction</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Resource</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Food</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">GridPosition</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Resource</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> MoveTimer</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Timer</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Resource</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> DirectionQueue</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">VecDeque</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Direction</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Resource</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Score</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">u32</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Resource</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> ScreenShake</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Timer</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Resource</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> EatSound</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Handle</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AudioSource</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Resource</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> DieSound</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Handle</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AudioSource</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">);</span></span></code></pre> <p>Let me explain each one.</p> <p><strong><code>Snake</code></strong> holds the logical state of the snake. <code>segments</code> is a <code>Vec&lt;GridPosition&gt;</code> where index 0 is the head. <code>direction</code> is which way the snake is currently moving.</p> <p><strong><code>Food</code></strong> is a newtype around a single <code>GridPosition</code>. Where the food sits on the grid.</p> <p><strong><code>MoveTimer</code></strong> wraps a Bevy <code>Timer</code>. We tick it every frame. When it finishes, the snake moves one cell.</p> <p><strong><code>DirectionQueue</code></strong> wraps a <code>VecDeque&lt;Direction&gt;</code>. When the player presses a key, we push onto this queue. Each tick, we pop one direction off.</p> <p><strong><code>Score</code></strong> is the player's score. Starts at 0.</p> <p><strong><code>ScreenShake</code></strong> wraps a <code>Timer</code>. When the player dies, we reset it. While it runs, <code>apply_screenshake</code> offsets the camera randomly each frame.</p> <p><strong><code>EatSound</code></strong> and <strong><code>DieSound</code></strong> hold handles to loaded audio assets. We load them once in <code>setup</code> and clone the handle whenever we want to play them.</p> <h3 id="game-state">Game State</h3> <p>Add this to define our two game modes:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">States</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Default</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Clone</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Eq</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> PartialEq</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Hash</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Debug</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> GameState</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">default</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Playing</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> GameOver</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>#[derive(States)]</code> tells Bevy this enum defines game states. <code>#[default]</code> on <code>Playing</code> means the game starts in Playing mode.</p> <p>Register it in <code>main()</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> App</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">add_plugins</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">DefaultPlugins</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">set</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">WindowPlugin</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> primary_window</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Window</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> title</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;Snake&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> resolution</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;"> bevy</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">window</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">WindowResolution</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">600</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 680</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> resizable</span><span style="color: #94E2D5;">:</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ..</span><span style="color: #89B4FA;font-style: italic;">default</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }),</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ..</span><span style="color: #89B4FA;font-style: italic;">default</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">init_state</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">GameState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">add_systems</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Startup</span><span style="color: #9399B2;">,</span><span> setup</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">run</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="random-position-for-food">Random Position for Food</h3> <p>We need a way to generate random grid positions for food. We'll also need to avoid spawning food on top of the snake:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> random_grid_position</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;"> rand</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">random</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">rem_euclid</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">GRID_WIDTH</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> row</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;"> rand</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">random</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">rem_euclid</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">GRID_HEIGHT</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> spawn_food_on_empty</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">snake</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">Snake</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> loop</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> pos</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> random_grid_position</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> !</span><span>snake</span><span style="color: #94E2D5;">.</span><span>segments</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">contains</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pos</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span> pos</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>rand::random::&lt;i32&gt;()</code> generates a random i32. <code>rem_euclid(GRID_WIDTH)</code> wraps it into (0, 20). The loop retries until it finds an empty cell that the snake does not occupy.</p> <h3 id="the-setup-system">The Setup System</h3> <p>Now the full <code>setup</code> function that spawns everything:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> setup</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">mut</span><span style="color: #EBA0AC;"> commands</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Commands</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> asset_server</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Res</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AssetServer</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Load sounds</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert_resource</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">EatSound</span><span style="color: #9399B2;">(</span><span>asset_server</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">load</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;audio/eat.wav&quot;</span><span style="color: #9399B2;">)));</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert_resource</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">DieSound</span><span style="color: #9399B2;">(</span><span>asset_server</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">load</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;audio/die.wav&quot;</span><span style="color: #9399B2;">)));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Initialize the screenshake timer as already finished so it doesn&#39;t</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // fire on startup. We reset it manually when the player dies.</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert_resource</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">ScreenShake</span><span style="color: #9399B2;">({</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> t</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> Timer</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_seconds</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;"> TimerMode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Once</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> t</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">finish</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> t</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Camera2d</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Initial snake: 3 segments in the center</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> start_col</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> GRID_WIDTH</span><span style="color: #94E2D5;"> /</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> start_row</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> GRID_HEIGHT</span><span style="color: #94E2D5;"> /</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> snake</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Snake</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> segments</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;"> {</span><span> col</span><span style="color: #94E2D5;">:</span><span> start_col</span><span style="color: #9399B2;">,</span><span> row</span><span style="color: #94E2D5;">:</span><span> start_row</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;"> {</span><span> col</span><span style="color: #94E2D5;">:</span><span> start_col</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">,</span><span> row</span><span style="color: #94E2D5;">:</span><span> start_row</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;"> {</span><span> col</span><span style="color: #94E2D5;">:</span><span> start_col</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span> row</span><span style="color: #94E2D5;">:</span><span> start_row</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ],</span></span> <span class="giallo-l"><span> direction</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Right</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Spawn one sprite per segment</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #94E2D5;"> &amp;</span><span>pos</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>snake</span><span style="color: #94E2D5;">.</span><span>segments </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">((</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> SnakeSegment</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Sprite</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_color</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Color</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">srgb</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">8</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">),</span><span style="color: #F9E2AF;"> Vec2</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">splat</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">CELL_SIZE</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Transform</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_translation</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">grid_to_world</span><span style="color: #9399B2;">(</span><span>pos</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert_resource</span><span style="color: #9399B2;">(</span><span>snake</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Food</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> food_pos</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;"> {</span><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 15</span><span style="color: #9399B2;">,</span><span> row</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">((</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> FoodSprite</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Sprite</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_color</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Color</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">srgb</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">8</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">),</span><span style="color: #F9E2AF;"> Vec2</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">splat</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">CELL_SIZE</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Transform</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_translation</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">grid_to_world</span><span style="color: #9399B2;">(</span><span>food_pos</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ));</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert_resource</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">Food</span><span style="color: #9399B2;">(</span><span>food_pos</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Timer, queue, score</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert_resource</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">MoveTimer</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Timer</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_seconds</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">SNAKE_MOVE_INTERVAL</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;"> TimerMode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Repeating</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ));</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert_resource</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">DirectionQueue</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">VecDeque</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">()));</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert_resource</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">Score</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Score text at top of screen</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">((</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> ScoreText</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Text2d</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Score: 0&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TextFont</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> font_size</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 30</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ..</span><span style="color: #89B4FA;font-style: italic;">default</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> TextColor</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Color</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">WHITE</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Transform</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_xyz</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 290</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ));</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Let me walk through the key parts.</p> <p>The snake starts at the center with 3 segments: <code>(10, 10)</code>, <code>(9, 10)</code>, <code>(8, 10)</code> heading right. We spawn a green <code>Sprite::from_color</code> for each segment. <code>Vec2::splat(CELL_SIZE - 2.0)</code> makes each segment 28x28 pixels, with a 1 pixel gap on each side so segments don't bleed into each other.</p> <p>Food is placed at <code>(15, 10)</code> on the right side of the grid. Red sprite.</p> <p>The timer is <code>Timer::from_seconds(0.15, TimerMode::Repeating)</code>. It loops every 0.15 seconds. Each time it completes, the snake moves.</p> <p>The <code>ScreenShake</code> timer is initialized with <code>t.finish()</code> called immediately after creation. This puts it in a completed state from the start. If we didn't do this, <code>apply_screenshake</code> would see a freshly-started timer on frame one and shake the camera for 0.3 seconds before any death has occurred. The timer only matters after we call <code>shake.0.reset()</code> on death.</p> <p>The score text uses <code>Text2d</code>, <code>TextFont</code>, <code>TextColor</code>, same pattern as Pong. Positioned at <code>y = 320</code>, near the top of the grid.</p> <p>Run <code>cargo run</code>. You should see a 3-segment green snake in the center, a red food square on the right, and "Score: 0" at the top. Nothing moves yet.</p> <h3 id="snake-input">Snake Input</h3> <p>Now we add movement. First, the input system. Arrow keys queue direction changes:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> snake_input</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> keyboard</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Res</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">ButtonInput</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">KeyCode</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> queue</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> ResMut</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">DirectionQueue</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> keyboard</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">just_pressed</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">KeyCode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">ArrowUp</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> queue</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">push_back</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Up</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else if</span><span> keyboard</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">just_pressed</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">KeyCode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">ArrowDown</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> queue</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">push_back</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Down</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else if</span><span> keyboard</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">just_pressed</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">KeyCode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">ArrowLeft</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> queue</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">push_back</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Left</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else if</span><span> keyboard</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">just_pressed</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">KeyCode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">ArrowRight</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> queue</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">push_back</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Right</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>We use <code>just_pressed</code> (not <code>pressed</code>) so each key press adds exactly one entry to the queue. Holding a key down does not spam the queue.</p> <h3 id="opposite-direction-check">Opposite Direction Check</h3> <p>The snake should not reverse into itself:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> is_opposite</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">a</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> b</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> bool</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> matches!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span>a</span><span style="color: #9399B2;">,</span><span> b</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Up</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Down</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> |</span><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Down</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Up</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> |</span><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Left</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Right</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> |</span><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Right</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Left</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> )</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>matches!</code> is a Rust macro that checks if a value matches a pattern.</p> <h3 id="snake-movement">Snake Movement</h3> <p>This is the core logic that runs on each timer tick:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> snake_move</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> commands</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Commands</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> time</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Res</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Time</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> timer</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> ResMut</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">MoveTimer</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> snake</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> ResMut</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Snake</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> queue</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> ResMut</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">DirectionQueue</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> food</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> ResMut</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Food</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> score</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> ResMut</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Score</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> next_state</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> ResMut</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">NextState</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">GameState</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> eat_sound</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Res</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">EatSound</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Advance the timer. Exit if it hasn&#39;t finished yet.</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> !</span><span>timer</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">tick</span><span style="color: #9399B2;">(</span><span>time</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">delta</span><span style="color: #9399B2;">())</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">just_finished</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Pop the next direction from the queue, if any</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> while let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>next_dir</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> queue</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">pop_front</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> !</span><span style="color: #89B4FA;font-style: italic;">is_opposite</span><span style="color: #9399B2;">(</span><span>next_dir</span><span style="color: #9399B2;">,</span><span> snake</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">direction</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> snake</span><span style="color: #94E2D5;">.</span><span>direction </span><span style="color: #94E2D5;">=</span><span> next_dir</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Calculate the new head position</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> head</span><span style="color: #94E2D5;"> =</span><span> snake</span><span style="color: #94E2D5;">.</span><span>segments</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> new_head</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> snake</span><span style="color: #94E2D5;">.</span><span>direction </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Up</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span> head</span><span style="color: #94E2D5;">.</span><span>col</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> row</span><span style="color: #94E2D5;">:</span><span> head</span><span style="color: #94E2D5;">.</span><span>row </span><span style="color: #94E2D5;">+</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Down</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span> head</span><span style="color: #94E2D5;">.</span><span>col</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> row</span><span style="color: #94E2D5;">:</span><span> head</span><span style="color: #94E2D5;">.</span><span>row </span><span style="color: #94E2D5;">-</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Left</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span> head</span><span style="color: #94E2D5;">.</span><span>col </span><span style="color: #94E2D5;">-</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> row</span><span style="color: #94E2D5;">:</span><span> head</span><span style="color: #94E2D5;">.</span><span>row</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Right</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span> head</span><span style="color: #94E2D5;">.</span><span>col </span><span style="color: #94E2D5;">+</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> row</span><span style="color: #94E2D5;">:</span><span> head</span><span style="color: #94E2D5;">.</span><span>row</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Wall collision</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> new_head</span><span style="color: #94E2D5;">.</span><span>col</span><span style="color: #94E2D5;"> &lt;</span><span style="color: #FAB387;"> 0</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ||</span><span> new_head</span><span style="color: #94E2D5;">.</span><span>col </span><span style="color: #94E2D5;">&gt;=</span><span style="color: #FAB387;"> GRID_WIDTH</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ||</span><span> new_head</span><span style="color: #94E2D5;">.</span><span>row</span><span style="color: #94E2D5;"> &lt;</span><span style="color: #FAB387;"> 0</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ||</span><span> new_head</span><span style="color: #94E2D5;">.</span><span>row </span><span style="color: #94E2D5;">&gt;=</span><span style="color: #FAB387;"> GRID_HEIGHT</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> next_state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">set</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">GameState</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">GameOver</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Self collision</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> snake</span><span style="color: #94E2D5;">.</span><span>segments</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">contains</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>new_head</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> next_state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">set</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">GameState</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">GameOver</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Move: insert new head at the front</span></span> <span class="giallo-l"><span> snake</span><span style="color: #94E2D5;">.</span><span>segments</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span> new_head</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Check if the snake ate the food</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> new_head</span><span style="color: #94E2D5;"> ==</span><span> food</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> score</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> +=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">AudioPlayer</span><span style="color: #9399B2;">(</span><span>eat_sound</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">()));</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> spawn_eat_particles</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span> commands</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> grid_to_world</span><span style="color: #9399B2;">(</span><span>new_head</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span> food</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> spawn_food_on_empty</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>snake</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Don&#39;t remove the tail, snake grows</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> snake</span><span style="color: #94E2D5;">.</span><span>segments</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">pop</span><span style="color: #9399B2;">();</span><span style="color: #9399B2;font-style: italic;"> // Remove tail</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Let me explain the most important parts.</p> <p><strong>System parameters.</strong> <code>snake_move</code> takes <code>mut commands: Commands</code> and <code>eat_sound: Res&lt;EatSound&gt;</code> because eating food both plays a sound and spawns particles, both require <code>commands</code>. Bevy injects all system parameters automatically; you just declare what you need.</p> <p><strong>Timer tick.</strong> <code>timer.0.tick(time.delta())</code> advances the timer by the frame's delta time. <code>.just_finished()</code> returns true exactly once when the timer reaches its duration. On that frame, the snake moves. The timer is <code>Repeating</code>, so it resets automatically.</p> <p><strong>Queue processing.</strong> The <code>while</code> loop pops directions from the front of the queue until it finds one that is not opposite to the current direction. The <code>break</code> after a valid direction means only one turn per tick. The check is against <code>snake.direction</code>, the direction the snake is <em>currently moving</em>, not the last queued direction.</p> <p><strong>New head position.</strong> The head moves one cell in the current direction. <code>Up</code> increases <code>row</code>, <code>Down</code> decreases it. <code>Left</code> and <code>Right</code> change <code>col</code>.</p> <p><strong>Wall collision.</strong> If the new head is outside the 20x20 grid, game over.</p> <p><strong>Self collision.</strong> <code>.contains(&amp;new_head)</code> checks if the new head overlaps any existing segment. If yes, game over.</p> <p><strong>Food check.</strong> If the head landed on the food cell, the score increases, a sound plays, particles burst, the food respawns, and the tail is NOT removed, the snake grows by one. Otherwise, the tail is popped off.</p> <h3 id="sync-sprites">Sync Sprites</h3> <p>The <code>snake_move</code> system updates the logical positions. Now we need to update the visual sprites to match. The simplest approach: despawn all old sprites and spawn new ones at the current positions:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> sync_sprites</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> commands</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Commands</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> snake</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Res</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Snake</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> food</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Res</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Food</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> segments</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Entity</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> With</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">SnakeSegment</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> food_sprites</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Entity</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> With</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">FoodSprite</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Despawn old segment sprites</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> entity</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>segments</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">entity</span><span style="color: #9399B2;">(</span><span>entity</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">despawn</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Despawn old food sprite</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> entity</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>food_sprites</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">entity</span><span style="color: #9399B2;">(</span><span>entity</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">despawn</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Spawn new segment sprites</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>i</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>pos</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span> snake</span><span style="color: #94E2D5;">.</span><span>segments</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">enumerate</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> color</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if</span><span> i</span><span style="color: #94E2D5;"> ==</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Color</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">srgb</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">95</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">)</span><span style="color: #9399B2;font-style: italic;"> // Head: bright green</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Color</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">srgb</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">7</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">)</span><span style="color: #9399B2;font-style: italic;"> // Body: darker green</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">((</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> SnakeSegment</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Sprite</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_color</span><span style="color: #9399B2;">(</span><span>color</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;"> Vec2</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">splat</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">CELL_SIZE</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Transform</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_translation</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">grid_to_world</span><span style="color: #9399B2;">(</span><span>pos</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Spawn new food sprite</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">((</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> FoodSprite</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Sprite</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_color</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Color</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">srgb</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">9</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">),</span><span style="color: #F9E2AF;"> Vec2</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">splat</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">CELL_SIZE</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Transform</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_translation</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">grid_to_world</span><span style="color: #9399B2;">(</span><span>food</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ));</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>We despawn entities by querying for their marker components and calling <code>commands.entity(entity).despawn()</code>. We make the head bright green and the body darker green so the player can see which end is which. This despawn-and-respawn approach is simple and correct for a game this size.</p> <h3 id="score-text-update">Score Text Update</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> update_score_text</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> score</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Res</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Score</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> query</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Text2d</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> With</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">ScoreText</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> commands</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Commands</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for mut</span><span> text</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span> query</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> old</span><span style="color: #94E2D5;"> =</span><span> text</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> text</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Score: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> score</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> old</span><span style="color: #94E2D5;"> !=</span><span> text</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">((</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> ScorePop</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Timer</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_seconds</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;"> TimerMode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Once</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Text2d</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>text</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">()),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TextFont</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> font_size</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 44</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ..</span><span style="color: #89B4FA;font-style: italic;">default</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> TextColor</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Color</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">srgb</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Transform</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_xyz</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 290</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>text.0</code> accesses the inner <code>String</code> of <code>Text2d</code>. We compare the old value to the new value. If they differ, the score just changed and we spawn a <code>ScorePop</code> entity, a larger yellow version of the score text that floats upward and fades. The <code>commands</code> parameter is needed here for that spawn.</p> <h3 id="score-pop-animation">Score Pop Animation</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> update_score_pop</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> commands</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Commands</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> time</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Res</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Time</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> pops</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Entity</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> ScorePop</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Transform</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> TextColor</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>entity</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> mut</span><span> pop</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> mut</span><span> transform</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> mut</span><span> color</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span> pops</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> pop</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">tick</span><span style="color: #9399B2;">(</span><span>time</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">delta</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> pop</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">is_finished</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">entity</span><span style="color: #9399B2;">(</span><span>entity</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">despawn</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> continue</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> t</span><span style="color: #94E2D5;"> =</span><span> pop</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">fraction_remaining</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">=</span><span style="color: #FAB387;"> 290</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> +</span><span style="color: #9399B2;"> (</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> -</span><span> t</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> 30</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> color</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">set_alpha</span><span style="color: #9399B2;">(</span><span>t</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>fraction_remaining()</code> goes from 1.0 at the start of the timer down to 0.0 at the end. We use it for both alpha (fades out) and to drive the upward float. When <code>t = 1.0</code> (just spawned), <code>y = 290.0 + 0.0 * 30.0 = 290.0</code>. When <code>t = 0.0</code> (about to despawn), <code>y = 290.0 + 1.0 * 30.0 = 320.0</code>. So the text floats 30 pixels upward while fading.</p> <h3 id="game-over-and-restart">Game Over and Restart</h3> <p>When the game is over, we show a message and wait for Enter:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> game_over_restart</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> keyboard</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Res</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">ButtonInput</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">KeyCode</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> next_state</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> ResMut</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">NextState</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">GameState</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> snake</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> ResMut</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Snake</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> food</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> ResMut</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Food</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> score</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> ResMut</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Score</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> timer</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> ResMut</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">MoveTimer</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> queue</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> ResMut</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">DirectionQueue</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> !</span><span>keyboard</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">just_pressed</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">KeyCode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Enter</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Reset everything</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> start_col</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> GRID_WIDTH</span><span style="color: #94E2D5;"> /</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> start_row</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> GRID_HEIGHT</span><span style="color: #94E2D5;"> /</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> snake</span><span style="color: #94E2D5;">.</span><span>segments </span><span style="color: #94E2D5;">=</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;"> {</span><span> col</span><span style="color: #94E2D5;">:</span><span> start_col</span><span style="color: #9399B2;">,</span><span> row</span><span style="color: #94E2D5;">:</span><span> start_row</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;"> {</span><span> col</span><span style="color: #94E2D5;">:</span><span> start_col</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">,</span><span> row</span><span style="color: #94E2D5;">:</span><span> start_row</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;"> {</span><span> col</span><span style="color: #94E2D5;">:</span><span> start_col</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span> row</span><span style="color: #94E2D5;">:</span><span> start_row</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ];</span></span> <span class="giallo-l"><span> snake</span><span style="color: #94E2D5;">.</span><span>direction </span><span style="color: #94E2D5;">=</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Right</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> food</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> GridPosition</span><span style="color: #9399B2;"> {</span><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 15</span><span style="color: #9399B2;">,</span><span> row</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span> score</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> timer</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">reset</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> queue</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">clear</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> next_state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">set</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">GameState</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Playing</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The game over screen is shown and hidden via <code>OnEnter</code> and <code>OnExit</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> show_game_over</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> commands</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Commands</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> die_sound</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Res</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">DieSound</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> shake</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> ResMut</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">ScreenShake</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">AudioPlayer</span><span style="color: #9399B2;">(</span><span>die_sound</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">()));</span></span> <span class="giallo-l"><span> shake</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">reset</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">((</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> GameOverText</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Text2d</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Game Over</span><span style="color: #F5C2E7;">\n</span><span style="color: #A6E3A1;">Press Enter to Restart&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TextFont</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> font_size</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 40</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ..</span><span style="color: #89B4FA;font-style: italic;">default</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> TextColor</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Color</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">srgb</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Transform</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_xyz</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ));</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> hide_game_over</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">mut</span><span style="color: #EBA0AC;"> commands</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Commands</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> query</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Entity</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> With</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">GameOverText</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> entity</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>query</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">entity</span><span style="color: #9399B2;">(</span><span>entity</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">despawn</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>show_game_over</code> does three things: plays the death sound, resets the screenshake timer (which triggers the camera shake), and spawns the game over text. <code>hide_game_over</code> despawns it when the player restarts.</p> <h3 id="polish-particle-burst-on-eat">Polish: Particle Burst on Eat</h3> <p>When the snake eats, we spawn 10 small yellow particles that fly outward and fade:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> spawn_eat_particles</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">commands</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Commands</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> position</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec3</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> _</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 0</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">10</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> angle</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> rand</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">random</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">f32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> *</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #CBA6F7;">f32</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">consts</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">TAU</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> speed</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 60</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> +</span><span style="color: #F9E2AF;"> rand</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">random</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">f32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> 80</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">((</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Particle</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> velocity</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;"> Vec2</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>angle</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">cos</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> *</span><span> speed</span><span style="color: #9399B2;">,</span><span> angle</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">sin</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> *</span><span> speed</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> lifetime</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;"> Timer</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_seconds</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">6</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;"> TimerMode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Once</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Sprite</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_color</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Color</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">srgb</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">9</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">),</span><span style="color: #F9E2AF;"> Vec2</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">splat</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Transform</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_translation</span><span style="color: #9399B2;">(</span><span>position</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>TAU</code> is 2π, a full circle in radians. Multiplying a random float by <code>TAU</code> gives a random angle. <code>angle.cos()</code> and <code>angle.sin()</code> give the x and y components of a unit vector in that direction, scaled by <code>speed</code>. Each particle gets its own <code>lifetime</code> timer. This is why <code>Particle</code> is a component rather than a resource, many particles can exist simultaneously, each with independent state.</p> <p>A separate system updates particles each frame:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> update_particles</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> commands</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Commands</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> time</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Res</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Time</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> particles</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Entity</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Particle</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Transform</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Sprite</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>entity</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> mut</span><span> particle</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> mut</span><span> transform</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> mut</span><span> sprite</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span> particles</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> particle</span><span style="color: #94E2D5;">.</span><span>lifetime</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">tick</span><span style="color: #9399B2;">(</span><span>time</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">delta</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> particle</span><span style="color: #94E2D5;">.</span><span>lifetime</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_finished</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">entity</span><span style="color: #9399B2;">(</span><span>entity</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">despawn</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> continue</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> t</span><span style="color: #94E2D5;"> =</span><span> particle</span><span style="color: #94E2D5;">.</span><span>lifetime</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">fraction_remaining</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">+=</span><span> particle</span><span style="color: #94E2D5;">.</span><span>velocity</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">*</span><span> time</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">delta_secs</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">+=</span><span> particle</span><span style="color: #94E2D5;">.</span><span>velocity</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">*</span><span> time</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">delta_secs</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> sprite</span><span style="color: #94E2D5;">.</span><span>color</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">set_alpha</span><span style="color: #9399B2;">(</span><span>t</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> transform</span><span style="color: #94E2D5;">.</span><span>scale </span><span style="color: #94E2D5;">=</span><span style="color: #F9E2AF;font-style: italic;"> Vec3</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">splat</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">5</span><span style="color: #94E2D5;"> +</span><span> t</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>t</code> goes from 1.0 to 0.0 as the particle ages. Alpha fades from 1.0 to 0.0. Scale goes from <code>0.5 + 1.0 * 0.5 = 1.0</code> down to <code>0.5 + 0.0 * 0.5 = 0.5</code>, so particles shrink slightly as they die.</p> <h3 id="polish-screen-shake-on-death">Polish: Screen Shake on Death</h3> <p>When the player dies, the camera shakes briefly:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> apply_screenshake</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> shake</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> ResMut</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">ScreenShake</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> camera</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Transform</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> With</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Camera2d</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> time</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Res</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Time</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> shake</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">tick</span><span style="color: #9399B2;">(</span><span>time</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">delta</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for mut</span><span> transform</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span> camera</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> shake</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">is_finished</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> transform</span><span style="color: #94E2D5;">.</span><span>translation </span><span style="color: #94E2D5;">!=</span><span style="color: #F9E2AF;font-style: italic;"> Vec3</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">ZERO</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> transform</span><span style="color: #94E2D5;">.</span><span>translation </span><span style="color: #94E2D5;">=</span><span style="color: #F9E2AF;font-style: italic;"> Vec3</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">ZERO</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> intensity</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> *</span><span style="color: #9399B2;"> (</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> -</span><span> shake</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">fraction</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span> transform</span><span style="color: #94E2D5;">.</span><span>translation </span><span style="color: #94E2D5;">=</span><span style="color: #F9E2AF;font-style: italic;"> Vec3</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> rand</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">random</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">f32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> *</span><span> intensity</span><span style="color: #94E2D5;"> -</span><span> intensity</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> rand</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">random</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">f32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> *</span><span> intensity</span><span style="color: #94E2D5;"> -</span><span> intensity</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> );</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>shake.0.fraction()</code> goes from 0.0 to 1.0 as time passes, so <code>1.0 - fraction()</code> starts at 1.0 and decays to 0.0. Multiplying by 10.0 gives a starting intensity of 10 pixels that eases to zero. When finished, the camera is snapped back to <code>Vec3::ZERO</code>. Because the timer starts pre-finished (we called <code>t.finish()</code> in setup), this system runs every frame doing nothing until a death occurs and <code>shake.0.reset()</code> is called.</p> <h3 id="register-everything">Register Everything</h3> <p>The final <code>main</code> function ties it all together:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> App</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">add_plugins</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">DefaultPlugins</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">set</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">WindowPlugin</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> primary_window</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Window</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> title</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;Snake&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> resolution</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;"> bevy</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">window</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">WindowResolution</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">600</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 680</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> resizable</span><span style="color: #94E2D5;">:</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ..</span><span style="color: #89B4FA;font-style: italic;">default</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }),</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ..</span><span style="color: #89B4FA;font-style: italic;">default</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">init_state</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">GameState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">add_systems</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Startup</span><span style="color: #9399B2;">,</span><span> setup</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">add_systems</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">OnEnter</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">GameState</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">GameOver</span><span style="color: #9399B2;">),</span><span> show_game_over</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">add_systems</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">OnExit</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">GameState</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">GameOver</span><span style="color: #9399B2;">),</span><span> hide_game_over</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">add_systems</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Update</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span></span> <span class="giallo-l"><span> snake_input</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> snake_move</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">run_if</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">in_state</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">GameState</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Playing</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span> sync_sprites</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> update_score_text</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> update_score_pop</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> update_particles</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> apply_screenshake</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> game_over_restart</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">run_if</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">in_state</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">GameState</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">GameOver</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> )</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">run</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Run <code>cargo run</code>. You should now have a fully polished Snake game:</p> <ul> <li>Steer with arrow keys. Eat food to grow and score points.</li> <li>Eat food -&gt; hear a rising beep, yellow particles burst, score pops up bigger.</li> <li>Hit a wall or yourself -&gt; hear a low tone, screen shakes, "Game Over" appears.</li> <li>Press Enter to restart.</li> </ul> <h3 id="deploying-to-itch-io">Deploying to Itch.io</h3> <p>Let's build a web version and publish it to itch.io.</p> <p>Before building for the web, add this to your <code>Cargo.toml</code> after the <code>[dependencies]</code> block:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;">[</span><span>target.&#39;cfg(all(target_family = &quot;wasm&quot;, any(target_os = &quot;unknown&quot;, target_os = &quot;none&quot;)))&#39;.dependencies</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>getrandom_02</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;^0.2&quot;</span><span style="color: #9399B2;">,</span><span> features</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> [</span><span style="color: #A6E3A1;">&quot;js&quot;</span><span style="color: #9399B2;">],</span><span> package</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;getrandom&quot;</span><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span>getrandom_03</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;^0.3&quot;</span><span style="color: #9399B2;">,</span><span> features</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> [</span><span style="color: #A6E3A1;">&quot;wasm_js&quot;</span><span style="color: #9399B2;">],</span><span> package</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;getrandom&quot;</span><span style="color: #9399B2;"> }</span></span></code></pre> <p><code>rand</code> uses <code>getrandom</code> internally to access the system's entropy source. On native, this is straightforward. On <code>wasm32-unknown-unknown</code>, there is no OS, so <code>getrandom</code> needs to be told to use the browser's <code>crypto.getRandomValues()</code> API instead. Without this, <code>rand::random()</code> panics at runtime in the browser. The <code>cfg</code> target triple ensures these entries only apply to WASM builds and have no effect on native.</p> <p>First, install the wasm target:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>rustup target add wasm32-unknown-unknown</span></span></code></pre> <p>Install the Bevy CLI. It is not yet published to crates.io so install it from git:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo install --git https://github.com/TheBevyFlock/bevy_cli --locked bevy_cli</span></span></code></pre> <p>Build and bundle the web release:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>bevy build --release web --bundle</span></span></code></pre> <p>The <code>--bundle</code> flag collects the wasm binary, JS bindings, and assets into a single folder at:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>target/bevy_web/</span></span></code></pre> <p>That folder is self-contained. Create a zip from it:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cd target/bevy_web</span></span> <span class="giallo-l"><span>zip -r ../../bevy_snake.zip .</span></span></code></pre> <p>Upload <code>bevy_snake.zip</code> to <a rel="external" href="https://itch.io/">itch.io</a> and enable "This file will be played in the browser".</p> <h3 id="things-we-could-improve">Things We Could Improve</h3> <ul> <li>The food always spawns in random positions. It could prefer the area ahead of the snake for more interesting gameplay.</li> <li>We could add difficulty progression: the snake moves faster as the score increases.</li> <li>High score persistence with local storage.</li> <li>A proper title screen with settings (volume sliders, fullscreen toggle).</li> </ul> <h3 id="conclusion">Conclusion</h3> <p>You now understand how game states work in Bevy, how timers drive tick-based movement, how grid coordinates power tile-based games, and how to queue inputs to prevent unfair deaths. You also learned how to bake polish into every system like particles, screenshake, audio, and animations.</p> <p>In the next post, we will build Breakout and learn about collision groups, sprite sheet animations, power-up drops, and tween-style animations. See you soon!</p> 2026-05-28T00:00:00+00:00 2026-05-28T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/learn-rust-closures-by-building-a-tiny-linter/ <p>In this post, we are going to learn about closures and functional patterns in Rust. Once we cover all the concepts, we will build a Tiny Rule-based Text Linter where lint rules are closures stored in a <code>Vec&lt;Box&lt;dyn Fn&gt;&gt;</code>, pass behaviour as values, and auto-fix code. I'm really excited for this project and I hope you are too. I won't go too deep in theory, just practical and we will build our knowledge of these concepts over time with more articles.</p> <p>The only prerequisite is that you have read the previous articles in this series, as I will assume you know ownership, borrowing, structs, enums, pattern matching, error handling, generics, traits, and lifetimes.</p> <p>Get the source code <a rel="external" href="https://github.com/MrSheerluck/linter-rust">here</a></p> <h2 id="what-is-box-t">What is <code>Box&lt;T&gt;</code></h2> <p>Before we talk about closures, we need to understand <code>Box&lt;T&gt;</code>. You saw <code>Box</code> briefly in the JSON parser when we talked about recursive enums. Let me explain it properly now.</p> <p>A <code>Box&lt;T&gt;</code> is a heap-allocated value. When you write <code>let x = Box::new(42)</code>, Rust allocates space for <code>42</code> on the heap and stores a pointer to it on the stack. The <code>Box</code> owns the value, when the <code>Box</code> is dropped, the heap memory is freed.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Box</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">42</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // 42</span></span></code></pre> <p><code>Box::new(42)</code> allocates <code>42</code> on the heap and returns a <code>Box&lt;i32&gt;</code> that owns it. You can use <code>x</code> just like a regular <code>i32</code>. Rust dereferences it automatically when you access it. This is called "deref coercion."</p> <p>Without <code>Box</code>, local bindings themselves are usually stack-allocated, though many types such as <code>Vec</code> and <code>String</code> may still allocate their contents on the heap internally. With <code>Box</code>, you explicitly move a value onto the heap while keeping a pointer on the stack.</p> <h2 id="why-do-we-need-box">Why Do We Need Box</h2> <p>There are two main reasons to use Box:</p> <ol> <li>Recursive types: A struct that contains itself would have infinite size on the stack. Putting it behind a <code>Box</code> gives it a fixed size (just the pointer). This is exactly what we did in the JSON parser with recursive <code>JsonValue</code> variants.</li> <li>Trait objects: When you want to store values of different types in a single <code>Vec</code>, they must all be the same size. <code>Box</code> puts them on the heap so the <code>Vec</code> only stores fixed-size pointers.</li> </ol> <h2 id="what-are-trait-objects">What Are Trait Objects</h2> <p>A trait object lets us work with values through a trait interface without knowing their concrete type at compile time.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">trait</span><span style="color: #F9E2AF;font-style: italic;"> Animal</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> speak</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Dog</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Cat</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Animal</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> Dog</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> speak</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;woof&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Animal</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> Cat</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> speak</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;meow&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>Dog</code> and <code>Cat</code> are completely different concrete types. Normally, a <code>Vec&lt;T&gt;</code> can only store a single concrete type:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> dogs</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Dog</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">Dog</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Dog</span><span style="color: #9399B2;">];</span></span></code></pre> <p>If we try to mix <code>Dog</code> and <code>Cat</code> directly inside the same vector, Rust rejects it:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// ERROR</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// let animals = vec![Dog, Cat];</span></span></code></pre> <p>Rust needs every element in a <code>Vec</code> to have the same concrete type and size at compile time.</p> <p>Trait objects solve this problem.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> animals</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Box</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">dyn</span><span style="color: #F9E2AF;font-style: italic;"> Animal</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Box</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Dog</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Box</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Cat</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">];</span></span></code></pre> <p><code>dyn Animal</code> means "Some type that implements the <code>Animal</code> trait."</p> <p>The concrete type (<code>Dog</code> or <code>Cat</code>) is erased, and we interact with the value only through the trait methods defined by <code>Animal</code>.</p> <p>Now we can iterate over the vector:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">for</span><span> animal</span><span style="color: #CBA6F7;"> in</span><span> animals</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> animal</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">speak</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Rust will call the correct implementation at runtime, either <code>Dog::speak</code> or <code>Cat::speak</code> depending on the concrete type behind the trait object.</p> <p>This is called dynamic dispatch. Under the hood, a trait object stores a pointer to the actual data along with a pointer to a vtable. A vtable ("virtual method table") contains function pointers for the trait methods of the concrete type.</p> <p>When we call:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span>animal</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">speak</span><span style="color: #9399B2;">();</span></span></code></pre> <p>Rust looks up the correct function in the vtable and calls the appropriate implementation for the concrete type behind the trait object.</p> <p>Trait objects are dynamically sized types (DSTs). Rust does not know their size at compile time, so they must be used behind some kind of pointer such as <code>Box&lt;dyn Trait&gt;</code>, <code>&amp;dyn Trait</code>, or <code>Rc&lt;dyn Trait&gt;</code>.</p> <p>This is why we later use <code>Box&lt;dyn Fn&gt;</code> for storing closures of different concrete types inside the same <code>Vec</code>.</p> <h2 id="closures">Closures</h2> <p>Now that you understand Box and dyn, let's learn about closures.</p> <p>A closure is an anonymous function that can capture variables from its environment.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> add_x</span><span style="color: #94E2D5;"> = |</span><span>n</span><span style="color: #94E2D5;">|</span><span> n</span><span style="color: #94E2D5;"> +</span><span> x</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> add_x</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;">));</span><span style="color: #9399B2;font-style: italic;"> // 15</span></span></code></pre> <p><code>|n| n + x</code> is a closure. The parameter <code>n</code> goes between the pipes <code>|n|</code>, and the body <code>n + x</code> follows. The closure captures <code>x</code> from the surrounding scope and adds it to <code>n</code>. When we call <code>add_x(5)</code>, it returns <code>15</code>.</p> <p>This is different from a regular function. A regular <code>fn</code> cannot access variables from the enclosing scope</p> <h2 id="closure-syntax">Closure Syntax</h2> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// Full syntax with type annotations</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> closure</span><span style="color: #94E2D5;"> = |</span><span>n</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #94E2D5;">| -&gt;</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;"> {</span><span> n</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// Inferred types (most common)</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> closure</span><span style="color: #94E2D5;"> = |</span><span>n</span><span style="color: #94E2D5;">|</span><span> n</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// Multiple parameters</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> add</span><span style="color: #94E2D5;"> = |</span><span>a</span><span style="color: #9399B2;">,</span><span> b</span><span style="color: #94E2D5;">|</span><span> a</span><span style="color: #94E2D5;"> +</span><span> b</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// No parameters</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> greet</span><span style="color: #94E2D5;"> = ||</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">);</span></span></code></pre> <p>Closures can have type annotations like regular functions, but usually Rust infers the types from how you use the closure. The pipes <code>||</code> enclose the parameter list, just like parentheses <code>()</code> in a regular function. Unlike functions, closures with a single expression can omit the curly braces.</p> <h2 id="how-closures-capture-variables">How Closures Capture Variables</h2> <p>Closures capture variables from their environment in three ways, matching the three borrowing modes:</p> <table><thead><tr><th>Capture Mode</th><th>How It Captures</th><th>Closure Trait</th></tr></thead><tbody> <tr><td><code>&amp;T</code></td><td>Immutable reference</td><td><code>Fn</code></td></tr> <tr><td><code>&amp;mut T</code></td><td>Mutable reference</td><td><code>FnMut</code></td></tr> <tr><td><code>T</code></td><td>Ownership (move)</td><td><code>FnOnce</code></td></tr> </tbody></table> <p>Rust infers the capture mode automatically based on what the closure does with the captured variable.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> print_it</span><span style="color: #94E2D5;"> = ||</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> s</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> s2</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> push_world</span><span style="color: #94E2D5;"> = ||</span><span> s2</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push_str</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot; world&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> s3</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> consume</span><span style="color: #94E2D5;"> = ||</span><span style="color: #89B4FA;font-style: italic;"> drop</span><span style="color: #9399B2;">(</span><span>s3</span><span style="color: #9399B2;">);</span></span></code></pre> <p><code>print_it</code> only reads <code>s</code>, so Rust captures it by immutable reference and the closure implements <code>Fn</code>.</p> <p><code>push_world</code> mutates <code>s2</code>, so Rust captures it by mutable reference and the closure implements <code>FnMut</code>.</p> <p><code>consume</code> takes ownership of <code>s3</code> using <code>drop</code>, so the closure implements <code>FnOnce</code>. After the first call, <code>s3</code> is gone and the closure cannot be called again.</p> <p>The traits form a hierarchy:</p> <ul> <li><code>Fn</code> closures can be called many times without mutation</li> <li><code>FnMut</code> closures can mutate captured state</li> <li><code>FnOnce</code> closures may consume captured values</li> </ul> <h2 id="the-move-keyword">The <code>move</code> Keyword</h2> <p>Sometimes you need to force a closure to take ownership of captured variables. This is essential when the closure will outlive the scope where it was created.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> closure</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> move</span><span style="color: #94E2D5;"> ||</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> s</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">};</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// println!(&quot;{}&quot;, s); // ERROR: s was moved into the closure</span></span></code></pre> <p>The <code>move</code> keyword before the pipes tells Rust: capture everything by value, even if the closure only reads the variable. Without <code>move</code>, the closure would borrow <code>s</code> by reference. With <code>move</code>, it takes ownership of <code>s</code>.</p> <h2 id="storing-closures-the-problem">Storing Closures: The Problem</h2> <p>Every closure has a unique type. Two closures with the same signature are different types:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> c1</span><span style="color: #94E2D5;"> = |</span><span>x</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #94E2D5;">|</span><span> x</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &gt;</span><span style="color: #FAB387;"> 80</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> c2</span><span style="color: #94E2D5;"> = |</span><span>x</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #94E2D5;">|</span><span> x</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">contains</span><span style="color: #9399B2;">(&#39;</span><span style="color: #F5C2E7;">\t</span><span style="color: #9399B2;">&#39;);</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// These are DIFFERENT types. You cannot do this:</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// let rules: Vec&lt;???&gt; = vec![c1, c2];</span></span></code></pre> <p>We cannot name the type of a closure. Even if we could, they would be different sizes.</p> <h2 id="storing-closures-the-solution-with-box-dyn-fn">Storing Closures: The Solution with <code>Box&lt;dyn Fn&gt;</code></h2> <p>We use <code>Box&lt;dyn Fn&gt;</code>, a boxed trait object. <code>Box</code> gives the vector a fixed-size pointer representation even though the underlying closure types differ. <code>dyn Fn(...)</code> erases the concrete type and uses a vtable for dynamic dispatch.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> rules</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Box</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">dyn</span><span style="color: #F9E2AF;font-style: italic;"> Fn</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #89DCEB;">&gt;&gt;&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span>rules</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Box</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>line</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &gt;</span><span style="color: #FAB387;"> 80</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #A6E3A1;">&quot;Line too long&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">()]</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[]</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}));</span></span> <span class="giallo-l"><span>rules</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Box</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>line</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">contains</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;TODO&quot;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #A6E3A1;">&quot;Contains TODO&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">()]</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[]</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}));</span></span></code></pre> <p><code>Box::new(|line| ...)</code> heap-allocates the closure. <code>Box::new</code> allocates space on the heap and moves the closure into it, returning a <code>Box</code> pointer. When we push into rules, Rust sees <code>Box&lt;UniqueClosureType&gt;</code> and coerces it to <code>Box&lt;dyn Fn(...)&gt;</code>.</p> <p>The <code>dyn</code> keyword means the <code>Box</code> now holds a fat pointer: one pointer to the heap-allocated closure data, and one pointer to a vtable that tells Rust how to call <code>Fn::call</code> on this specific closure. When we call <code>rule(line)</code>, Rust looks up the function address in the vtable and calls through it.</p> <h2 id="why-can-t-we-use-generics-in-the-struct">Why Can't We Use Generics in the Struct</h2> <p>Instead of <code>Box&lt;dyn Fn&gt;</code>, why not make the <code>Linter</code> struct generic?</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Linter</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">F</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> Fn</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Violation</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> rules</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">F</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>A generic struct is monomorphized: the compiler creates a separate copy for each concrete <code>F</code>. But we want to store different closures with different types in the same <code>Vec</code>. A <code>Vec&lt;F&gt;</code> can only hold one type of closure. With <code>Box&lt;dyn Fn&gt;</code>, all closures are erased to the same type (<code>Box&lt;dyn Fn(...)</code>) so they fit in the same <code>Vec</code>.</p> <p>This is the fundamental tradeoff:</p> <ul> <li>Generics (<code>impl Fn</code> / <code>F: Fn</code>): Static dispatch, faster, but all items must be the same concrete type</li> <li>Trait objects (<code>Box&lt;dyn Fn&gt;</code>): Dynamic dispatch, slightly slower, but items can be different concrete types</li> </ul> <h2 id="the-project-tiny-rule-based-text-linter">The Project: Tiny Rule-based Text Linter</h2> <p>Now that you understand closures, <code>Box</code>, <code>dyn</code> trait objects, and how they work together, let's build our Tiny Rule-based Text Linter.</p> <p>Our program will:</p> <ul> <li>Define lint rules as closures: Fn(&amp;str) -&gt; <code>Vec&lt;Violation&gt;</code></li> <li>Store rules in a <code>Vec&lt;Box&lt;dyn Fn(&amp;str) -&gt; Vec&lt;Violation&gt;&gt;&gt;</code></li> <li>Run all rules over each line of a file</li> <li>Report all violations with line numbers</li> <li>Support fixers as <code>Fn(&amp;mut String) -&gt; bool</code> closures</li> <li>Apply fixers to auto-correct issues</li> </ul> <h2 id="project-setup">Project Setup</h2> <p>Open your terminal and run:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> new linter</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> linter</span></span></code></pre> <p>Now open <code>src/main.rs</code> and let's build this step by step.</p> <h3 id="the-violation-and-linter-types">The Violation and Linter Types</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span>fs</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Debug</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Violation</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Linter</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> rules</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Box</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">dyn</span><span style="color: #F9E2AF;font-style: italic;"> Fn</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Violation</span><span style="color: #89DCEB;">&gt;&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> fixers</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Box</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">dyn</span><span style="color: #F9E2AF;font-style: italic;"> Fn</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> bool</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>Violation</code> holds a line number and a message describing the problem. <code>Linter</code> holds two vectors of boxed trait objects.</p> <p>Let's read <code>Vec&lt;Box&lt;dyn Fn(&amp;str) -&gt; Vec&lt;Violation&gt;&gt;&gt;</code> from the inside out:</p> <ul> <li><code>&amp;str</code> is the input: a line of text</li> <li><code>Vec&lt;Violation&gt;</code> is the output: all violations found on that line</li> <li><code>dyn Fn(&amp;str) -&gt; Vec&lt;Violation&gt;</code> is a trait object: any closure that takes &amp;str and returns <code>Vec&lt;Violation&gt;</code></li> <li><code>Box&lt;...&gt;</code> heap-allocates that trait object so all entries in the <code>Vec</code> are the same size (a pointer)</li> <li><code>Vec&lt;Box&lt;...&gt;&gt;</code> is the collection holding all our rules Same for fixers, but fixers take <code>&amp;mut</code> String (the entire file) and return <code>bool</code> (whether they changed anything).</li> </ul> <h3 id="adding-rules-and-fixers">Adding Rules and Fixers</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Linter</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> new</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Linter</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Linter</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> rules</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> fixers</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> add_rule</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">F</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> rule</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> F</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> where</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> F</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> Fn</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Violation</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> +</span><span style="color: #9399B2;"> &#39;</span><span style="color: #89B4FA;font-style: italic;">static</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>rules</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Box</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>rule</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> add_fixer</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">F</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> fixer</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> F</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> where</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> F</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> Fn</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> bool</span><span style="color: #94E2D5;"> +</span><span style="color: #9399B2;"> &#39;</span><span style="color: #89B4FA;font-style: italic;">static</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>fixers</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Box</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>fixer</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Each <code>add_*</code> method is generic over <code>F</code>. The <code>where</code> clause constrains <code>F</code> to implement the appropriate <code>Fn</code> trait and be <code>'static</code>.</p> <p>The <code>'static</code> bound means the closure cannot contain borrowed references tied to shorter lifetimes. In practice, this usually means the closure either captures nothing or captures owned values using <code>move</code>.This is required because <code>Box&lt;dyn Fn(...)&gt;</code> does not carry lifetime information.</p> <p>When we call <code>Box::new(rule)</code>, Rust allocates the closure on the heap. The <code>Box&lt;F&gt;</code> is then coerced to <code>Box&lt;dyn Fn(...)&gt;</code> when pushed into the vector. The concrete type <code>F</code> is erased, replaced with a fat pointer that includes a vtable.</p> <h3 id="running-rules-and-fixers">Running Rules and Fixers</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Linter</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> check</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> content</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Violation</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> all_violations</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>line_num</span><span style="color: #9399B2;">,</span><span> line</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span> content</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">lines</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">enumerate</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> rule</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>rules </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> violations</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> rule</span><span style="color: #9399B2;">(</span><span>line</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> v</span><span style="color: #CBA6F7;"> in</span><span> violations</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> all_violations</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Violation</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span> line_num</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">:</span><span> v</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">message</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> all_violations</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> fix</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> content</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> fixed_count</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> fixer</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>fixers </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #89B4FA;font-style: italic;"> fixer</span><span style="color: #9399B2;">(</span><span>content</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> fixed_count</span><span style="color: #94E2D5;"> +=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> fixed_count</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>check</code> iterates over every line using <code>content.lines()</code>, which returns an iterator. <code>enumerate()</code> pairs each line with its 0-based index. We adjust to 1-based for human-friendly output. For each line, we iterate over every rule in <code>self.rules</code>. Each rule is a <code>Box&lt;dyn Fn(&amp;str) -&gt; Vec&lt;Violation&gt;&gt;</code>. When we call <code>rule(line)</code>, Rust:</p> <ol> <li>Reads the fat pointer from the Box</li> <li>Looks up <code>Fn::call</code> in the vtable</li> <li>Calls the closure's actual function through the vtable pointer</li> <li>Returns the <code>Vec&lt;Violation&gt;</code> result</li> </ol> <p>This is dynamic dispatch. The tiny runtime cost is the vtable lookup. <code>fix</code> is similar but passes <code>&amp;mut</code> content to each fixer. Fixers return <code>bool</code> to indicate whether they changed anything.</p> <h3 id="defining-lint-rules-as-closures">Defining Lint Rules as Closures</h3> <p>Now let's define some lint rules. Each rule is a closure that takes a line and returns violations.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> linter</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Linter</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Rule 1: Check for trailing whitespace</span></span> <span class="giallo-l"><span> linter</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add_rule</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>line</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> violations</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &gt;</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">trim_end</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span> violations</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Violation</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;Trailing whitespace&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> violations</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Rule 2: Check for lines longer than 80 characters</span></span> <span class="giallo-l"><span> linter</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add_rule</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>line</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> violations</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &gt;</span><span style="color: #FAB387;"> 80</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> violations</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Violation</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Line too long (</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> characters)&quot;</span><span style="color: #9399B2;">,</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> violations</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Rule 3: Check for hard tabs</span></span> <span class="giallo-l"><span> linter</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add_rule</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>line</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> violations</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">contains</span><span style="color: #9399B2;">(&#39;</span><span style="color: #F5C2E7;">\t</span><span style="color: #9399B2;">&#39;) {</span></span> <span class="giallo-l"><span> violations</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Violation</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;Hard tab detected, use spaces&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> violations</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Rule 4: Check for TODO and FIXME comments</span></span> <span class="giallo-l"><span> linter</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add_rule</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>line</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> violations</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">contains</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;TODO&quot;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> ||</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">contains</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;FIXME&quot;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> violations</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Violation</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;Contains TODO or FIXME marker&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> violations</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Each <code>linter.add_rule(...)</code> passes a closure. These closures don't capture anything from the environment, they only use their <code>line</code> parameter. Since they have no captures, Rust infers <code>Fn</code> for them, and they satisfy <code>'static</code> trivially.</p> <p>Each rule sets <code>line: 0</code> as a placeholder. The <code>check</code> method overwrites this with the actual line number when it iterates. The rules don't know their line number, they only analyze a single line.</p> <p>Let's trace through what happens when we call <code>linter.check</code>:</p> <ol> <li><code>check</code> opens the file and starts reading lines</li> <li>For line 1, it calls the first closure (trailing whitespace rule). Rust looks up the vtable, calls the closure, gets back a <code>Vec</code>. If the line has trailing spaces, the <code>Vec</code> has one violation. If not, it is empty.</li> <li>It calls the second closure (line length rule) on the same line. Same vtable lookup process.</li> <li>Continues for all four rules on line 1.</li> <li>Moves to line 2, repeats.</li> <li>All violations are collected into a single <code>Vec</code>.</li> </ol> <h3 id="a-fixer-closure">A Fixer Closure</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // ... rules from above ...</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Fixer: Remove trailing whitespace</span></span> <span class="giallo-l"><span> linter</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add_fixer</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>content</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> original</span><span style="color: #94E2D5;"> =</span><span> content</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> *</span><span>content</span><span style="color: #94E2D5;"> =</span><span> content</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">lines</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>line</span><span style="color: #94E2D5;">|</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">trim_end</span><span style="color: #9399B2;">())</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Vec</span><span style="color: #89DCEB;">&lt;</span><span>_</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #F5C2E7;">\n</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> original</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">ends_with</span><span style="color: #9399B2;">(&#39;</span><span style="color: #F5C2E7;">\n</span><span style="color: #9399B2;">&#39;) {</span></span> <span class="giallo-l"><span> content</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #F5C2E7;">\n</span><span style="color: #9399B2;">&#39;);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> *</span><span>content</span><span style="color: #94E2D5;"> !=</span><span> original</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This closure captures nothing. <code>content.clone()</code> saves the original so we can compare at the end. <code>content.lines()</code> returns an iterator over lines (without trailing newlines). <code>.map(|line| line.trim_end())</code> transforms each line by stripping trailing whitespace. <code>.collect::&lt;Vec&lt;_&gt;&gt;()</code> collects into a <code>Vec&lt;&amp;str&gt;</code>. <code>.join("\n")</code> joins them back with newlines.</p> <p>The tricky part: <code>lines()</code> does not include the trailing newline. If the original file ended with <code>\n</code>, the joined string won't have one. We check <code>original.ends_with('\n')</code> and push a newline if needed.</p> <p>The closure returns <code>*content != original</code>, <code>true</code> if we modified the content, <code>false</code> if it was already clean.</p> <h3 id="the-main-function">The Main Function</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // ... rule definitions and fixer from above ...</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> args</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">env</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">args</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> file_path</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if</span><span> args</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &gt;</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &amp;</span><span>args</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> eprintln!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Usage: cargo run -- &lt;file&gt;&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> content</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #F9E2AF;"> fs</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">read_to_string</span><span style="color: #9399B2;">(</span><span>file_path</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>s</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> s</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> eprintln!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Error reading </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> file_path</span><span style="color: #9399B2;">,</span><span> e</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> violations</span><span style="color: #94E2D5;"> =</span><span> linter</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">check</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>content</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> violations</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_empty</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;No violations found.&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> v</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>violations</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">:</span><span style="color: #9399B2;">{} {}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> file_path</span><span style="color: #9399B2;">,</span><span> v</span><span style="color: #94E2D5;">.</span><span>line</span><span style="color: #9399B2;">,</span><span> v</span><span style="color: #94E2D5;">.</span><span>message</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #F5C2E7;">\n</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> violation(s) found.&quot;</span><span style="color: #9399B2;">,</span><span> violations</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> fixed_count</span><span style="color: #94E2D5;"> =</span><span> linter</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">fix</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span> content</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> fixed_count</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #F5C2E7;">\n</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> fixer(s) applied.&quot;</span><span style="color: #9399B2;">,</span><span> fixed_count</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F9E2AF;"> fs</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">write</span><span style="color: #9399B2;">(</span><span>file_path</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>content</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(())</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;File updated.&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> eprintln!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Error writing </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> file_path</span><span style="color: #9399B2;">,</span><span> e</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>We read the file into a <code>String</code>, run check to collect violations, print them in <code>filename:line: message</code> format, then run fix to auto-correct. If any fixer applied changes, we write back to disk.</p> <p>The check method takes <code>&amp;self</code> because rules only read lines. The fix method also takes <code>&amp;self</code>, the mutation is on the external content parameter, not on self.</p> <h2 id="closures-that-capture">Closures That Capture</h2> <p>All the closures so far have been "pure" (no captures). Let's make things more interesting by capturing variables</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// Configurable max line length</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> max_line_length</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 100</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span>linter</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add_rule</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">move</span><span style="color: #94E2D5;"> |</span><span>line</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> violations</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &gt;</span><span> max_line_length</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> violations</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Violation</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;Line too long (</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> chars, max </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">)&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> max_line_length</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> violations</span></span> <span class="giallo-l"><span style="color: #9399B2;">});</span></span></code></pre> <p>The closure captures <code>max_line_length</code> from the surrounding scope. We use <code>move</code> to force ownership transfer into the closure.</p> <p>Without <code>move</code>, the closure would capture <code>&amp;max_line_length</code>, a reference to the local variable. But <code>Box&lt;dyn Fn(...)&gt;</code> requires the closure to be <code>'static</code>. If the closure held a reference to <code>max_line_length</code>, what happens when main returns and <code>max_line_length</code> is dropped? The reference would dangle. Rust prevents this at compile time.</p> <p>With <code>move</code>, the closure takes ownership of <code>max_line_length</code>. The <code>i32</code> value is copied into the closure's internal state (on the heap, inside the Box). Now the closure is self-contained and <code>'static</code>.</p> <h3 id="forbidden-words-rule">Forbidden Words Rule</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> forbidden_words</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #A6E3A1;">&quot;debug&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;println&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;unwrap&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;todo&quot;</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span>linter</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add_rule</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">move</span><span style="color: #94E2D5;"> |</span><span>line</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> violations</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> word</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>forbidden_words</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">contains</span><span style="color: #9399B2;">(</span><span>word</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> violations</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Violation</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Forbidden word &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39; found&quot;</span><span style="color: #9399B2;">,</span><span> word</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> violations</span></span> <span class="giallo-l"><span style="color: #9399B2;">});</span></span></code></pre> <p><code>move</code> gives ownership of the entire <code>Vec&lt;&amp;str&gt;</code> to the closure.The <code>Vec</code> stores its elements in a heap-allocated buffer, while the <code>Vec</code> struct itself contains pointer/len/cap metadata. With <code>move</code>, the closure owns this vector. Inside the closure, for word in <code>&amp;forbidden_words</code> borrows from the closure's own captured state.</p> <p>Closures let us package both behaviour and captured state together as a single value.</p> <h2 id="running-the-project">Running The Project</h2> <p>Create a test file:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cat</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #A6E3A1;"> test.rs</span><span style="color: #94E2D5;"> &lt;&lt;</span><span style="color: #A6E3A1;"> &#39;EOF&#39;</span></span> <span class="giallo-l"><span style="color: #A6E3A1;">fn main() {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> println!(&quot;hello world&quot;); </span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> let x = 10; // TODO: fix this</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> println!(&quot;{}&quot;, x);</span></span> <span class="giallo-l"><span style="color: #A6E3A1;">}</span></span> <span class="giallo-l"><span style="color: #A6E3A1;">EOF</span></span></code></pre> <p>This contains three trailing whitespace after the <code>println!("hello world");</code>.</p> <p>Now run the linter:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> run -- test.rs</span></span></code></pre> <p>You should see output like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">test</span><span style="color: #A6E3A1;">.rs:2 Trailing whitespace</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">test</span><span style="color: #A6E3A1;">.rs:3 Contains TODO or FIXME marker</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">2</span><span style="color: #A6E3A1;"> violation</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">s</span><span style="color: #9399B2;">)</span><span style="color: #A6E3A1;"> found.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">1</span><span style="color: #A6E3A1;"> fixer</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">s</span><span style="color: #9399B2;">)</span><span style="color: #A6E3A1;"> applied.</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">File</span><span style="color: #A6E3A1;"> updated.</span></span></code></pre> <p>The linter found trailing whitespace on line 2 and a TODO marker on line 3. The trailing whitespace fixer ran and cleaned up the file automatically.</p> 2026-05-23T00:00:00+00:00 2026-05-23T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/learn-the-basics-of-bevy-by-building-and-deploying-pong-to-itch-io/ <p>I'm starting a new series on learning game dev and Bevy game engine. I'll structure the articles so that in each article, we will build one game and learn different game dev and Bevy concepts. All the projects are coming from the <a rel="external" href="https://20_games_challenge.gitlab.io/challenge/">20 challenges list</a>.</p> <p>This is a learning series for me as well. I'm familiar with game dev but not with Bevy, this is why I'm writing these primarily for learning and sharing my knowledge with you. If there is any incorrect information, then please inform me, I'll rectify that asap.</p> <p>The only prerequisite is that you should know Rust or should be able to learn Rust concepts on the go. I have a <a rel="external" href="https://blog.sheerluck.dev/series/learning-rust/">Rust learning series</a> that follows the similar project building method. In every article we build a interesting project and learn Rust concepts. You can check that out or you can follow any other resource as well.</p> <p>In this post, we are going to build <strong>Pong</strong> and publish our game on <a rel="external" href="https://itch.io">Itch.io</a>, the classic arcade game where two players bounce a ball past each other's paddles. If you know Rust but have never built a game before, this is the perfect place to start. I'm really excited for this project and I hope you are too.</p> <p>We'll use <strong>Bevy</strong>, a Rust game engine. We'll learn the fundamentals of game development along the way: what a game loop is, how entities and components work, how collision detection works, how to handle player input, and how to display a score.</p> <p>Get the full source code from <a rel="external" href="https://github.com/MrSheerluck/bevy-pong">here</a> Published game link is <a rel="external" href="https://mrsheerluck.itch.io/pong-with-bevy-engine">here</a></p> <blockquote> <p>This series will be updated for future stable Bevy versions and if anything is incorrect, then please let me know I'll fix that ASAP.</p> </blockquote> <blockquote> <p>We might not follow standard patterns or best practices in our learning series as the goal is to build games incrementally. For example, in this article, we are not using any third party physics crate, instead we are implementing a manual AABB algorithm, which we won't do in future articles.</p> </blockquote> <blockquote> <p>I won't add game GIFs or images for any sections as that's really not required. You can just copy and run the section one by one and you'll get the game on your system without any issues.</p> </blockquote> <h2 id="what-is-a-game-engine">What Is a Game Engine?</h2> <p>Before writing any code, let's understand what a game engine actually does.</p> <p>At its core, a video game is just a loop. Every frame (usually 60 times per second), the game:</p> <ol> <li><strong>Reads input</strong> - what keys are the players pressing?</li> <li><strong>Updates the world</strong> - move the paddles, move the ball, check for collisions.</li> <li><strong>Renders</strong> - draw everything on the screen.</li> </ol> <p>This is called the <strong>game loop</strong>. Without an engine, you'd write this loop yourself, read input, update state, draw pixels. A game engine like Bevy handles the hard parts (rendering graphics, playing audio, handling window events) so you can focus on what makes your game unique.</p> <p>Bevy organizes game code using a pattern called <strong>ECS</strong>: Entity-Component-System. Let's understand each part:</p> <ul> <li><strong>Entity</strong>: A unique ID that represents something in your game. A paddle, a ball, the camera and so on.</li> <li><strong>Component</strong>: Data attached to an entity. Position, velocity, health, color and so on. Plain Rust structs with no methods.</li> <li><strong>System</strong>: A function that runs every frame and operates on entities that have specific components. A "movement" system finds all entities with a <code>Position</code> and <code>Velocity</code> and updates their positions.</li> </ul> <p><strong>Data and logic are separate</strong>. Components just sit there holding data. Systems read and modify components. This is different from object-oriented programming where objects contain both data and methods.</p> <h2 id="project-setup">Project Setup</h2> <p>Open your terminal and create a new Rust project:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo new bevy_pong</span></span> <span class="giallo-l"><span>cd bevy_pong</span></span></code></pre> <p>Now open <code>Cargo.toml</code> and replace its contents with:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;">[</span><span>package</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>name</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;bevy_pong&quot;</span></span> <span class="giallo-l"><span>version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.1.0&quot;</span></span> <span class="giallo-l"><span>edition</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;2024&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>dependencies</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>bevy</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.18&quot;</span></span></code></pre> <p>The <code>[dependencies]</code> section tells Cargo what external libraries to download. We add <code>bevy = "0.18"</code> which pulls in the Bevy engine at version 0.18.</p> <p>Now run:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo build</span></span></code></pre> <p>This will take a few minutes. Bevy is a large engine, it compiles the renderer (OpenGL/Metal/Vulkan), audio system, asset loader, input handler, and more. Subsequent builds will be fast because only your code changes need recompilation.</p> <h2 id="the-skeleton-opening-a-window">The Skeleton: Opening a Window</h2> <p>Let's write the smallest possible Bevy program. Open <code>src/main.rs</code> and type this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> bevy</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">prelude</span><span style="color: #94E2D5;">::*</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> App</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">add_plugins</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">DefaultPlugins</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">add_systems</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Startup</span><span style="color: #9399B2;">,</span><span> setup</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">run</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> setup</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">mut</span><span style="color: #EBA0AC;"> commands</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Commands</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Camera2d</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>use bevy::prelude::*;</code> imports the most common Bevy types. Without this, you'd write <code>bevy::ecs::system::Commands</code> instead of just <code>Commands</code>.</p> <h3 id="the-main-function">The <code>main</code> function</h3> <p><code>App::new()</code> creates a new, empty Bevy application. Think of <code>App</code> as your game's headquarters, it holds everything: the world (all entities and their components), the schedule (which systems run and when), and the plugins (bundled features).</p> <p><code>.add_plugins(DefaultPlugins)</code> is the most important line in any Bevy project. <code>DefaultPlugins</code> is a bundle of everything Bevy needs to function. It includes:</p> <ul> <li><strong>WindowPlugin</strong>: Creates a window on your screen.</li> <li><strong>RenderPlugin</strong>: Renders graphics using your GPU.</li> <li><strong>AssetPlugin</strong>: Loads files like images and sounds.</li> <li><strong>InputPlugin</strong>: Handles keyboard, mouse, and gamepad input.</li> <li><strong>AudioPlugin</strong>: Plays sounds.</li> </ul> <p><code>.add_systems(Startup, setup)</code> registers our <code>setup</code> function as a system that runs during the <code>Startup</code> schedule. A <strong>schedule</strong> determines <em>when</em> a system runs. Bevy has several schedules:</p> <ul> <li><strong>Startup</strong>: Runs once when the app starts. Use this for creating entities, loading assets, setting up initial state.</li> <li><strong>Update</strong>: Runs every frame. Use this for gameplay logic like movement, collision, input handling.</li> <li><strong>FixedUpdate</strong>: Runs at a fixed rate (independent of frame rate). Good for physics.</li> </ul> <p><code>.run()</code> starts the game loop. This function never returns, it runs until the player closes the window.</p> <h3 id="the-setup-function">The <code>setup</code> function</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> setup</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">mut</span><span style="color: #EBA0AC;"> commands</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Commands</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Camera2d</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>commands: Commands</code> is a queue of changes to make to the game world. When you call <code>commands.spawn(...)</code>, the entity is queued and created at a safe point during the frame.</p> <p><code>commands.spawn(Camera2d)</code> creates a new entity with a <code>Camera2d</code> component. In Bevy, <strong>components can require other components</strong>. <code>Camera2d</code> automatically brings along <code>Camera</code> (the camera settings), <code>Projection</code> (the math that converts 3D world coordinates to 2D screen pixels), and <code>Frustum</code> (for culling objects that are off-screen).</p> <p>Without a camera, there's nothing to render through.</p> <p>Run <code>cargo run</code>. You should see a window with a black background. That's your first running game.</p> <h2 id="understanding-coordinates">Understanding Coordinates</h2> <p>Before we place objects, let's understand how positions work in a 2D game.</p> <p>Your window is a flat rectangle. Every position on it is described by an <strong>(x, y)</strong> coordinate:</p> <ul> <li><strong>x</strong>: Horizontal position. 0 is the center. Negative is left. Positive is right.</li> <li><strong>y</strong>: Vertical position. 0 is the center. Negative is down. Positive is up.</li> </ul> <p>Coordinates are measured in <strong>pixels</strong>. If your window is 800 pixels wide, the left edge is at x = -400, the right edge is at x = 400, and the center is at x = 0.</p> <p>Each entity has a <code>Transform</code> component that stores its position, rotation, and scale. When you set <code>Transform::from_xyz(-350.0, 0.0, 0.0)</code>, you're moving that entity 350 pixels to the left of center.</p> <p>There's also a z component in the 3D vector. In a 2D game, z controls which objects appear on top of others. Higher z means closer to the camera. We leave it at 0 for everything.</p> <h2 id="setting-the-window-size-and-background">Setting the Window Size and Background</h2> <p>By default, Bevy creates a 1280x720 window with a dark grey background. Let's fix that to 800x600 with a black background, so our coordinate math is predictable:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> App</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">add_plugins</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">DefaultPlugins</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">set</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">WindowPlugin</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> primary_window</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Window</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> resolution</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;"> WindowResolution</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">800</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 600</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> title</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;Pong&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ..</span><span style="color: #89B4FA;font-style: italic;">default</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }),</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ..</span><span style="color: #89B4FA;font-style: italic;">default</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">insert_resource</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">ClearColor</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Color</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">srgb</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">)))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">add_systems</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Startup</span><span style="color: #9399B2;">,</span><span> setup</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">run</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Let me explain the new stuff.</p> <p><code>DefaultPlugins.set(WindowPlugin { ... })</code> - <code>DefaultPlugins</code> is configurable. The <code>.set()</code> method replaces its default <code>WindowPlugin</code> with our custom one.</p> <p><code>Window { resolution: ..., title: ..., ..default() }</code> - a <code>Window</code> struct with multiple settings. We only set two: <code>resolution</code> (800x600 pixels) and <code>title</code> ("Pong"). <code>..default()</code> fills in the rest: vsync enabled, resizable, decorated window frame, and so on.</p> <p><code>resolution: WindowResolution::new(800, 600)</code> - <code>WindowResolution::new</code> takes a width and height in logical pixels. On high-DPI displays, the actual physical pixels might be different, but Bevy handles that conversion.</p> <p><code>.insert_resource(ClearColor(Color::srgb(0.0, 0.0, 0.0)))</code> - <code>ClearColor</code> is a <strong>resource</strong>, which means there's exactly one instance of it in the world. It controls the background color rendered between frames. <code>Color::srgb(0.0, 0.0, 0.0)</code> is pure black (no red, no green, no blue).</p> <p>The reason we call it <code>insert_resource</code> instead of <code>spawn</code> is that resources are not entities. They're singletons (global data that any system can access). Entities are for things that exist in the game world (paddles, balls, walls). Resources are for game-wide state (score, settings, input state).</p> <h2 id="creating-our-game-objects">Creating Our Game Objects</h2> <p>Let's define the data that describes our paddles and ball. In ECS, data lives in components:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Component</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Paddle</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> speed</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> side</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Side</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Component</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Side</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Left</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Right</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Component</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Ball</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> velocity</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec3</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>#[derive(Component)]</code> is a derive macro that tells Bevy "this struct can be used as a component on an entity." It implements the <code>Component</code> trait, which provides metadata about the component.</p> <p><code>Paddle { speed: f32, side: Side }</code> - each paddle has a movement speed (pixels per second) and a side identifier (which player controls it).</p> <p><code>enum Side { Left, Right }</code> - yes, enums can be components too. We'll use this to determine which keyboard keys move which paddle.</p> <p><code>Ball { velocity: Vec3 }</code> - the ball's velocity is a 3D vector. Even in a 2D game, we use <code>Vec3</code> because <code>Transform</code> positions also use <code>Vec3</code>. The z component stays 0. The velocity determines how fast and in what direction the ball travels each frame.</p> <p>Now let's place these objects in the world. Update your <code>setup</code> function:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> setup</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">mut</span><span style="color: #EBA0AC;"> commands</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Commands</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Camera2d</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Left paddle</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">((</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Paddle</span><span style="color: #9399B2;"> {</span><span> speed</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 500</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span> side</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;"> Side</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Left</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Sprite</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_color</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Color</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">WHITE</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;"> Vec2</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">10</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 100</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Transform</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_xyz</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">-</span><span style="color: #FAB387;">350</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Right paddle</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">((</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Paddle</span><span style="color: #9399B2;"> {</span><span> speed</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 500</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span> side</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;"> Side</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Right</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Sprite</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_color</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Color</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">WHITE</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;"> Vec2</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">10</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 100</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Transform</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_xyz</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">350</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Ball</span></span> <span class="giallo-l"><span> commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">((</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ball</span><span style="color: #9399B2;"> {</span><span> velocity</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;"> Vec3</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">300</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 150</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">) },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Sprite</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_color</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Color</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">WHITE</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;"> Vec2</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">10</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Transform</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_xyz</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ));</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Each <code>commands.spawn((...))</code> call creates an entity with multiple components at once. The components are passed as a tuple. Bevy treats each element as a separate component and attaches all of them to the same entity.</p> <p><code>Sprite::from_color(Color::WHITE, Vec2::new(10.0, 100.0))</code> creates a visual rectangle without loading any image files. The first argument is the fill color, the second is the size in pixels. Left and right paddles are 10 pixels wide by 100 pixels tall. The ball is a 10x10 square.</p> <p><code>Transform::from_xyz(-350.0, 0.0, 0.0)</code> positions the left paddle 350 pixels to the left of center. Since our window is 800 pixels wide, the left edge is at -400, so the paddle sits 50 pixels from the left edge. The right paddle is at the mirror position. The ball starts at the exact center.</p> <p>The ball's velocity is <code>(300, 150, 0)</code> it moves 300 pixels per second to the right and 150 pixels per second upward. This diagonal path gives it an interesting angle.</p> <p>Run <code>cargo run</code>. You should see two white rectangles near the edges and a small white square in the center. Nothing moves yet, we need to write systems for that.</p> <h2 id="making-the-paddles-move">Making the Paddles Move</h2> <p>Now we write our first real gameplay system.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> move_paddle</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> keyboard</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Res</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">ButtonInput</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">KeyCode</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> paddle_query</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Transform</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #F9E2AF;font-style: italic;">Paddle</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> time</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Res</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Time</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span style="color: #CBA6F7;">mut</span><span> transform</span><span style="color: #9399B2;">,</span><span> paddle</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span> paddle_query</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> direction</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> paddle</span><span style="color: #94E2D5;">.</span><span>side </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Side</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Left</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> keyboard</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">pressed</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">KeyCode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">KeyW</span><span style="color: #9399B2;">) {</span><span> direction</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">; }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> keyboard</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">pressed</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">KeyCode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">KeyS</span><span style="color: #9399B2;">) {</span><span> direction</span><span style="color: #94E2D5;"> = -</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">; }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Side</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Right</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> keyboard</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">pressed</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">KeyCode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">ArrowUp</span><span style="color: #9399B2;">) {</span><span> direction</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">; }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> keyboard</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">pressed</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">KeyCode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">ArrowDown</span><span style="color: #9399B2;">) {</span><span> direction</span><span style="color: #94E2D5;"> = -</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">; }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">+=</span><span> direction</span><span style="color: #94E2D5;"> *</span><span> paddle</span><span style="color: #94E2D5;">.</span><span>speed </span><span style="color: #94E2D5;">*</span><span> time</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">delta_secs</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Let me explain every piece.</p> <h3 id="system-parameters">System Parameters</h3> <p>A Bevy system is just a Rust function. What makes it special is the <strong>parameters</strong>. Bevy automatically injects the right data based on the types in the function signature.</p> <p><code>keyboard: Res&lt;ButtonInput&lt;KeyCode&gt;&gt;</code> - <code>Res&lt;T&gt;</code> gives read-only access to a resource. <code>ButtonInput&lt;KeyCode&gt;</code> is Bevy's keyboard input resource. It tracks which keys are currently held down, which were just pressed this frame, and which were just released. We use <code>pressed(KeyCode::KeyW)</code> to check if a specific key is being held down right now.</p> <p><code>mut paddle_query: Query&lt;(&amp;mut Transform, &amp;Paddle)&gt;</code> - <code>Query</code> is how you find entities in the world. The type parameter <code>(&amp;mut Transform, &amp;Paddle)</code> means "give me mutable access to Transform and read-only access to Paddle, but only for entities that have BOTH of these components." Since both paddles have Transform and Paddle, this system processes both of them.</p> <p>The <code>mut</code> before <code>paddle_query</code> is required because we asked for mutable access to component data. The <code>mut</code> inside <code>&amp;mut Transform</code> means we can modify the position.</p> <p><code>time: Res&lt;Time&gt;</code> - the Time resource provides timing information. We use <code>delta_secs()</code>, the time in seconds since the last frame. This is crucial for smooth movement.</p> <h3 id="why-delta-time-matters">Why Delta Time Matters</h3> <p>Here's the problem every new game developer encounters. On a 60 Hz monitor, your game runs 60 times per second. On a 144 Hz monitor, it runs 144 times per second. If you moved the paddle 10 pixels every frame:</p> <ul> <li>At 60 FPS: 600 pixels per second</li> <li>At 144 FPS: 1440 pixels per second</li> </ul> <p>The game runs at a completely different speed on different monitors. This is called a <strong>frame rate dependency bug</strong>.</p> <p>The fix is to multiply your movement by <code>delta_secs()</code>:</p> <ul> <li>At 60 FPS: delta = 0.0167 seconds. 500 * 0.0167 = 8.35 pixels per frame.</li> <li>At 144 FPS: delta = 0.0069 seconds. 500 * 0.0069 = 3.47 pixels per frame.</li> </ul> <p>The per-frame movement is different, but over one second: 500 pixels in both cases. The game runs at the same speed regardless of monitor refresh rate.</p> <h3 id="direction-logic">Direction Logic</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> direction</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> paddle</span><span style="color: #94E2D5;">.</span><span>side </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Side</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Left</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> keyboard</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">pressed</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">KeyCode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">KeyW</span><span style="color: #9399B2;">) {</span><span> direction</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">; }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> keyboard</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">pressed</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">KeyCode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">KeyS</span><span style="color: #9399B2;">) {</span><span> direction</span><span style="color: #94E2D5;"> = -</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">; }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Side</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Right</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> keyboard</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">pressed</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">KeyCode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">ArrowUp</span><span style="color: #9399B2;">) {</span><span> direction</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">; }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> keyboard</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">pressed</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">KeyCode</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">ArrowDown</span><span style="color: #9399B2;">) {</span><span> direction</span><span style="color: #94E2D5;"> = -</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">; }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>We check which side this paddle is on and which keys are held. <code>direction</code> is 1.0 for up (positive y), -1.0 for down (negative y), and 0.0 if no keys are pressed.</p> <p>We use two separate <code>if</code> statements (not <code>if-else</code>) because both keys could be pressed simultaneously. If W and S are both held, <code>direction</code> gets set to 1.0 then immediately to -1.0. The last key check wins, in this case S takes priority. Not ideal (pressing both should cancel to zero), but functional enough for our first game.</p> <h3 id="the-movement-formula">The Movement Formula</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span>transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">+=</span><span> direction</span><span style="color: #94E2D5;"> *</span><span> paddle</span><span style="color: #94E2D5;">.</span><span>speed </span><span style="color: #94E2D5;">*</span><span> time</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">delta_secs</span><span style="color: #9399B2;">();</span></span></code></pre> <p>We add to the y component of the transform's translation. Translation is the position. <code>direction * speed * delta</code> gives us pixels to move this frame.</p> <h3 id="registering-the-system">Registering the System</h3> <p>Add this to your <code>main</code> function:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add_systems</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Update</span><span style="color: #9399B2;">,</span><span> move_paddle</span><span style="color: #9399B2;">)</span></span></code></pre> <p><code>Update</code> means this system runs every frame, 60+ times per second.</p> <p>Run it. You can now move the left paddle with W/S and the right paddle with Arrow Up/Down.</p> <h2 id="making-the-ball-move">Making the Ball Move</h2> <p>The ball movement system follows the exact same pattern:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> move_ball</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> ball_query</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Transform</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #F9E2AF;font-style: italic;">Ball</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> time</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Res</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Time</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span style="color: #CBA6F7;">mut</span><span> transform</span><span style="color: #9399B2;">,</span><span> ball</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span> ball_query</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> transform</span><span style="color: #94E2D5;">.</span><span>translation </span><span style="color: #94E2D5;">+=</span><span> ball</span><span style="color: #94E2D5;">.</span><span>velocity </span><span style="color: #94E2D5;">*</span><span> time</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">delta_secs</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The difference from the paddle system: instead of checking input and setting a direction, we just add the ball's velocity to its position every frame. Since the ball's velocity is <code>Vec3::new(300.0, 150.0, 0.0)</code>, it moves 300 pixels right and 150 pixels up per second.</p> <p>Registration:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add_systems</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Update</span><span style="color: #9399B2;">, (</span><span>move_paddle</span><span style="color: #9399B2;">,</span><span> move_ball</span><span style="color: #9399B2;">))</span></span></code></pre> <p>Using a tuple registers multiple systems in the same schedule.</p> <p>Run it. The ball flies diagonally off-screen. We need walls.</p> <h2 id="bouncing-off-walls">Bouncing Off Walls</h2> <p>The ball should bounce off the top and bottom of the window. Let's add collision detection:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> bounce_ball</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> ball_query</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Transform</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Ball</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> window</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Single</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">Window</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> With</span><span style="color: #89DCEB;">&lt;</span><span style="color: #EBA0AC;">bevy</span><span style="color: #94E2D5;">::</span><span style="color: #EBA0AC;">window</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">PrimaryWindow</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> half_height</span><span style="color: #94E2D5;"> =</span><span> window</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">height</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> /</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> ball_radius</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span style="color: #CBA6F7;">mut</span><span> transform</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> mut</span><span> ball</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span> ball_query</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Top wall</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">+</span><span> ball_radius</span><span style="color: #94E2D5;"> &gt;=</span><span> half_height</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">=</span><span> half_height</span><span style="color: #94E2D5;"> -</span><span> ball_radius</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> ball</span><span style="color: #94E2D5;">.</span><span>velocity</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">= -</span><span>ball</span><span style="color: #94E2D5;">.</span><span>velocity</span><span style="color: #94E2D5;">.</span><span>y</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Bottom wall</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">-</span><span> ball_radius</span><span style="color: #94E2D5;"> &lt;= -</span><span>half_height</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">= -</span><span>half_height</span><span style="color: #94E2D5;"> +</span><span> ball_radius</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> ball</span><span style="color: #94E2D5;">.</span><span>velocity</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">= -</span><span>ball</span><span style="color: #94E2D5;">.</span><span>velocity</span><span style="color: #94E2D5;">.</span><span>y</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="getting-the-window">Getting the Window</h3> <p><code>window: Single&lt;&amp;Window, With&lt;bevy::window::PrimaryWindow&gt;&gt;</code> this is a special system parameter that says "I need exactly one entity that matches these criteria." <code>Single&lt;T, F&gt;</code> is like <code>Query&lt;T, F&gt;</code> but it gives you the item directly instead of making you iterate. If zero or more than one entities match, the system panics. For the primary window, there's always exactly one.</p> <p><code>window.height()</code> returns the logical height of the window in pixels (600). Dividing by 2 gives us the distance from the center to the top edge (300).</p> <p><code>ball_radius = 5.0</code> our ball is 10x10 pixels, so its half-size (or "radius" for a square) is 5 pixels.</p> <h3 id="the-collision-check">The Collision Check</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">if</span><span> transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">+</span><span> ball_radius</span><span style="color: #94E2D5;"> &gt;=</span><span> half_height</span><span style="color: #9399B2;"> {</span></span></code></pre> <p>This checks if the ball's top edge (center y + half its height) has reached or passed the top of the window. If the ball center is at y = 297 and we add the radius of 5, we get 302, which is &gt;= 300. Collision detected.</p> <p>When a collision happens, we do two things:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span>transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">=</span><span> half_height</span><span style="color: #94E2D5;"> -</span><span> ball_radius</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span>ball</span><span style="color: #94E2D5;">.</span><span>velocity</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">= -</span><span>ball</span><span style="color: #94E2D5;">.</span><span>velocity</span><span style="color: #94E2D5;">.</span><span>y</span><span style="color: #9399B2;">;</span></span></code></pre> <p>First, we <strong>snap the ball back inside</strong> the play area. We set its y position to <code>half_height - ball_radius</code> = 300 - 5 = 295. This prevents the ball from getting stuck outside the wall.</p> <p>You might ask: <strong>why would it get stuck?</strong> Imagine the ball is fast (say 600 pixels per second) and the frame rate drops to 30 FPS. The ball moves 20 pixels in one frame. If it was at y = 290 and moved 20 pixels up, it'd be at y = 310. Next frame, it's still past the wall, so it bounces again, reversing direction again. But it's still past the wall because it bounced back only 10 pixels. It vibrates in place. Snapping ensures this never happens.</p> <p>Second, we reverse the Y velocity. If the ball was moving upward (+150), it now moves downward (-150).</p> <p>The bottom wall check is the mirror: <code>transform.translation.y - ball_radius &lt;= -half_height</code>.</p> <p>Registration:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add_systems</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Update</span><span style="color: #9399B2;">, (</span><span>move_paddle</span><span style="color: #9399B2;">,</span><span> move_ball</span><span style="color: #9399B2;">,</span><span> bounce_ball</span><span style="color: #9399B2;">))</span></span></code></pre> <p>Run it. The ball bounces off the top and bottom walls endlessly.</p> <h2 id="bouncing-off-paddles">Bouncing Off Paddles</h2> <p>Now the interesting part, making the ball bounce off the paddles. We'll use <strong>AABB collision detection</strong> (Axis-Aligned Bounding Box). This detects if two rectangles overlap.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> check_paddle_collision</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> ball_query</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Transform</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Ball</span><span style="color: #9399B2;">),</span><span style="color: #F9E2AF;font-style: italic;"> Without</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Paddle</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> paddle_query</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">Transform</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #F9E2AF;font-style: italic;">Paddle</span><span style="color: #9399B2;">),</span><span style="color: #F9E2AF;font-style: italic;"> Without</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Ball</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span style="color: #CBA6F7;">mut</span><span> ball_transform</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> mut</span><span> ball</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span> ball_query</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> ball_pos</span><span style="color: #94E2D5;"> =</span><span> ball_transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">truncate</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> ball_size</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec2</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">10</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>paddle_transform</span><span style="color: #9399B2;">,</span><span> _paddle</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>paddle_query</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> paddle_pos</span><span style="color: #94E2D5;"> =</span><span> paddle_transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">truncate</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> paddle_size</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec2</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">10</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 100</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // AABB collision check</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> overlap</span><span style="color: #94E2D5;"> = !</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span> ball_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">+</span><span> ball_size</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> &lt;</span><span> paddle_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">-</span><span> paddle_size</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ||</span><span> ball_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">-</span><span> ball_size</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> &gt;</span><span> paddle_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">+</span><span> paddle_size</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ||</span><span> ball_pos</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">+</span><span> ball_size</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> &lt;</span><span> paddle_pos</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">-</span><span> paddle_size</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ||</span><span> ball_pos</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">-</span><span> ball_size</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> &gt;</span><span> paddle_pos</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">+</span><span> paddle_size</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span></span> <span class="giallo-l"><span style="color: #9399B2;"> );</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> overlap</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> ball</span><span style="color: #94E2D5;">.</span><span>velocity</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">= -</span><span>ball</span><span style="color: #94E2D5;">.</span><span>velocity</span><span style="color: #94E2D5;">.</span><span>x</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> ball</span><span style="color: #94E2D5;">.</span><span>velocity</span><span style="color: #94E2D5;">.</span><span>x</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> ball_transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">=</span><span> paddle_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">+</span><span> paddle_size</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> +</span><span> ball_size</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> ball_transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">=</span><span> paddle_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">-</span><span> paddle_size</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> -</span><span> ball_size</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="disjoint-queries">Disjoint Queries</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">mut</span><span> ball_query</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Transform</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Ball</span><span style="color: #9399B2;">),</span><span style="color: #F9E2AF;font-style: italic;"> Without</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Paddle</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span>paddle_query</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">Transform</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #F9E2AF;font-style: italic;">Paddle</span><span style="color: #9399B2;">),</span><span style="color: #F9E2AF;font-style: italic;"> Without</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Ball</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span></code></pre> <p>Both queries use <code>Without&lt;T&gt;</code> filters. <code>Without&lt;Paddle&gt;</code> on the ball query means "only match entities that don't have a Paddle component." <code>Without&lt;Ball&gt;</code> on the paddle query means the opposite.</p> <p>Why? Because Bevy needs to prove that these two queries never access the same entity. If they could, we'd have a data race, one query mutably accessing Transform while another query also accesses it. The <code>Without</code> filters tell Bevy "these are completely separate groups of entities," so it can run them safely.</p> <h3 id="how-aabb-collision-works">How AABB Collision Works</h3> <p>Imagine two rectangles on screen. They overlap if they are <strong>not separated along any axis</strong>. A rectangle is separated from another if:</p> <ol> <li>Its right edge is to the left of the other's left edge.</li> <li>Its left edge is to the right of the other's right edge.</li> <li>Its top edge is below the other's bottom edge.</li> <li>Its bottom edge is above the other's top edge.</li> </ol> <p>If any one of these is true, they don't overlap. If all four are false, they overlap.</p> <p>Our check:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> overlap</span><span style="color: #94E2D5;"> = !</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span> ball_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">+</span><span> ball_size</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> &lt;</span><span> paddle_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">-</span><span> paddle_size</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ||</span><span> ball_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">-</span><span> ball_size</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> &gt;</span><span> paddle_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">+</span><span> paddle_size</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ||</span><span> ball_pos</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">+</span><span> ball_size</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> &lt;</span><span> paddle_pos</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">-</span><span> paddle_size</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ||</span><span> ball_pos</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">-</span><span> ball_size</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> &gt;</span><span> paddle_pos</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">+</span><span> paddle_size</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span></span> <span class="giallo-l"><span style="color: #9399B2;">);</span></span></code></pre> <p><code>ball_pos.x + ball_size.x / 2.0</code> is the ball's right edge. <code>paddle_pos.x - paddle_size.x / 2.0</code> is the paddle's left edge. If the ball's right edge is to the left of the paddle's left edge, they're separated horizontally. We OR all four checks together and NOT the result.</p> <h3 id="collision-response">Collision Response</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">if</span><span> overlap</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> ball</span><span style="color: #94E2D5;">.</span><span>velocity</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">= -</span><span>ball</span><span style="color: #94E2D5;">.</span><span>velocity</span><span style="color: #94E2D5;">.</span><span>x</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> ball</span><span style="color: #94E2D5;">.</span><span>velocity</span><span style="color: #94E2D5;">.</span><span>x</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> ball_transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">=</span><span> paddle_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">+</span><span> paddle_size</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> +</span><span> ball_size</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> ball_transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">=</span><span> paddle_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">-</span><span> paddle_size</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> -</span><span> ball_size</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">/</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>When a collision happens, we reverse the ball's X direction. Then we snap the ball to the outside of the paddle. If the ball is moving right (velocity.x &gt; 0), it hit the left side of the paddle, so we place it just to the right of the paddle's left edge. If moving left, we place it just to the left of the paddle's right edge.</p> <p>The snap prevents the same problem as wall bouncing. Without it, the ball can get stuck inside the paddle, bouncing back and forth every frame until it wiggles through.</p> <p>Registration:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add_systems</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Update</span><span style="color: #9399B2;">, (</span><span>move_paddle</span><span style="color: #9399B2;">,</span><span> move_ball</span><span style="color: #9399B2;">,</span><span> bounce_ball</span><span style="color: #9399B2;">,</span><span> check_paddle_collision</span><span style="color: #9399B2;">))</span></span></code></pre> <p>Run it. You can now play Pong, the ball bounces off both paddles and the top/bottom walls.</p> <h2 id="adding-a-score">Adding a Score</h2> <p>A game of Pong is meaningless without keeping score. Let's add scoring and a display.</p> <h3 id="score-resource-and-text-marker">Score Resource and Text Marker</h3> <p>Add these near your component definitions:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Resource</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Default</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Score</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> left</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> u32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> right</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> u32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Component</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> ScoreText</span><span style="color: #9399B2;">;</span></span></code></pre> <p><code>Score</code> is a <strong>resource</strong>, a singleton piece of data. Unlike components that belong to entities, resources are global. There's only one score in the game. <code>#[derive(Default)]</code> initializes both fields to 0.</p> <p><code>ScoreText</code> is an empty <strong>marker component</strong>. We'll attach it to the text entity so we can find it later with a query. Without this, we'd have no way to distinguish the score text from other text entities.</p> <h3 id="spawning-the-score-display">Spawning the Score Display</h3> <p>Add this to your <code>setup</code> function:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span>commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">((</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Text2d</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;0 - 0&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TextFont</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> font_size</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 40</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ..</span><span style="color: #89B4FA;font-style: italic;">default</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> TextColor</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Color</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">WHITE</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Transform</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_xyz</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 250</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> ScoreText</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>commands</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert_resource</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Score</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">default</span><span style="color: #9399B2;">());</span></span></code></pre> <p><code>Text2d::new("0 - 0")</code> in Bevy 0.18, text display uses the <code>Text2d</code> component (for text positioned in the 2D world). It wraps a <code>String</code>. The initial text shows "0 - 0".</p> <p><code>TextFont { font_size: 40.0, ..default() }</code> controls the font style. We set the size to 40 pixels and use the default font (Fira Mono, bundled with Bevy).</p> <p><code>TextColor(Color::WHITE)</code> makes the text white.</p> <p><code>Transform::from_xyz(0.0, 250.0, 0.0)</code> positions the text near the top of the screen. Our window is 600 pixels tall, so y = 300 is the top edge. We place it at y = 250 so it's near the top but not at the very edge.</p> <p><code>commands.insert_resource(Score::default())</code> inserts the Score resource into the world with both counters at 0.</p> <h3 id="the-scoring-system">The Scoring System</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> score_goal</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> ball_query</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Transform</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> With</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Ball</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> score</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> ResMut</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Score</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> window</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Single</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">Window</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> With</span><span style="color: #89DCEB;">&lt;</span><span style="color: #EBA0AC;">bevy</span><span style="color: #94E2D5;">::</span><span style="color: #EBA0AC;">window</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">PrimaryWindow</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> score_text</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Text2d</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> With</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">ScoreText</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> width</span><span style="color: #94E2D5;"> =</span><span> window</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">width</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> half_width</span><span style="color: #94E2D5;"> =</span><span> width</span><span style="color: #94E2D5;"> /</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for mut</span><span> transform</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span> ball_query</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>x</span><span style="color: #94E2D5;"> &gt;</span><span> half_width</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> score</span><span style="color: #94E2D5;">.</span><span>left </span><span style="color: #94E2D5;">+=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> transform</span><span style="color: #94E2D5;">.</span><span>translation </span><span style="color: #94E2D5;">=</span><span style="color: #F9E2AF;font-style: italic;"> Vec3</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else if</span><span> transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;"> -</span><span>half_width</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> score</span><span style="color: #94E2D5;">.</span><span>right </span><span style="color: #94E2D5;">+=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> transform</span><span style="color: #94E2D5;">.</span><span>translation </span><span style="color: #94E2D5;">=</span><span style="color: #F9E2AF;font-style: italic;"> Vec3</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> continue</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for mut</span><span> text</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span> score_text</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> text</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> - </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> score</span><span style="color: #94E2D5;">.</span><span>left</span><span style="color: #9399B2;">,</span><span> score</span><span style="color: #94E2D5;">.</span><span>right</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>ResMut&lt;Score&gt;</code> <code>ResMut</code> gives mutable access to a resource. We need to modify the score counters.</p> <p><code>With&lt;Ball&gt;</code> we only want the ball entity, so we filter for entities that have a <code>Ball</code> component.</p> <p><code>Query&lt;&amp;mut Text2d, With&lt;ScoreText&gt;&gt;</code> finds the text entity by its marker component.</p> <p>The scoring logic:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">if</span><span> transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>x</span><span style="color: #94E2D5;"> &gt;</span><span> half_width</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> score</span><span style="color: #94E2D5;">.</span><span>left </span><span style="color: #94E2D5;">+=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ...</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span><span style="color: #CBA6F7;"> else if</span><span> transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;"> -</span><span>half_width</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> score</span><span style="color: #94E2D5;">.</span><span>right </span><span style="color: #94E2D5;">+=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ...</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>If the ball goes past the right edge (plus a 10-pixel buffer so it fully disappears), the <strong>left</strong> player scores the right player failed to return it. If it goes past the left edge, the <strong>right</strong> player scores.</p> <p>After scoring, we reset the ball to the center. The ball keeps its current velocity, it doesn't restart from zero speed. In a later version, we'll randomize the restart direction.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span>text</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> - </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> score</span><span style="color: #94E2D5;">.</span><span>left</span><span style="color: #9399B2;">,</span><span> score</span><span style="color: #94E2D5;">.</span><span>right</span><span style="color: #9399B2;">);</span></span></code></pre> <p><code>text.0</code> accesses the inner <code>String</code> of the <code>Text2d</code> tuple struct. We update it with the current score.</p> <p>Registration:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add_systems</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Update</span><span style="color: #9399B2;">, (</span><span>move_paddle</span><span style="color: #9399B2;">,</span><span> move_ball</span><span style="color: #9399B2;">,</span><span> bounce_ball</span><span style="color: #9399B2;">,</span><span> check_paddle_collision</span><span style="color: #9399B2;">,</span><span> score_goal</span><span style="color: #9399B2;">))</span></span></code></pre> <p>Run it. Play a game. The score updates at the top of the screen whenever a player misses the ball.</p> <h2 id="deploying-the-game-to-itch-io">Deploying the Game to itch.io</h2> <p>Now let's build a web version of the game and upload it to itch.io so anyone can play it in their browser.</p> <p>We'll use the <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli?utm_source=chatgpt.com">bevy_cli</a> tool to build a WebAssembly version of the game.</p> <p>First, install the wasm target:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">rustup</span><span style="color: #A6E3A1;"> target add wasm32-unknown-unknown</span></span></code></pre> <p>Then install the Bevy CLI:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> install bevy_cli</span></span></code></pre> <p>Now build the web release:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">bevy</span><span style="color: #A6E3A1;"> build --release web</span></span></code></pre> <p>This compiles the game into WebAssembly and generates the web runtime files.</p> <p>After the build finishes, you'll find the generated files in:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>target/wasm32-unknown-unknown/web-release/</span></span></code></pre> <p>Inside that directory, you should see files similar to:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>bevy_pong.js</span></span> <span class="giallo-l"><span>bevy_pong.wasm</span></span> <span class="giallo-l"><span>bevy_pong_bg.wasm</span></span></code></pre> <p>However, this is not yet a complete website. We still need an <code>index.html</code> file that loads the game.</p> <p>Create a file named <code>index.html</code> in the <code>web-release</code> directory:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="html"><span class="giallo-l"><span style="color: #CBA6F7;">&lt;!DOCTYPE</span><span style="color: #F9E2AF;"> html</span><span style="color: #CBA6F7;">&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span style="color: #89B4FA;">html</span><span style="color: #F9E2AF;"> lang</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;en&quot;</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span style="color: #89B4FA;">head</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &lt;</span><span style="color: #89B4FA;">meta</span><span style="color: #F9E2AF;"> charset</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;UTF-8&quot;</span><span style="color: #94E2D5;"> /&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &lt;</span><span style="color: #89B4FA;">meta</span><span style="color: #F9E2AF;"> name</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;viewport&quot;</span><span style="color: #F9E2AF;"> content</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;width=device-width, initial-scale=1.0&quot;</span><span style="color: #94E2D5;"> /&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #94E2D5;"> &lt;</span><span style="color: #89B4FA;">title</span><span style="color: #94E2D5;">&gt;</span><span>Bevy Pong</span><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">title</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #94E2D5;"> &lt;</span><span style="color: #89B4FA;">style</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> body</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> margin</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> overflow</span><span style="color: #94E2D5;">:</span><span> hidden</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> background</span><span style="color: #94E2D5;">:</span><span> black</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;"> canvas</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> width</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 100</span><span style="color: #CBA6F7;">vw</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> height</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 100</span><span style="color: #CBA6F7;">vh</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> display</span><span style="color: #94E2D5;">:</span><span> block</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #94E2D5;">/</span><span style="color: #89B4FA;">style</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">head</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span style="color: #89B4FA;">body</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &lt;</span><span style="color: #89B4FA;">script</span><span style="color: #F9E2AF;"> type</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">&quot;module&quot;</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> import</span><span> init</span><span style="color: #CBA6F7;"> from</span><span style="color: #A6E3A1;"> &quot;./bevy_pong.js&quot;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> init</span><span>()</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> &lt;</span><span style="color: #94E2D5;">/</span><span style="color: #89B4FA;">script</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">body</span><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;/</span><span style="color: #89B4FA;">html</span><span style="color: #94E2D5;">&gt;</span></span></code></pre> <p>Your final directory should look like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>web-release/</span></span> <span class="giallo-l"><span>├── index.html</span></span> <span class="giallo-l"><span>├── bevy_pong.js</span></span> <span class="giallo-l"><span>├── bevy_pong.wasm</span></span> <span class="giallo-l"><span>├── bevy_pong_bg.wasm</span></span> <span class="giallo-l"><span>└── assets/</span></span></code></pre> <p>One important thing: do <strong>not</strong> zip the entire <code>web-release</code> directory directly. It contains extra build artifacts like <code>deps</code>, <code>incremental</code>, and <code>build</code> folders that itch.io does not need.</p> <p>Instead, create a clean deployment folder:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">mkdir</span><span style="color: #A6E3A1;"> itch_build</span></span></code></pre> <p>Copy only the required runtime files:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cp</span><span style="color: #A6E3A1;"> target/wasm32-unknown-unknown/web-release/bevy_pong.js itch_build/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cp</span><span style="color: #A6E3A1;"> target/wasm32-unknown-unknown/web-release/bevy_pong.wasm itch_build/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cp</span><span style="color: #A6E3A1;"> target/wasm32-unknown-unknown/web-release/bevy_pong_bg.wasm itch_build/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cp</span><span style="color: #A6E3A1;"> target/wasm32-unknown-unknown/web-release/index.html itch_build/</span></span></code></pre> <p>Now create the zip:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> itch_build</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">zip</span><span style="color: #A6E3A1;"> -r bevy_pong.zip .</span></span></code></pre> <p>The zip contents should look like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>bevy_pong.zip</span></span> <span class="giallo-l"><span>├── index.html</span></span> <span class="giallo-l"><span>├── bevy_pong.js</span></span> <span class="giallo-l"><span>├── bevy_pong.wasm</span></span> <span class="giallo-l"><span>├── bevy_pong_bg.wasm</span></span> <span class="giallo-l"><span>└── assets/</span></span></code></pre> <p>Upload <code>bevy_pong.zip</code> to <a rel="external" href="https://itch.io/?utm_source=chatgpt.com">itch.io</a> and enable:</p> <ul> <li>"This file will be played in the browser"</li> </ul> <p>Once uploaded, your game can run directly in the browser without players installing anything.</p> <h2 id="things-we-could-improve">Things We Could Improve</h2> <ul> <li>Both the player paddles can be moved out of the viewport, you can take this as a mini challenge and fix this.</li> <li>Adding a simple sound whenever ball touches either paddle or walls</li> </ul> <h2 id="conclusion">Conclusion</h2> <p>This was a long one. I can go on and add other concepts as well but its already too long for our first article in this series. We have tons of chances to learn and reinforce our knowledge in future projects, so lets not worry about it. I hope you understood the overall basic concepts of Bevy and don't worry all these concepts will solidify in future with more and more projects.</p> <p>In the next post, we'll work on building a flappy bird clone by using external free assets, add sounds and particle effects and some physics concepts too.</p> <p>See you in the next one.</p> 2026-05-19T00:00:00+00:00 2026-05-19T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/learn-hashmap-iterators-by-building-a-git-object-store-reader/ <p>In this post, we are going to learn about <code>HashMap</code> and the <code>Iterator</code> trait in Rust. Once we cover all the concepts, we will build a <strong>Git Object Store Reader</strong> that reads a real <code>.git</code> folder, decompresses loose objects, decodes commits/trees/blobs, and renders <code>git log --oneline</code> output. I'm really excited for this project and I hope you are too. I won't go too deep in theory, just practical and we will build our knowledge of these concepts over time with more articles.</p> <p>The only prerequisite is that you have read the previous articles in this series, as I will assume you know ownership, borrowing, structs, enums, pattern matching, error handling, generics, traits, and lifetimes.</p> <p>Get the source code <a rel="external" href="https://github.com/MrSheerluck/git-log-in-rust">here</a></p> <h2 id="hashmap">HashMap</h2> <p>We have been using <code>Vec&lt;(String, JsonValue)&gt;</code> as a stand-in for objects in the JSON parser because we had not covered HashMap yet. Now it's time to learn this.</p> <p><code>HashMap&lt;K, V&gt;</code> is a hash table that maps keys of type <code>K</code> to values of type <code>V</code>. It gives you O(1) average lookups, insertions, and deletions.</p> <h3 id="hashmap-insertion-operation">HashMap Insertion Operation</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">collections</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">HashMap</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> scores</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> HashMap</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>scores</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Alice&quot;</span><span style="color: #9399B2;">),</span><span style="color: #FAB387;"> 100</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span>scores</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Bob&quot;</span><span style="color: #9399B2;">),</span><span style="color: #FAB387;"> 80</span><span style="color: #9399B2;">);</span></span></code></pre><h3 id="hashmap-retrieving-values">HashMap Retrieving Values</h3> <p>You can look up values by key:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> alice_score</span><span style="color: #94E2D5;"> =</span><span> scores</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Alice&quot;</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // Option&lt;&amp;i32&gt;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> alice_score</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>score</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Alice scored </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> score</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Alice not found&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>get</code> returns <code>Option&lt;&amp;V&gt;</code>. If the key exists, you get <code>Some(&amp;value)</code>. If not, <code>None</code>.</p> <p>You can iterate over entries:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">for</span><span style="color: #9399B2;"> (</span><span>name</span><span style="color: #9399B2;">,</span><span> score</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>scores</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> name</span><span style="color: #9399B2;">,</span><span> score</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="entry-api">Entry API</h3> <p>The entry API is one of the most useful features of <code>HashMap</code>. It lets you check if a key exists and act on it in one step:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span>scores</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">entry</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Alice&quot;</span><span style="color: #9399B2;">))</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">or_insert</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">50</span><span style="color: #9399B2;">);</span></span></code></pre> <p><code>entry</code> returns an <code>Entry</code> enum. <code>or_insert</code> inserts the value if the key does not exist, or returns a mutable reference to the existing value.</p> <p>Without the entry API, you'd have to write:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">if</span><span style="color: #94E2D5;"> !</span><span>scores</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">contains_key</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Alice&quot;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> scores</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Alice&quot;</span><span style="color: #9399B2;">),</span><span style="color: #FAB387;"> 50</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>That's two lookups instead of one. The entry API does it in a single operation.</p> <p>You can also update based on the existing value:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> map</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> HashMap</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">for</span><span> word</span><span style="color: #CBA6F7;"> in</span><span style="color: #A6E3A1;"> &quot;hello world hello&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">split_whitespace</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> count</span><span style="color: #94E2D5;"> =</span><span> map</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">entry</span><span style="color: #9399B2;">(</span><span>word</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">or_insert</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> *</span><span>count</span><span style="color: #94E2D5;"> +=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>map.entry(word)</code> looks up the word in the map. If the word doesn't exist, <code>or_insert(0)</code> inserts it with a starting count of 0 and returns a <code>&amp;mut i32</code> pointing to that new entry. If the word already exists, <code>or_insert</code> returns a <code>&amp;mut i32</code> pointing to the existing count. Either way, we get a mutable reference to the counter. Then <code>*count += 1</code> dereferences it and increments the value. After this loop, <code>map</code> contains <code>{"hello": 2, "world": 1}</code>.</p> <h3 id="ownership">Ownership</h3> <p>When you insert a <code>String</code> into a <code>HashMap</code>, the map takes ownership of the string. If you insert a reference, you must ensure the reference outlives the map.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> map</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> HashMap</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> key</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;name&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> value</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Alice&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span>map</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span>key</span><span style="color: #9399B2;">,</span><span> value</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // ownership moves into map</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// println!(&quot;{}&quot;, key); // ERROR: key was moved</span></span></code></pre> <p>Both <code>key</code> and <code>value</code> are <code>String</code>s. When we call <code>map.insert(key, value)</code>, ownership of both strings moves into the map. After that line, we can no longer use <code>key</code> or <code>value</code>. If we tried to print <code>key</code>, the compiler would say "value used here after move." This is the same ownership rule that applies everywhere in Rust: when you give something to a collection, the collection owns it now.</p> <h2 id="the-iterator-trait">The Iterator Trait</h2> <p>You have been using iterators since the mini grep project. Every time you call <code>.iter()</code>, <code>.into_iter()</code>, <code>.lines()</code>, or write a <code>for</code> loop, you are using the Iterator trait. Now let's understand what it actually is.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">pub trait</span><span style="color: #F9E2AF;font-style: italic;"> Iterator</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> type</span><span style="color: #F9E2AF;font-style: italic;"> Item</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> next</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F38BA8;">Self</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Item</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // many provided methods</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>That's it. An iterator is just something that has a <code>next</code> method. Each call to <code>next</code> returns either <code>Some(item)</code> or <code>None</code> when the iteration is finished.</p> <h3 id="for-loops-desugar-to-iterators"><code>for</code> Loops Desugar to Iterators</h3> <p>When you write:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> v</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">for</span><span> x</span><span style="color: #CBA6F7;"> in</span><span> v</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Rust desugars it into:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> iter</span><span style="color: #94E2D5;"> =</span><span> v</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into_iter</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">while let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>x</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> iter</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">next</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>for</code> calls <code>.into_iter()</code> on the collection, then repeatedly calls <code>.next()</code> on the resulting iterator.</p> <h3 id="three-forms-of-iteration">Three Forms of Iteration</h3> <p>Rust provides three ways to get an iterator from a collection:</p> <table><thead><tr><th>Method</th><th>Produces</th><th>Meaning</th></tr></thead><tbody> <tr><td><code>.iter()</code></td><td><code>&amp;T</code></td><td>Immutable references</td></tr> <tr><td><code>.iter_mut()</code></td><td><code>&amp;mut T</code></td><td>Mutable references</td></tr> <tr><td><code>into_iter()</code></td><td><code>T</code></td><td>Owned values (consumes the collection)</td></tr> </tbody></table> <p>Here is what each looks like:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> v</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">for</span><span> x</span><span style="color: #CBA6F7;"> in</span><span> v</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // x: &amp;i32 - we borrow each element</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">for</span><span> x</span><span style="color: #CBA6F7;"> in</span><span> v</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter_mut</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // x: &amp;mut i32 - we can modify each element</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">for</span><span> x</span><span style="color: #CBA6F7;"> in</span><span> v</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into_iter</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // x: i32 - we own each element, v is consumed</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// println!(&quot;{:?}&quot;, v); // ERROR: v was moved in into_iter()</span></span></code></pre><h3 id="consuming-adapters">Consuming Adapters</h3> <p>Some iterator methods consume the iterator and produce a value. <code>collect</code> and <code>count</code> are common examples.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> v</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 4</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> count</span><span style="color: #94E2D5;"> =</span><span> v</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">count</span><span style="color: #9399B2;">();</span><span style="color: #9399B2;font-style: italic;"> // 5</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> doubled</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> v</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>x</span><span style="color: #94E2D5;">|</span><span> x</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span></code></pre> <p><code>count</code> exhausts the iterator and returns the number of elements. <code>collect</code> exhausts the iterator and gathers elements into a collection. You need to specify the collection type (like <code>Vec&lt;i32&gt;</code>) because <code>collect</code> can produce many types.</p> <h3 id="iterator-adapters">Iterator Adapters</h3> <p>Iterator adapters transform one iterator into another iterator. They are lazy, meaning they do not execute immediately. Instead, they create a new iterator that describes how values should be processed. The actual work only happens when a consuming operation like <code>collect</code>, <code>count</code>, or <code>for_each</code> starts pulling values out with <code>next()</code>.</p> <p><code>map</code> transforms each element:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> v</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> squares</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> v</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>x</span><span style="color: #94E2D5;">|</span><span> x</span><span style="color: #94E2D5;"> *</span><span> x</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// squares = [1, 4, 9]</span></span></code></pre> <p><code>v.iter()</code> produces <code>&amp;i32</code> values. The closure receives each element one by one and returns a transformed value. Here, every number is squared. <code>map</code> does not modify the original vector. It creates a new iterator that yields transformed values lazily.</p> <p><code>filter</code> keeps only elements that match a condition:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> v</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 4</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> evens</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">i32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> v</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">filter</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>x</span><span style="color: #94E2D5;">| *</span><span>x</span><span style="color: #94E2D5;"> %</span><span style="color: #FAB387;"> 2</span><span style="color: #94E2D5;"> ==</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// evens = [2, 4]</span></span></code></pre> <p><code>filter</code> takes a closure that returns <code>true</code> or <code>false</code>. If the closure returns <code>true</code>, the element stays in the iterator. If it returns <code>false</code>, the element is skipped.</p> <p>Notice the resulting type is <code>Vec&lt;&amp;i32&gt;</code>, not <code>Vec&lt;i32&gt;</code>. <code>v.iter()</code> yields references, so <code>filter</code> also yields references.</p> <p><code>take</code> limits how many elements are produced:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> v</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 4</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> first_three</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">i32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> v</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">take</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// first_three = [1, 2, 3]</span></span></code></pre> <p><code>take(3)</code> stops the iterator after producing three elements. Even if the original iterator has more values, iteration ends early.</p> <p><code>skip</code> ignores the first N elements:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> v</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 4</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> after_two</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">i32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> v</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">skip</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// after_two = [3, 4, 5]</span></span></code></pre> <p><code>skip(2)</code> discards the first two values before yielding anything.</p> <p><code>chain</code> combines two iterators into one continuous iterator:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> a</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> b</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 4</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> chained</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">i32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> a</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">chain</span><span style="color: #9399B2;">(</span><span>b</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">())</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// chained = [1, 2, 3, 4]</span></span></code></pre> <p><code>chain</code> first yields all values from the first iterator, then continues with the second iterator.</p> <p><code>zip</code> pairs elements from two iterators together:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> names</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #A6E3A1;">&quot;Alice&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Bob&quot;</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> scores</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">100</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 80</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> paired</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">i32</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> names</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into_iter</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">zip</span><span style="color: #9399B2;">(</span><span>scores</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">())</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// paired = [(&quot;Alice&quot;, 100), (&quot;Bob&quot;, 80)]</span></span></code></pre> <p><code>zip</code> walks both iterators at the same time. The first element from one iterator is paired with the first element from the other, the second with the second, and so on.</p> <p>If one iterator ends early, <code>zip</code> stops immediately.</p> <p><code>filter_map</code> combines filtering and transformation into a single operation:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> v</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #A6E3A1;">&quot;1&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;two&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;3&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;four&quot;</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> numbers</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> v</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">filter_map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>s</span><span style="color: #94E2D5;">|</span><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">parse</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">ok</span><span style="color: #9399B2;">())</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// numbers = [1, 3]</span></span></code></pre> <p><code>s.parse::&lt;i32&gt;()</code> returns <code>Result&lt;i32, ParseIntError&gt;</code>. Calling <code>.ok()</code> converts that <code>Result</code> into an <code>Option&lt;i32&gt;</code>.</p> <ul> <li><code>Ok(value)</code> becomes <code>Some(value)</code></li> <li><code>Err(_)</code> becomes <code>None</code></li> </ul> <p><code>filter_map</code> only keeps <code>Some</code> values and automatically unwraps them. Values that become <code>None</code> are skipped entirely. So:</p> <ul> <li><code>"1"</code> becomes <code>Some(1)</code></li> <li><code>"3"</code> becomes <code>Some(3)</code></li> <li><code>"two"</code> becomes <code>None</code></li> <li><code>"four"</code> becomes <code>None</code></li> </ul> <p>The final result is:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">]</span></span></code></pre><h3 id="chaining-adapters">Chaining Adapters</h3> <p>The real power comes from chaining:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> v</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 4</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 6</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 7</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 8</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 9</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> result</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> v</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">filter</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>x</span><span style="color: #94E2D5;">| *</span><span>x</span><span style="color: #94E2D5;"> %</span><span style="color: #FAB387;"> 2</span><span style="color: #94E2D5;"> ==</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">)</span><span style="color: #9399B2;font-style: italic;"> // keep evens</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>x</span><span style="color: #94E2D5;">|</span><span> x</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">)</span><span style="color: #9399B2;font-style: italic;"> // multiply by 10</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">take</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">)</span><span style="color: #9399B2;font-style: italic;"> // take first 3</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// result = [20, 40, 60]</span></span></code></pre> <p>Each adapter creates a new iterator struct that wraps the previous one. <code>v.iter()</code> creates an <code>Iter&lt;i32&gt;</code>. <code>.filter(...)</code> wraps it in a <code>Filter&lt;Iter&lt;i32&gt;, _&gt;</code>. <code>.map(...)</code> wraps it in a <code>Map&lt;Filter&lt;...&gt;, _&gt;</code>. <code>.take(3)</code> wraps it in a <code>Take&lt;Map&lt;...&gt;&gt;</code>. Nothing executes until a consuming operation like <code>collect</code>, <code>count</code>, or <code>for_each</code> starts calling <code>next</code> repeatedly. When it does, values flow through the pipeline one at a time: <code>1</code> comes out of the iterator, <code>filter</code> rejects it (odd), <code>2</code> comes out, <code>filter</code> accepts it, <code>map</code> turns it into <code>20</code>, <code>take</code> accepts it, <code>collect</code> stores it. Then <code>3</code> is rejected, <code>4</code> → <code>40</code> → accepted, <code>5</code> rejected, <code>6</code> → <code>60</code> → accepted. After three items, <code>take</code> returns <code>None</code> and iteration stops.</p> <h2 id="git-object-storage-model">Git Object Storage Model</h2> <p>Before we start the project, let's understand how Git stores data internally. Git is a content-addressable filesystem. In traditional Git repositories, every object is identified by the SHA-1 hash of its contents.</p> <h3 id="object-types">Object Types</h3> <p>Git has four types of objects:</p> <table><thead><tr><th>Type</th><th>What It Stores</th></tr></thead><tbody> <tr><td>blob</td><td>File contents</td></tr> <tr><td>tree</td><td>Directory listing (filenames, modes and hashes)</td></tr> <tr><td>commit</td><td>Snapshot metadata (tree hash, parent hashes, author, message)</td></tr> <tr><td>tag</td><td>Signed references (we will skip this)</td></tr> </tbody></table> <h3 id="loose-object-format">Loose Object Format</h3> <p>Loose objects are stored in <code>.git/objects/XX/YYYYYY...</code> where <code>XX</code> is the first two hex characters of the SHA-1 hash and <code>YYYYYY...</code> is the remaining 38 characters.</p> <p>The file contains the object data compressed with zlib (deflate). When decompressed, the format is:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>&lt;type&gt; &lt;size&gt;\0&lt;content&gt;</span></span></code></pre> <p>For example, a blob containing "hello world\n" decompresses to:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>blob 12\0hello world\n</span></span></code></pre> <p>The header is the type name, a space, the content size in bytes as a decimal string, a null byte, and then the raw content.</p> <h3 id="the-sha-1-hash">The SHA-1 Hash</h3> <p>Traditional Git computes the SHA-1 hash of <code>&lt;type&gt; &lt;size&gt;\0&lt;content&gt;</code>. That hash becomes the object's filename. This means the same content always produces the same hash, and the hash verifies the content.</p> <h3 id="commit-object">Commit Object</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>commit &lt;size&gt;\0tree &lt;tree_hash&gt;</span></span> <span class="giallo-l"><span>parent &lt;parent_hash&gt;</span></span> <span class="giallo-l"><span>author Mrsheerluck &lt;email&gt; &lt;timestamp&gt;</span></span> <span class="giallo-l"><span>committer Mrsheerluck &lt;email&gt; &lt;timestamp&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>commit message</span></span></code></pre> <p>The parent line is optional (the first commit has no parent). The tree line points to the tree object representing the directory structure at that commit.</p> <h3 id="tree-object">Tree Object</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>tree &lt;size&gt;\0&lt;mode&gt; &lt;name&gt;\0&lt;hash (20 bytes)&gt;</span></span> <span class="giallo-l"><span>&lt;mode&gt; &lt;name&gt;\0&lt;hash (20 bytes)&gt;</span></span></code></pre> <p>Each entry is a file or subdirectory. The mode is a string like <code>100644</code> (regular file) or <code>040000</code> (directory). The name is the filename. The hash is 20 raw bytes of the SHA-1 hash (not hex).</p> <h2 id="the-project-git-object-store-reader">The Project: Git Object Store Reader</h2> <p>Now that you understand HashMap, iterators, and how Git stores objects, let's build our Git Object Store Reader.</p> <p>Our program will:</p> <ul> <li>Accept a path to a <code>.git</code> directory</li> <li>Read loose objects from <code>.git/objects/XX/YYYYYY</code></li> <li>Decompress them using <code>flate2</code></li> <li>Parse the header and content into typed structs</li> <li>Build a commit graph using <code>HashMap&lt;CommitHash, Commit&gt;</code></li> <li>Render <code>git log --oneline</code> output starting from HEAD</li> </ul> <h3 id="project-setup">Project Setup</h3> <p>Open your terminal and run:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> new git_log</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> git_log</span></span></code></pre> <p>Now open <code>Cargo.toml</code> and add the dependency:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;">[</span><span>package</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>name</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;git_log&quot;</span></span> <span class="giallo-l"><span>version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.1.0&quot;</span></span> <span class="giallo-l"><span>edition</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;2024&quot;</span></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>dependencies</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>flate2</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&quot;</span></span></code></pre> <p>The only external dependency we need is <code>flate2</code> for zlib decompression. Everything else is standard library: <code>std::collections::HashMap</code>, <code>std::fs</code>, <code>std::io::Read</code>.</p> <h3 id="imports">Imports</h3> <p>Open <code>src/main.rs</code> and delete everything. Write this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> flate2</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">read</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">ZlibDecoder</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">collections</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">HashMap</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span>fs</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">io</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Read</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">path</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Path</span><span style="color: #9399B2;">;</span></span></code></pre> <ul> <li><code>flate2::read::ZlibDecoder</code> is used to decompress Git's zlib-compressed object files</li> <li><code>std::collections::HashMap</code> is for storing the commit graph, mapping hashes to commit structs</li> <li><code>std::fs</code> is for reading files from the .git directory</li> <li><code>std::io::Read</code> gives us the <code>read_to_end</code> method we need for decompression</li> <li><code>std::path::Path</code> is for manipulating filesystem paths</li> </ul> <h3 id="reading-head">Reading HEAD</h3> <p>Git always knows which branch you are on by reading the <code>.git/HEAD</code> file.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> read_head</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">git_dir</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">Path</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> head_path</span><span style="color: #94E2D5;"> =</span><span> git_dir</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;HEAD&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> content</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> fs</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">read_to_string</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>head_path</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">expect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Failed to read HEAD&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> content</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">trim</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. <code>git_dir.join("HEAD")</code> constructs the path to the HEAD file. If <code>git_dir</code> is the path to a <code>.git</code> directory, this gives us <code>.git/HEAD</code>. <code>fs::read_to_string</code> reads the entire file into a <code>String</code>. We <code>trim()</code> whitespace (HEAD files often have a trailing newline) and return the content.</p> <p>The HEAD file typically contains something like <code>ref: refs/heads/main</code>. This means "main" is the current branch. To get the actual commit hash, we need to read <code>.git/refs/heads/main</code>.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> resolve_ref</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">git_dir</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">Path</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> reference</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> reference</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">starts_with</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;ref: &quot;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> ref_path</span><span style="color: #94E2D5;"> = &amp;</span><span>reference</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">5</span><span style="color: #94E2D5;">..</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> full_path</span><span style="color: #94E2D5;"> =</span><span> git_dir</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">(</span><span>ref_path</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> fs</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">read_to_string</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>full_path</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">ok</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>s</span><span style="color: #94E2D5;">|</span><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">trim</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">())</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>reference</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">())</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. If the reference starts with <code>"ref: "</code>, we strip off those 5 characters to get something like <code>refs/heads/main</code>. Why 5? Because <code>"ref: "</code> is exactly 5 characters: <code>r</code>, <code>e</code>, <code>f</code>, <code>:</code>, <code> </code>. We join that path with the git directory and read the file it points to.</p> <p><code>fs::read_to_string</code> returns <code>Result&lt;String, io::Error&gt;</code>. We call <code>.ok()</code> to convert it to <code>Option&lt;String&gt;</code>. If the file exists, we get <code>Some(content)</code>. If not (the branch doesn't exist), we get <code>None</code>. Then <code>.map(|s| s.trim().to_string())</code> strips whitespace from the content. The result is the actual commit hash, like <code>"a1b2c3d4e5f6..."</code>.</p> <p>If the reference doesn't start with <code>"ref: "</code>, it means HEAD is already pointing directly at a commit hash — this is "detached HEAD" state. In that case, we just return it as-is wrapped in <code>Some</code>.</p> <h3 id="structs-for-git-objects">Structs for Git Objects</h3> <p>We need a struct for the data we care about:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Commit</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> tree_hash</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> parent_hashes</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Each commit has a tree hash (pointing to the directory snapshot), zero or more parent hashes (the first commit has none, merge commits have two), and a commit message.</p> <h3 id="reading-a-loose-object">Reading a Loose Object</h3> <p>Git stores objects in <code>.git/objects/XX/YYYYYY</code> where the path is derived from the SHA-1 hash. The first two hex characters become the directory name, and the remaining 38 characters become the filename.</p> <p>A loose object file is compressed with zlib (deflate). Let's write a function to read and decompress one:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> read_object</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">git_dir</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">Path</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> hash</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">u8</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> object_path</span><span style="color: #94E2D5;"> =</span><span> git_dir</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;objects&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>hash</span><span style="color: #9399B2;">[</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">])</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>hash</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">2</span><span style="color: #94E2D5;">..</span><span style="color: #9399B2;">]);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> compressed</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> fs</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">read</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>object_path</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">unwrap_or_else</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>_</span><span style="color: #94E2D5;">|</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Failed to read object: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> hash</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> decoder</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> ZlibDecoder</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>compressed</span><span style="color: #9399B2;">[</span><span style="color: #94E2D5;">..</span><span style="color: #9399B2;">]);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> decompressed</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> decoder</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">read_to_end</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span> decompressed</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">unwrap_or_else</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>_</span><span style="color: #94E2D5;">|</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Failed to decompress object: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> hash</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span> decompressed</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. We construct the path by splitting the hash. For example, if the hash is <code>a1b2c3d4e5f6...</code>, <code>&amp;hash[..2]</code> gives us <code>"a1"</code> (the first two hex characters), and <code>&amp;hash[2..]</code> gives us <code>"b2c3d4e5f6..."</code> (the remaining 38 characters). The resulting path becomes <code>.git/objects/a1/b2c3d4e5f6...</code>.</p> <p>We read the compressed file into a byte vector using <code>fs::read</code>. Then <code>&amp;compressed[..]</code> creates a byte slice of the entire compressed data. We wrap it in a <code>ZlibDecoder</code> which implements <code>Read</code>. When we call <code>decoder.read_to_end(&amp;mut decompressed)</code>, it decompresses the zlib data and writes all decompressed bytes into our output vector.</p> <p>When decompressed, a Git object looks like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>blob 12\0hello world\n</span></span></code></pre> <p>or:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>commit 234\0tree a1b2...\nparent c3d4...\nauthor ...</span></span></code></pre> <p>The format is always: type name, space, size in bytes as decimal, null byte, then the raw content.</p> <h3 id="parsing-the-object-header">Parsing the Object Header</h3> <p>Let's write a function to split the decompressed data into the header and the content:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> parse_object</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">data</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">[</span><span style="color: #CBA6F7;">u8</span><span style="color: #9399B2;">])</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #9399B2;"> (</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #9399B2;">[</span><span style="color: #CBA6F7;">u8</span><span style="color: #9399B2;">]) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> header_end</span><span style="color: #94E2D5;"> =</span><span> data</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">position</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|&amp;</span><span>b</span><span style="color: #94E2D5;">|</span><span> b</span><span style="color: #94E2D5;"> ==</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">expect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid object: no null byte&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> header</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_utf8</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>data</span><span style="color: #9399B2;">[</span><span style="color: #94E2D5;">..</span><span>header_end</span><span style="color: #9399B2;">])</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">expect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid object: header not valid UTF-8&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> content</span><span style="color: #94E2D5;"> = &amp;</span><span>data</span><span style="color: #9399B2;">[</span><span>header_end</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;">..</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> parts</span><span style="color: #94E2D5;"> =</span><span> header</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">splitn</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">, &#39; &#39;);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> obj_type</span><span style="color: #94E2D5;"> =</span><span> parts</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">next</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> _size</span><span style="color: #94E2D5;"> =</span><span> parts</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">next</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span>obj_type</span><span style="color: #9399B2;">,</span><span> content</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. <code>data.iter().position(|&amp;b| b == 0)</code> walks through the byte array and returns the index of the first null byte. This is our separator between the header and the content. If there's no null byte, the data is corrupted and we panic.</p> <p><code>&amp;data[..header_end]</code> gives us the header bytes (everything before the null). We convert those bytes to a string with <code>from_utf8</code>. Then <code>header.splitn(2, ' ')</code> splits the header on the first space into at most 2 parts. Part 1 is the object type (like <code>"commit"</code> or <code>"tree"</code> or <code>"blob"</code>). Part 2 is the size (like <code>"234"</code>). We don't actually need the size because the content is everything after the null byte, but we still parse it because Git object headers always include it.</p> <p>The function returns a tuple: the type string and a byte slice of the content.</p> <h3 id="parsing-a-commit-object">Parsing a Commit Object</h3> <p>Now that we can read and decompress any object, let's parse a commit. A commit object looks like this when decompressed:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>commit 234\0tree a1b2c3d4e5f6...</span></span> <span class="giallo-l"><span>parent f8g9h0i1j2k3...</span></span> <span class="giallo-l"><span>author Mrsheerluck &lt;email&gt; 1234567890 +0000</span></span> <span class="giallo-l"><span>committer Mrsheerluck &lt;email&gt; 1234567890 +0000</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Initial commit message</span></span></code></pre> <p>The format is key-value headers until a blank line, then the commit message.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> parse_commit</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">content</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">[</span><span style="color: #CBA6F7;">u8</span><span style="color: #9399B2;">])</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Commit</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> content_str</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_utf8</span><span style="color: #9399B2;">(</span><span>content</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">expect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid commit: not valid UTF-8&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> tree_hash</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> parent_hashes</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> message</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> in_message</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> line</span><span style="color: #CBA6F7;"> in</span><span> content_str</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">lines</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> in_message</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> !</span><span>message</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_empty</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #F5C2E7;">\n</span><span style="color: #9399B2;">&#39;);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push_str</span><span style="color: #9399B2;">(</span><span>line</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> continue</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_empty</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span> in_message</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> continue</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>hash</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">strip_prefix</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;tree &quot;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> tree_hash</span><span style="color: #94E2D5;"> =</span><span> hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>hash</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">strip_prefix</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;parent &quot;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> parent_hashes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Commit</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> tree_hash</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> parent_hashes</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> message</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. <code>content_str.lines()</code> returns an iterator over the lines of the commit text. We walk through them one by one using a <code>for</code> loop.</p> <p>Before we hit the blank line, we are parsing headers. <code>line.strip_prefix("tree ")</code> checks if the line starts with <code>"tree "</code>. If it does, it returns the rest of the line (the hash) as a <code>&amp;str</code>, and we convert it to an owned <code>String</code>. Same for parent lines. There can be multiple parent lines in merge commits, so we push each one into a vector.</p> <p>When we hit an empty line (<code>if line.is_empty()</code>), we flip <code>in_message</code> to <code>true</code>. From that point on, every line is part of the commit message. We build the message string by appending each line. The <code>if !message.is_empty()</code> check ensures we add a newline between lines of a multi-line message, but not at the start.</p> <h3 id="reading-commits-recursively">Reading Commits Recursively</h3> <p>To build the full commit graph, we need to read a commit, then read all its parents, then their parents, and so on. We use a <code>HashMap</code> to cache commits we have already read, so we never read the same object twice and we avoid infinite loops.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> read_commit</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> git_dir</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">Path</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> hash</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> cache</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> HashMap</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Commit</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> cache</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">contains_key</span><span style="color: #9399B2;">(</span><span>hash</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> data</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> read_object</span><span style="color: #9399B2;">(</span><span>git_dir</span><span style="color: #9399B2;">,</span><span> hash</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span style="color: #9399B2;"> (</span><span>obj_type</span><span style="color: #9399B2;">,</span><span> content</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> parse_object</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>data</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> obj_type</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;commit&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> commit</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> parse_commit</span><span style="color: #9399B2;">(</span><span>content</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> parent</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>commit</span><span style="color: #94E2D5;">.</span><span>parent_hashes </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> read_commit</span><span style="color: #9399B2;">(</span><span>git_dir</span><span style="color: #9399B2;">,</span><span> parent</span><span style="color: #9399B2;">,</span><span> cache</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> cache</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span>hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span><span> commit</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Expected commit object, got </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> obj_type</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. First, <code>cache.contains_key(hash)</code> checks if we've already read this commit. If it's in the cache, we return immediately. This prevents redundant reads. Git commit graphs are acyclic, but caching still avoids re-reading commits reachable through multiple merge paths.</p> <p>Then we read the object from disk, parse its header to confirm it is a <code>"commit"</code> type, and parse the commit data into our <code>Commit</code> struct.</p> <p>Before inserting the current commit into the cache, we recursively read all its parent commits. We iterate over <code>commit.parent_hashes</code> and call <code>read_commit</code> for each one. This recursively walks the entire parent graph so every reachable ancestor commit eventually ends up in the cache. The recursion base case is when a commit has no parents (the root commit) or when all parents are already in the cache.</p> <p>Finally, <code>cache.insert(hash.to_string(), commit)</code> takes ownership of both the key and the value. The <code>hash</code> parameter is <code>&amp;str</code>, so we call <code>.to_string()</code> to get an owned <code>String</code> for the map key.</p> <h3 id="rendering-git-log-oneline">Rendering <code>git log --oneline</code></h3> <p>Now we have a graph of commits. The <code>git log --oneline</code> format looks like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>a1b2c3d Initial commit message</span></span> <span class="giallo-l"><span>e5f6a7b Add new feature</span></span> <span class="giallo-l"><span>f8g9h0i Fix bug in parser</span></span></code></pre> <p>Each line starts with the abbreviated hash (first 7 characters) and the first line of the commit message.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> log_oneline</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">commits</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">HashMap</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Commit</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> start_hash</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> hash</span><span style="color: #94E2D5;"> =</span><span> start_hash</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> loop</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> commits</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>hash</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>commit</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> short_hash</span><span style="color: #94E2D5;"> = &amp;</span><span>hash</span><span style="color: #9399B2;">[</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">7</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> first_line</span><span style="color: #94E2D5;"> =</span><span> commit</span><span style="color: #94E2D5;">.</span><span>message</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">lines</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">next</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap_or</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{} {}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> short_hash</span><span style="color: #9399B2;">,</span><span> first_line</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> commit</span><span style="color: #94E2D5;">.</span><span>parent_hashes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">first</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>parent</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> hash</span><span style="color: #94E2D5;"> =</span><span> parent</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. We start from <code>start_hash</code> (the commit that HEAD points to) and walk backwards through the first-parent chain. For each commit, <code>&amp;hash[..7]</code> takes the first 7 characters of the hash string. <code>commit.message.lines()</code> returns an iterator over the lines of the message. <code>.next()</code> gets the first line, returning <code>Option&lt;&amp;str&gt;</code>. We use <code>unwrap_or("")</code> to handle the edge case of an empty message. Then we move to the first parent by cloning the hash of <code>parent_hashes.first()</code>. If there are no parents, we have reached the root commit and we <code>break</code>.</p> <p>This follows only the first parent, which is similar to <code>git log --first-parent --oneline</code>. Merge commits have multiple parents, but the first parent is usually the branch you were on when you merged.</p> <h3 id="walking-the-tree">Walking the Tree</h3> <p>Now let's use iterators to do something more interesting. Let's list all files in the latest commit's directory structure. First, we need to parse tree objects.</p> <p>Git tree objects have a binary format. Each entry is:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>&lt;mode&gt; &lt;name&gt;\0&lt;20-byte raw hash&gt;</span></span></code></pre> <p>The mode is a string like <code>100644</code> (regular file) or <code>040000</code> (directory). The name is the filename. The hash is 20 raw bytes, not a hex string.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> TreeEntry</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> mode</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> hash</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> parse_tree</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">content</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">[</span><span style="color: #CBA6F7;">u8</span><span style="color: #9399B2;">])</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">TreeEntry</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> entries</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> pos</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> while</span><span> pos</span><span style="color: #94E2D5;"> &lt;</span><span> content</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> null_pos</span><span style="color: #94E2D5;"> =</span><span> content</span><span style="color: #9399B2;">[</span><span>pos</span><span style="color: #94E2D5;">..</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">position</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|&amp;</span><span>b</span><span style="color: #94E2D5;">|</span><span> b</span><span style="color: #94E2D5;"> ==</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">expect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid tree: missing null byte&quot;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> +</span><span> pos</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> mode_and_name</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_utf8</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>content</span><span style="color: #9399B2;">[</span><span>pos</span><span style="color: #94E2D5;">..</span><span>null_pos</span><span style="color: #9399B2;">])</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">expect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid tree: not valid UTF-8&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> space_pos</span><span style="color: #94E2D5;"> =</span><span> mode_and_name</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">find</span><span style="color: #9399B2;">(&#39; &#39;)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">expect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid tree entry: missing space&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> mode</span><span style="color: #94E2D5;"> = &amp;</span><span>mode_and_name</span><span style="color: #9399B2;">[</span><span style="color: #94E2D5;">..</span><span>space_pos</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> name</span><span style="color: #94E2D5;"> = &amp;</span><span>mode_and_name</span><span style="color: #9399B2;">[</span><span>space_pos</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;">..</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> pos</span><span style="color: #94E2D5;"> =</span><span> null_pos</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> hash_bytes</span><span style="color: #94E2D5;"> = &amp;</span><span>content</span><span style="color: #9399B2;">[</span><span>pos</span><span style="color: #94E2D5;">..</span><span>pos</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 20</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> hash</span><span style="color: #94E2D5;"> =</span><span> hash_bytes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>b</span><span style="color: #94E2D5;">|</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">:02x</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> b</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Vec</span><span style="color: #89DCEB;">&lt;</span><span>_</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> entries</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">TreeEntry</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> mode</span><span style="color: #94E2D5;">:</span><span> mode</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">:</span><span> name</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> hash</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> pos</span><span style="color: #94E2D5;"> +=</span><span style="color: #FAB387;"> 20</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> entries</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. Tree objects are binary, so we walk through the data byte by byte.</p> <p><code>content[pos..].iter().position(|&amp;b| b == 0)</code> finds the first null byte starting from the current position. We add <code>pos</code> to get the absolute index in the original array. The bytes from <code>pos</code> to <code>null_pos</code> are the mode and name, separated by a space. So <code>mode_and_name.find(' ')</code> finds that space, <code>&amp;mode_and_name[..space_pos]</code> is the mode (like <code>"100644"</code>), and <code>&amp;mode_and_name[space_pos + 1..]</code> is the name (like <code>"main.rs"</code>).</p> <p>After the null byte, the next 20 bytes are the raw SHA-1 hash. <code>&amp;content[pos..pos + 20]</code> gives us those bytes. This assumes the tree object is valid and contains at least 20 bytes for the hash. Real parsers would validate bounds more carefully instead of panicking on malformed data. Then we convert each byte to a two-character hex string:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span>hash_bytes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>b</span><span style="color: #94E2D5;">|</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">:02x</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> b</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Vec</span><span style="color: #89DCEB;">&lt;</span><span>_</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;&quot;</span><span style="color: #9399B2;">)</span></span></code></pre> <p>Let me break that iterator chain down. <code>hash_bytes.iter()</code> gives us an iterator over each byte. <code>.map(|b| format!("{:02x}", b))</code> transforms each byte (like <code>0xa1</code>) into a two-character hex string (like <code>"a1"</code>). <code>.collect::&lt;Vec&lt;_&gt;&gt;()</code> collects all those hex strings into a vector like <code>["a1", "b2", "c3", ...]</code>. <code>.join("")</code> concatenates them into a single 40-character hash string like <code>"a1b2c3..."</code>.</p> <p>Then we advance <code>pos</code> by 20 bytes to move to the next entry.</p> <p>Now let's write a recursive tree walker that lists every file:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> walk_tree</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">git_dir</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">Path</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> tree_hash</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> prefix</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> data</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> read_object</span><span style="color: #9399B2;">(</span><span>git_dir</span><span style="color: #9399B2;">,</span><span> tree_hash</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span style="color: #9399B2;"> (</span><span>_</span><span style="color: #9399B2;">,</span><span> content</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> parse_object</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>data</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> entries</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> parse_tree</span><span style="color: #9399B2;">(</span><span>content</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> entries</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">flat_map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>entry</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> path</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if</span><span> prefix</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_empty</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span> entry</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">name</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">/</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> prefix</span><span style="color: #9399B2;">,</span><span> entry</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">name</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> entry</span><span style="color: #94E2D5;">.</span><span>mode </span><span style="color: #94E2D5;">==</span><span style="color: #A6E3A1;"> &quot;040000&quot;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> walk_tree</span><span style="color: #9399B2;">(</span><span>git_dir</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>entry</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">hash</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>path</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span>path</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> })</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. For each entry in the tree, we build the full path. If the prefix is empty (we're at the root), the path is just the entry name. Otherwise, it's <code>prefix/name</code>. So if we're in <code>src/</code> and the entry is <code>main.rs</code>, the path becomes <code>src/main.rs</code>.</p> <p>If the entry's mode is <code>"040000"</code>, it's a directory. We recurse into it by calling <code>walk_tree</code> again with the subdirectory's tree hash and the new path. If it's a file (mode <code>"100644"</code> or similar), we return a vector with just that one path.</p> <p>The key here is <code>flat_map</code>. Each entry produces either a single-element vector (a file) or a multi-element vector (all files in a subdirectory). Without <code>flat_map</code>, the result would be <code>Vec&lt;Vec&lt;String&gt;&gt;</code> — a vector of file lists, one per entry. With <code>flat_map</code>, all those iterators are flattened into one combined <code>Vec&lt;String&gt;</code> of every file path.</p> <h3 id="putting-it-all-together">Putting It All Together</h3> <p>Now let's wire everything together in <code>main</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> args</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">env</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">args</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> git_dir</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if</span><span> args</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &gt;</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Path</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>args</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">])</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_path_buf</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Path</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;.git&quot;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_path_buf</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> head</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> read_head</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>git_dir</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> head_hash</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> resolve_ref</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>git_dir</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>head</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">expect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Failed to resolve HEAD&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> cache</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> HashMap</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> read_commit</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>git_dir</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>head_hash</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span> cache</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> log_oneline</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>cache</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>head_hash</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>commit</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> cache</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>head_hash</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #F5C2E7;">\n</span><span style="color: #A6E3A1;">Files in latest commit:&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> files</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> walk_tree</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>git_dir</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>commit</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">tree_hash</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> file</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>files</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;"> {}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> file</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. <code>std::env::args().collect()</code> reads command line arguments into a <code>Vec&lt;String&gt;</code>. If a path argument is provided (<code>args.len() &gt; 1</code>), we use it as the git directory. Otherwise, we default to <code>.git</code> in the current directory. <code>Path::new(&amp;args[1]).to_path_buf()</code> creates an owned <code>PathBuf</code> from the string argument.</p> <p>We read HEAD with <code>read_head</code>, which gives us something like <code>"ref: refs/heads/main"</code>. Then <code>resolve_ref</code> follows that reference to get the actual commit hash.</p> <p>We create a new, empty <code>HashMap</code> as our cache. Then <code>read_commit</code> reads the commit graph starting from HEAD, which recursively reads all ancestors. By the time this returns, the cache contains every commit reachable from HEAD.</p> <p>Finally, we print the log output using <code>log_oneline</code>. If the HEAD commit is in the cache (it should always be), we also walk its tree to list all files in the latest snapshot.</p> <h3 id="running-the-project">Running The Project</h3> <p>Type this in your terminal:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> run -- /path/to/some/.git</span></span></code></pre> <p>Or from inside a git repository:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> run</span></span></code></pre> <p>You should see output like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>a1b2c3d Initial commit</span></span> <span class="giallo-l"><span>e5f6a7b Add feature X</span></span> <span class="giallo-l"><span>f8g9h0i Set up project structure</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Files in latest commit:</span></span> <span class="giallo-l"><span> src/main.rs</span></span> <span class="giallo-l"><span> src/lib.rs</span></span> <span class="giallo-l"><span> Cargo.toml</span></span> <span class="giallo-l"><span> README.md</span></span></code></pre> <p>That's it, your own <code>git log --oneline</code> implementation in less than 200 lines of Rust, using <code>HashMap</code>, iterators, and the knowledge of Git's object storage model.</p> <h2 id="conclusion">Conclusion</h2> <p>In this post, you learned about <code>HashMap</code>, the <code>Entry</code> API for single-lookup insert-or-update, the <code>Iterator</code> trait and its three forms (<code>.iter()</code>, <code>.iter_mut()</code>, <code>.into_iter()</code>), consuming adapters like <code>collect</code> and <code>count</code>, iterator adapters like <code>map</code>, <code>filter</code>, <code>flat_map</code>, and how to chain them lazily. You also learned how Git stores objects (blobs, trees, commits) as zlib-compressed files in <code>.git/objects/</code>. And you built a Git Object Store Reader that reads real <code>.git</code> directories, parses commits and trees, and renders <code>git log --oneline</code> output using nothing but the standard library and <code>flate2</code>.</p> <p>In the next article, we will build something even more interesting. See you soon.</p> 2026-05-13T00:00:00+00:00 2026-05-13T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/learn-rust-lifetimes-by-building-a-lru-cache/ <p>In this post, we are going to learn about lifetimes in Rust. Once we cover all the concepts, we will build a <strong>Generic LRU Cache</strong>. I'm really excited for this project and I hope you are too. I won't go too deep in theory, just practical and we will build our knowledge of these concepts over time with more articles.</p> <p>The only prerequisite is that you have read the previous articles in this series, as I will assume you know ownership, borrowing, structs, enums, pattern matching, error handling, generics and traits.</p> <p>In this post, we will first learn what lifetimes are, why they exist, how lifetime annotations work, lifetime elision, lifetimes on structs, and then we will build a generic LRU cache that returns zero-copy references with lifetime annotations.</p> <p>Get the source code from <a rel="external" href="https://github.com/MrSheerluck/lru_cache_in_rust">here</a></p> <blockquote> <p>This is an educational LRU implementation focused on learning lifetimes and borrowing semantics. Production LRU caches typically use a HashMap and a doubly linked list to achieve O(1) operations.</p> </blockquote> <h2 id="the-problem-lifetimes-solve">The Problem Lifetimes Solve</h2> <p>Every reference in Rust has a <strong>lifetime</strong>. A lifetime is just the span of time during which a reference is valid. It starts when the reference is created and ends when the reference is no longer usable. Every reference in Rust has a lifetime, even if you don't see it written anywhere.</p> <p>Most of the time, lifetimes are invisible. The compiler can figure them out on its own. But sometimes, the compiler needs your help. When the compiler cannot figure out the relationship between references in a function's inputs and outputs, it asks you to annotate the lifetimes. That is what this article is about.</p> <p>Let's start with a simple example that compiles:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 42</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> r</span><span style="color: #94E2D5;"> = &amp;</span><span>x</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> r</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>x</code> is created, then <code>r</code> borrows <code>x</code>. Both <code>x</code> and <code>r</code> go out of scope at the end of <code>main</code>. <code>r</code> is always valid because <code>x</code> lives longer than <code>r</code>. The compiler can see this trivially.</p> <p>But what about this?</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> r</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 42</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> r</span><span style="color: #94E2D5;"> = &amp;</span><span>x</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> r</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // ERROR: `x` does not live long enough</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Here, <code>r</code> is declared before the inner block. Inside the block, <code>r</code> borrows <code>x</code>. But <code>x</code> is dropped when the inner block ends. When we try to print <code>r</code> after the block, <code>r</code> points to freed memory. This is a <strong>dangling reference</strong>. In C, this compiles and runs, and reads garbage or crashes. In Rust, this does not compile at all. The compiler checks that <code>r</code> cannot outlive the data it points to. That check is the borrow checker, and it enforces lifetime rules.</p> <p>The error message says "<code>x</code> does not live long enough." The compiler has computed the lifetimes of both references and determined that the reference <code>r</code> would be invalid by the time it is used.</p> <p>Here is another common example:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> longest</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">x</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> y</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt; &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> x</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &gt;</span><span> y</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">() {</span><span> x</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span><span> y</span><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This seems straightforward. Return the longer of two string slices. But this will not compile. The compiler does not know whether the returned reference points to <code>x</code> or <code>y</code>. It does not know how the lifetimes of the inputs relate to the lifetime of the output. It cannot guarantee that the returned reference will be valid when the caller uses it. So it rejects the code. To fix this, we need to tell the compiler: "The returned reference cannot outlive either input reference." That is exactly what lifetime annotations do.</p> <h2 id="lifetime-annotations">Lifetime Annotations</h2> <p>A lifetime annotation is written with a single quote followed by a name, just like <code>'a</code>. By convention, we use short names like <code>'a</code>, <code>'b</code>, <code>'ctx</code>, <code>'src</code>. The annotation does not change how long anything lives. It just names a lifetime so you can describe relationships between references.</p> <p>Here is the longest function with lifetime annotations:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> longest</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">x</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #F9E2AF;font-style: italic;"> str</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> y</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #F9E2AF;font-style: italic;"> str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt; &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #F9E2AF;font-style: italic;"> str</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> x</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &gt;</span><span> y</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">() {</span><span> x</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span><span> y</span><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Let me explain what we just did. <code>&lt;'a&gt;</code> introduces a lifetime parameter, just like <code>&lt;T&gt;</code> introduces a type parameter. <code>x: &amp;'a str</code> means "<code>x</code> is a reference to a <code>str</code> with lifetime <code>'a</code>". <code>y: &amp;'a str</code> means the same for <code>y</code>. And <code>-&gt; &amp;'a str</code> means "the return value is a reference with lifetime <code>'a</code>".</p> <p>The meaning of this signature is: "The function takes two string slices that both live at least as long as <code>'a</code>, and returns a string slice that also lives at least as long as <code>'a</code>." In other words, the returned reference cannot outlive either input reference.</p> <p>Now the compiler knows enough to check the caller. Here is a valid call:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;short&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> y</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;loooooong&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> result</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> longest</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>x</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>y</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // our longest function that we wrote above</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> result</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Both <code>x</code> and <code>y</code> live until the end of <code>main</code>. result is used within that scope.</p> <p>Everything checks out. But here is what gets rejected:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;short&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> result</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> y</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;loooooong&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> result</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> longest</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>x</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>y</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // our longest function that we wrote above</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> result</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // ERROR: `y` does not live long enough</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The function signature ties the returned reference lifetime to both inputs, so the compiler conservatively assumes the returned reference cannot outlive either one. Since <code>y</code> is dropped inside the block, result would be invalid after the block. The compiler catches this.</p> <p>But what if the function always returns one specific input, regardless of the other?</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> first</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">, &#39;</span><span style="color: #89B4FA;font-style: italic;">b</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">x</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #F9E2AF;font-style: italic;"> str</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> y</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">b</span><span style="color: #F9E2AF;font-style: italic;"> str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt; &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #F9E2AF;font-style: italic;"> str</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> x</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Here <code>x</code> has lifetime <code>'a</code> and <code>y</code> has lifetime <code>'b</code>. The return type is <code>&amp;'a str</code>, meaning the returned reference has the same lifetime as <code>x</code>. This is valid because <code>first</code> always returns <code>x</code>. The lifetime of <code>y</code> is completely unrelated.</p> <p>At the call site:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> result</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> y</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;world&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> result</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> first</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>x</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>y</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // our first function that we wrote above</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> result</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // This works! result borrows from x, not y</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This compiles because result only borrows from <code>x</code>, which lives longer. The compiler can see that the return value's lifetime is tied to <code>x</code> and not to <code>y</code>.</p> <h2 id="lifetime-annotations-in-struct-methods">Lifetime Annotations in Struct Methods</h2> <p>Structs can have lifetimes too, and methods on those structs need them as well.</p> <p>Consider a struct that holds a reference:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Config</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #F9E2AF;font-style: italic;"> str</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> version</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #F9E2AF;font-style: italic;"> str</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The <code>&lt;'a&gt;</code> on the struct definition means every instance of <code>Config</code> has a lifetime parameter. Any reference stored in the struct must live at least as long as <code>'a</code>. The struct cannot outlive the data it references.</p> <p>Now let's add a method:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #89DCEB;">&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Config</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> name</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt; &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>name</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The <code>impl&lt;'a&gt;</code> introduces the lifetime parameter for the impl block. The method <code>name</code> returns <code>&amp;str</code>. Can you spot why we don't need to annotate the return type's lifetime here? Because of lifetime elision. The compiler sees that the return type is a reference, and that the method takes <code>&amp;self</code>. When a method takes <code>&amp;self</code>, the compiler assumes the return type has the same lifetime as <code>&amp;self</code>. It fills in the blank automatically.</p> <h2 id="lifetime-elision-rules">Lifetime Elision Rules</h2> <p>You might be wondering: why do some functions need explicit lifetime annotations and others do not? The answer is that Rust has three lifetime elision rules. The compiler applies these rules to every function signature. If the rules can figure out the lifetimes, you do not need to write them. If the rules cannot figure it out, the compiler asks you to be explicit.</p> <p>Here are the three rules for function and method signatures:</p> <table><thead><tr><th>Rule</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>Each input reference gets its own lifetime parameter</td></tr> <tr><td>2</td><td>If there is exactly one input lifetime, it is assigned to all output references</td></tr> <tr><td>3</td><td>If the method takes &amp;self or &amp;mut self, the lifetime of self is assigned to all output references</td></tr> </tbody></table> <p>Let's see these rules in action.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> hello</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -&gt; &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;"> {</span><span style="color: #9399B2;font-style: italic;"> // ERROR: no input references</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;hello&quot;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This fails because there are no input references, so the compiler cannot figure out what lifetime to assign to the output. The fix is to return <code>&amp;'static str</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> hello</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -&gt; &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">static</span><span style="color: #F9E2AF;font-style: italic;"> str</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;hello&quot;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>String literals have the <code>'static</code> lifetime, meaning they live for the entire duration of the program.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> first_word</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">s</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt; &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;"> {</span><span style="color: #9399B2;font-style: italic;"> // Works! Rule 2 applies</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // ...</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>One input reference, one output reference. Rule 2 assigns the input lifetime to the output.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> longest</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">x</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> y</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt; &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;"> {</span><span style="color: #9399B2;font-style: italic;"> // ERROR: two input references</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // ...</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Two input references, one output reference. Rule 1 creates two lifetimes (<code>'a</code>, <code>'b</code>). Rule 2 does not apply because there are two inputs, not one. Rule 3 does not apply because this is not a method. So the compiler asks for explicit annotations.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #89DCEB;">&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Config</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> get_name</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt; &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;"> {</span><span style="color: #9399B2;font-style: italic;"> // Works! Rule 3 applies</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &amp;</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>name</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Takes <code>&amp;self</code>. Rule 3 assigns the lifetime of self to the output. No explicit annotation needed. These three rules cover the vast majority of cases. In practice, explicit lifetime annotations on functions are relatively rare. Most of the time, the elision rules handle it.</p> <h2 id="the-static-lifetime">The <code>'static</code> Lifetime</h2> <p>The <code>'static</code> lifetime is special. It means "this reference is valid for the entire program." String literals are <code>'static</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> s</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">static</span><span style="color: #F9E2AF;font-style: italic;"> str</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;hello world&quot;</span><span style="color: #9399B2;">;</span></span></code></pre> <p>The string <code>"hello world"</code> is embedded directly in the compiled binary. It exists for as long as the program runs, so its lifetime is <code>'static</code>.</p> <p>There is another way to get a <code>'static</code> lifetime that surprises beginners:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> s</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">static</span><span style="color: #F9E2AF;font-style: italic;"> str</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;hello&quot;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This works because string literals are stored in the binary. But this does not:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> make_string</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -&gt; &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">static</span><span style="color: #F9E2AF;font-style: italic;"> str</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &amp;</span><span>s</span><span style="color: #9399B2;font-style: italic;"> // ERROR: cannot return reference to local variable</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Even though we wrote <code>&amp;'static str</code>, the compiler knows we are lying. <code>s</code> is a heap-allocated <code>String</code> that will be dropped at the end of the function. It cannot have <code>'static</code> lifetime.</p> <p>The <code>'static</code> bound is also commonly seen in trait bounds:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> process</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> &#39;</span><span style="color: #89B4FA;font-style: italic;">static</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">t</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // T does not contain any non-static references</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This means <code>T</code> cannot contain any references that are not <code>'static</code>. If <code>T</code> is <code>i32</code>, that is fine because integers do not contain references. If <code>T</code> is <code>&amp;'a str</code> where <code>'a</code> is not <code>'static</code>, this will not compile.</p> <p>Now that we understand how lifetime relationships work in functions and structs, let's start working on our project</p> <h2 id="the-project-generic-lru-cache">The Project: Generic LRU Cache</h2> <p>Now that you understand lifetimes, let's build a generic LRU cache. An LRU (Least Recently Used) cache is a data structure that stores a fixed number of items. When the cache is full and a new item is added, the least recently used item is evicted to make space.</p> <p>Our LRU cache will:</p> <ul> <li>Be generic over key type <code>K</code> and value type <code>V</code></li> <li>Hold a borrowed <code>Config</code> reference with a lifetime annotation</li> <li>Provide zero-copy <code>get</code> that returns <code>Option&lt;&amp;V&gt;</code> with proper lifetime annotations</li> <li>Support <code>put</code>, <code>get</code>, and <code>contains</code> operations</li> <li>Be split into a separate <code>src/cache.rs</code> module</li> </ul> <p>We are using an LRU cache because it gives us a practical way to work with borrowed data and references returned from methods. The cache holds a reference to a configuration struct, and the <code>get</code> method returns references to values stored in the cache. Both of these need proper lifetime annotations to satisfy the borrow checker.</p> <h3 id="project-setup">Project Setup</h3> <p>Open your terminal and run:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> new lru_cache</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> lru_cache</span></span></code></pre> <p>Now open the <code>Cargo.toml</code> file. We do not need any external dependencies for this project. Everything is standard library.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;">[</span><span>package</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>name</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;lru_cache&quot;</span></span> <span class="giallo-l"><span>version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.1.0&quot;</span></span> <span class="giallo-l"><span>edition</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;2024&quot;</span></span></code></pre> <p>We will create two files: <code>src/cache.rs</code> for the cache implementation and <code>src/main.rs</code> for the demo.</p> <blockquote> <p>The below code snippets will come under <code>src/cache.rs</code> file, please, check the complete code on github if you are coding along while reading</p> </blockquote> <h3 id="the-config-struct">The Config Struct</h3> <p>Before we build the cache, we need a configuration struct. The cache will borrow from it.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> CacheConfig</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> max_capacity</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The cache will hold a reference to this config using a lifetime annotation.</p> <h3 id="the-cache-struct">The Cache Struct</h3> <p>Now let's define the cache struct. This is where lifetimes come in.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Cache</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> config</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #F9E2AF;font-style: italic;"> CacheConfig</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> items</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">K</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> access_order</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">usize</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. <code>Cache&lt;'a, K, V&gt;</code> has three generic parameters: a lifetime <code>'a</code> and two type parameters <code>K</code> and <code>V</code>. The <code>config</code> field is <code>&amp;'a CacheConfig</code>, meaning it borrows a <code>CacheConfig</code> that must live at least as long as <code>'a</code>. The cache cannot outlive the config it borrows from.</p> <p><code>items</code> is a <code>Vec&lt;(K, V)&gt;</code> holding the key-value pairs. <code>access_order</code> is a <code>Vec&lt;usize&gt;</code> of indices into <code>items</code>, ordered from most recently used to least recently used.</p> <h3 id="the-constructor">The Constructor</h3> <p>We need a way to create a <code>Cache</code>. The constructor takes a reference to a <code>CacheConfig</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #89DCEB;">&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Cache</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> new</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">config</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #F9E2AF;font-style: italic;"> CacheConfig</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F38BA8;"> Self</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Cache</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> config</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> items</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> access_order</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>new</code> takes <code>config: &amp;'a CacheConfig</code> and returns <code>Cache&lt;'a, K, V&gt;</code>. The lifetime <code>'a</code> is the same for both the input reference and the output struct. This tells the compiler that the cache is borrowing from the config, and the cache cannot outlive the config.</p> <h3 id="capacity-getter">Capacity Getter</h3> <p>Since the cache borrows from <code>CacheConfig</code>, it can access its fields through the reference:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #89DCEB;">&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Cache</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> capacity</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>config</span><span style="color: #94E2D5;">.</span><span>max_capacity</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Notice that <code>capacity</code> returns <code>usize</code>, not a reference. It reads the value from the borrowed config and returns an owned copy. No lifetime annotation needed.</p> <p>But what if we wanted to return a reference to a field of <code>config</code>?</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #89DCEB;">&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Cache</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> name</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt; &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &amp;</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>config</span><span style="color: #94E2D5;">.</span><span>name</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This works without explicit lifetime annotations because of elision rule 3. The method takes <code>&amp;self</code>, so the output reference is assumed to have the same lifetime as <code>self</code>. Since <code>self</code> is <code>&amp;'a CacheConfig</code> internally, the returned <code>&amp;str</code> is actually <code>&amp;'a str</code>. But we don't need to write any of that.</p> <h3 id="the-bump-helper-method">The <code>bump</code> Helper Method</h3> <p>The <code>bump</code> helper moves a recently accessed index to the front of the access order:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> bump</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> index</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> pos</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>access_order</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">position</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|&amp;</span><span>i</span><span style="color: #94E2D5;">|</span><span> i</span><span style="color: #94E2D5;"> ==</span><span> index</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>access_order</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">remove</span><span style="color: #9399B2;">(</span><span>pos</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>access_order</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span> index</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>It finds where the index currently is in the access order, removes it, and inserts it at the front. This is called every time a key is accessed via <code>get</code> or updated via <code>put</code>.</p> <h3 id="the-get-method">The <code>get</code> Method</h3> <p>The <code>get</code> method looks up a key and returns a reference to the value without copying it:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">pub fn</span><span style="color: #89B4FA;font-style: italic;"> get</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> key</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">K</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">V</span><span style="color: #89DCEB;">&gt;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">where</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> PartialEq</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> idx</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>items</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">position</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;">(</span><span>k</span><span style="color: #9399B2;">,</span><span> _</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">|</span><span> k</span><span style="color: #94E2D5;"> ==</span><span> key</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">bump</span><span style="color: #9399B2;">(</span><span>idx</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>items</span><span style="color: #9399B2;">[</span><span>idx</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. First, we search for the key using <code>self.items.iter().position(...)</code>. The <code>position</code> method walks the iterator and returns the index of the first element where the closure returns <code>true</code>. If no element matches, it returns <code>None</code>, and the <code>?</code> operator makes the whole function return <code>None</code> immediately. Once we have the index, we call <code>self.bump(idx)</code> to move that index to the front of the access order. Then we return <code>Some(&amp;self.items[idx].1)</code>, a reference to the value at that position. The return type is <code>Option&lt;&amp;V&gt;</code>. Notice there is no explicit lifetime annotation on the return value. This works because of elision rule 3: the method takes <code>&amp;mut self</code>, so the output reference has the same lifetime as <code>self</code>. The important thing is that <code>get</code> returns a reference to the value stored inside the cache. No cloning, no copying. The caller gets a direct reference to the cached data. This is zero-copy.</p> <h3 id="the-put-method">The <code>put</code> Method</h3> <p>The <code>put</code> method inserts or updates a key-value pair. If the cache is full, it evicts the least recently used item:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">pub fn</span><span style="color: #89B4FA;font-style: italic;"> put</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> key</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> value</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">where</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> PartialEq</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>idx</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>items</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">position</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;">(</span><span>k</span><span style="color: #9399B2;">,</span><span> _</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">| *</span><span>k</span><span style="color: #94E2D5;"> ==</span><span> key</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>items</span><span style="color: #9399B2;">[</span><span>idx</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">1</span><span style="color: #94E2D5;"> =</span><span> value</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">bump</span><span style="color: #9399B2;">(</span><span>idx</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>items</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> &gt;=</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">capacity</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> evict_index</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>access_order</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">pop</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>items</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">remove</span><span style="color: #9399B2;">(</span><span>evict_index</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> idx</span><span style="color: #CBA6F7;"> in</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>access_order</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter_mut</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> *</span><span>idx</span><span style="color: #94E2D5;"> &gt;</span><span> evict_index</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> *</span><span>idx</span><span style="color: #94E2D5;"> -=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>items</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">((</span><span>key</span><span style="color: #9399B2;">,</span><span> value</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>access_order</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">items</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. The method first checks if the key already exists using <code>position()</code> again. If it does, we update the value in place with <code>self.items[idx].1 = value</code>, bump the access order, and return. If the key does not exist, we check if the cache is full by comparing <code>self.items.len()</code>against <code>self.capacity()</code>. If we are at capacity, we need to evict the least recently used item. The LRU item is at the end of <code>access_order</code>, so we <code>pop()</code> it to get the eviction index, then <code>remove</code> that item from the vector. After removal, any indices in <code>access_order</code> that pointed beyond the removed item need to be decremented by one because <code>remove</code> shifts all later elements down. Finally, we push the new key-value pair onto <code>items</code> and insert its index (which is <code>items.len() - 1</code>) at the front of <code>access_order</code>, marking it as most recently used.</p> <h3 id="the-contains-method">The <code>contains</code> Method</h3> <p>A simple check for key existence:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> PartialEq</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #89DCEB;">&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Cache</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> contains</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> key</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">K</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> bool</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span>key</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_some</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>We call <code>self.get(key)</code> which bumps the access order, then check if the result is <code>Some</code>.</p> <blockquote> <p>Notice that <code>contains</code> takes <code>&amp;mut self</code> instead of <code>&amp;self</code>. That is because checking for existence also updates the access order, which mutates the cache state.</p> </blockquote> <h3 id="the-len-method">The <code>len</code> Method</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #89DCEB;">&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Cache</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> len</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>items</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="module-split-src-cache-rs">Module Split: <code>src/cache.rs</code></h3> <p>Right now, everything is in one file. Let's split the cache implementation into its own module. Create a new file <code>src/cache.rs</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">pub struct</span><span style="color: #F9E2AF;font-style: italic;"> CacheConfig</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> pub</span><span> max_capacity</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> pub</span><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">pub struct</span><span style="color: #F9E2AF;font-style: italic;"> Cache</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> config</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #F9E2AF;font-style: italic;"> CacheConfig</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> items</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">K</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> access_order</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">usize</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #89DCEB;">&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Cache</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> pub fn</span><span style="color: #89B4FA;font-style: italic;"> new</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">config</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #F9E2AF;font-style: italic;"> CacheConfig</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F38BA8;"> Self</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Cache</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> config</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> items</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> access_order</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> pub fn</span><span style="color: #89B4FA;font-style: italic;"> capacity</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>config</span><span style="color: #94E2D5;">.</span><span>max_capacity</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> pub fn</span><span style="color: #89B4FA;font-style: italic;"> name</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt; &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &amp;</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>config</span><span style="color: #94E2D5;">.</span><span>name</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> pub fn</span><span style="color: #89B4FA;font-style: italic;"> len</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>items</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> pub fn</span><span style="color: #89B4FA;font-style: italic;"> contains</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> key</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">K</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> bool</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> where</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> PartialEq</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span>key</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_some</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> pub fn</span><span style="color: #89B4FA;font-style: italic;"> get</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> key</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">K</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">V</span><span style="color: #89DCEB;">&gt;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> where</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> PartialEq</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> idx</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>items</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">position</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;">(</span><span>k</span><span style="color: #9399B2;">,</span><span> _</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">|</span><span> k</span><span style="color: #94E2D5;"> ==</span><span> key</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">bump</span><span style="color: #9399B2;">(</span><span>idx</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>items</span><span style="color: #9399B2;">[</span><span>idx</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> pub fn</span><span style="color: #89B4FA;font-style: italic;"> put</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> key</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> value</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> where</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> PartialEq</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>idx</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>items</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">position</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;">(</span><span>k</span><span style="color: #9399B2;">,</span><span> _</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">| *</span><span>k</span><span style="color: #94E2D5;"> ==</span><span> key</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>items</span><span style="color: #9399B2;">[</span><span>idx</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">1</span><span style="color: #94E2D5;"> =</span><span> value</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">bump</span><span style="color: #9399B2;">(</span><span>idx</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>items</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> &gt;=</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">capacity</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> evict_index</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>access_order</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">pop</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>items</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">remove</span><span style="color: #9399B2;">(</span><span>evict_index</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> idx</span><span style="color: #CBA6F7;"> in</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>access_order</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter_mut</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> *</span><span>idx</span><span style="color: #94E2D5;"> &gt;</span><span> evict_index</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> *</span><span>idx</span><span style="color: #94E2D5;"> -=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>items</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">((</span><span>key</span><span style="color: #9399B2;">,</span><span> value</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>access_order</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">items</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> bump</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> index</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> pos</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>access_order</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">position</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|&amp;</span><span>i</span><span style="color: #94E2D5;">|</span><span> i</span><span style="color: #94E2D5;"> ==</span><span> index</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>access_order</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">remove</span><span style="color: #9399B2;">(</span><span>pos</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>access_order</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span> index</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. Everything is marked <code>pub</code> that needs to be visible outside the module: the structs, <code>new</code>, <code>get</code>, <code>put</code>, <code>capacity</code>, <code>len</code>, <code>name</code>, <code>contains</code>. The <code>bump</code> method is private because it is an internal helper. Notice the where <code>K: PartialEq</code> bounds on <code>get</code>, <code>put</code>, and <code>contains</code>. These methods need to compare keys, so <code>K</code> must implement <code>PartialEq</code>. The <code>where</code> clause is placed on each method that needs it, not on the <code>impl</code> block. This is a stylistic choice. You could also put it on the <code>impl</code> block:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> PartialEq</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #89DCEB;">&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Cache</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">a</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> K</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> V</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // all methods here</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Either is fine. I prefer the method-level bounds when only some methods need the constraint. <code>capacity</code>, <code>len</code>, <code>new</code>, and <code>name</code> do not need <code>PartialEq</code>.</p> <h3 id="the-demo-in-src-main-rs">The Demo in <code>src/main.rs</code></h3> <p>Now let's wire everything together in <code>src/main.rs</code>. First, we declare the module and use the types:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">mod</span><span style="color: #FAB387;"> cache</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> cache</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">Cache</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> CacheConfig</span><span style="color: #9399B2;">};</span></span></code></pre> <p><code>mod cache;</code> tells Rust to look for <code>src/cache.rs</code> and load it as a module. The items inside are accessible as <code>cache::Cache</code>, <code>cache::CacheConfig</code>, etc.</p> <p>Now the demo:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> config</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> CacheConfig</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> max_capacity</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;demo_cache&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> cache</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Cache</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>config</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> cache</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">put</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;key1&quot;</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 100</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> cache</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">put</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;key2&quot;</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 200</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> cache</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">put</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;key3&quot;</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 300</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Cache &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39; has </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> items&quot;</span><span style="color: #9399B2;">,</span><span> cache</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">name</span><span style="color: #9399B2;">(),</span><span> cache</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Capacity: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> cache</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">capacity</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>value</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> cache</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #A6E3A1;">&quot;key1&quot;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;key1 = </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> value</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> cache</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">put</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;key4&quot;</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 400</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;After inserting key4:&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Cache has </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> items&quot;</span><span style="color: #9399B2;">,</span><span> cache</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // key2 should have been evicted (LRU)</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> cache</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">contains</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #A6E3A1;">&quot;key2&quot;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;key2 is still in cache (unexpected)&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;key2 was evicted (expected)&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>value</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> cache</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #A6E3A1;">&quot;key3&quot;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;key3 = </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> value</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span></code></pre> <p>Now, let me explain why this compiles and works despite lifetimes being everywhere. The <code>config</code> is created first. It lives until the end of <code>main</code>. The <code>cache</code> is created with <code>Cache::new(&amp;config)</code>, borrowing from <code>config</code>. The cache cannot outlive <code>config</code>. Since both are dropped at the end of <code>main</code> (cache first, then config, in reverse order of creation), the lifetimes are satisfied.</p> <p>When we call <code>cache.get(&amp;"key1")</code>, it returns <code>Option&lt;&amp;i32&gt;</code>. The returned reference points into the cache's internal storage and remains valid for the duration of the borrow.</p> <h3 id="running-the-project">Running the Project</h3> <p>Type this in your terminal:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> run</span></span></code></pre> <p>You should see output like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Cache</span><span style="color: #A6E3A1;"> &#39;demo_cache&#39; has</span><span style="color: #FAB387;"> 3</span><span style="color: #A6E3A1;"> items</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Capacity:</span><span style="color: #FAB387;"> 3</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">key1</span><span style="color: #A6E3A1;"> =</span><span style="color: #FAB387;"> 100</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">After</span><span style="color: #A6E3A1;"> inserting key4:</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Cache</span><span style="color: #A6E3A1;"> has</span><span style="color: #FAB387;"> 3</span><span style="color: #A6E3A1;"> items</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">key2</span><span style="color: #A6E3A1;"> was evicted</span><span> (expected)</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">key3</span><span style="color: #A6E3A1;"> =</span><span style="color: #FAB387;"> 300</span></span></code></pre> <p>The cache evicted <code>key2</code> because it was the least recently used item. <code>key1</code> stayed in the cache because calling <code>get</code> moved it to the front of the access order.</p> <h2 id="conclusion">Conclusion</h2> <p>In this post, you learned about lifetimes, the three elision rules, and the <code>'static</code> lifetime. You built a generic LRU cache with a lifetime-annotated config reference and zero-copy get that returns <code>Option&lt;&amp;V&gt;</code>, split into <code>src/cache.rs</code> and <code>src/main.rs</code>. In the next article, we will learn about <code>HashMap</code> and build an <strong>inverted index search engine</strong>. See you soon.</p> <p>If you like reading this, please subscribe and share this with others. It'll really help me and motivate me to keep publishing more such articles.</p> 2026-05-09T00:00:00+00:00 2026-05-09T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/learn-generics-traits-in-rust-by-building-blackjack-card-game-engine/ <p>In this post, we are going to learn about generics and traits by building a blackjack card engine in Rust. I'm really excited for this project and I hope you are too. I won't go too deep in theory, just practical and we will build our knowledge of these concepts over time with more articles.</p> <p>The only prerequisite is that you have read the previous articles in this series, as I will assume you know ownership, borrowing, structs, enums, pattern matching and error handling.</p> <p>In this post, we will first learn what generics are, what traits are, how they work together, and then we will build a generic card engine that can work with any card type. We will also use proper error handling throughout, since we already learned about <code>Result</code>, the <code>?</code> operator, and custom error types in the previous article.</p> <p>You can get the source code from <a rel="external" href="https://github.com/MrSheerluck/blackjack-card-engine">here</a></p> <p>Let's start. I can't wait.</p> <h2 id="generics">Generics</h2> <p>Let's say you want to write a function that returns the larger of two values. Without generics, you would need to write a separate function for every type you want to support:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> max_i32</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">a</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> b</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> a</span><span style="color: #94E2D5;"> &gt;</span><span> b</span><span style="color: #9399B2;"> {</span><span> a</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span><span> b</span><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> max_f64</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">a</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f64</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> b</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f64</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> f64</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> a</span><span style="color: #94E2D5;"> &gt;</span><span> b</span><span style="color: #9399B2;"> {</span><span> a</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span><span> b</span><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>These two functions have identical logic. The only difference is the type. If you also wanted to support <code>i64</code>, <code>u32</code>, <code>strings</code>, or your own custom types, you would need to duplicate this code forever. This is not maintainable at all. To solve this issue, we have <strong>generics</strong>. Generics let you write logic once and use it with any type. You introduce a type parameter, which acts as a placeholder for a concrete type.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> identity</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">value</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> value</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The <code>&lt;T&gt;</code> is the type parameter. It says "this function works for any type T". When you call <code>identity(5)</code>, Rust replaces <code>T</code> with <code>i32</code>. When you call <code>identity("hello")</code>, Rust replaces <code>T</code> with <code>&amp;str</code>. The compiler figures this out automatically from the argument you pass. Now let me explain what we just did. The <code>T</code> is just a name. You can use any identifier, but single capital letters like <code>T</code>, <code>U</code>, <code>K</code>, <code>V</code> are conventional. <code>T</code> stands for "type". The compiler generates separate machine code for each concrete type you use. This is called <strong>monomorphization</strong>. It means there is zero runtime cost compared to writing separate functions. The generated code is exactly as fast as if you have written <code>identity_i32</code> and <code>identity_str</code> by hand.</p> <h3 id="generics-structs">Generics Structs</h3> <p>Generics are not limited to functions. Structs can be generic too.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>Point&lt;i32&gt;</code> and <code>Point&lt;f64&gt;</code> are completely different types. The compiler treats them as separate. You cannot mix them.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> p1</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;"> };</span><span style="color: #9399B2;font-style: italic;"> // Point&lt;i32&gt;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> p2</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;"> };</span><span style="color: #9399B2;font-style: italic;"> // Point&lt;f64&gt;</span></span></code></pre> <p>If you try <code>let p = Point { x: 4, y: 3.14 };</code>, you will get a compile error because <code>x</code> and <code>y</code> must be the same type. If you want to be different, you need two type parameters, like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> U</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> U</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now <code>Point&lt;i32, f64&gt;</code> is valid. The convention is to use <code>T</code> and <code>U</code> when they are unrelated and <code>K</code> and <code>V</code> when they represent keys and values.</p> <h3 id="the-limitation">The Limitation</h3> <p>Here is where generics hit a wall. If you try to write that <code>max</code> function using generics:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> max</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">a</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> b</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> a</span><span style="color: #94E2D5;"> &gt;</span><span> b</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> a</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> b</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>You will get a compile error. The compiler will tell you that <code>T</code> does not support <code>&gt;</code> operator. The problem is that <code>T</code> could be anything. It could be a struct you defined that has no concept of ordering. It could be a vector. It could be a file handle. The compiler cannot assume <code>&gt;</code> is valid. This is where traits come in. Traits let you constrain generics. They let you say "this generic function only works with types that can do X".</p> <h2 id="traits">Traits</h2> <p>A trait defines a set of methods that a type must implement. It is a contract. If a type implements a trait, it is promising that is can do certain things. Think of it like this. In real world, a "vehicle" is a concept that promises certain behaviour. Any vehicle can start, stop and turn. A car implements vehicle. A motorcycle implements vehicle. They do it differently but they both fulfill the contract. In Rust, a trait looks like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">trait</span><span style="color: #F9E2AF;font-style: italic;"> Card</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> value</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> u8</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> display</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Any type that wants to be a <code>Card</code> must provide two methods: <code>value</code> and <code>display</code>. The trait only defines signatures, not implementations. The actual code lives in the <code>impl</code> block for each type.</p> <h3 id="implementing-a-trait">Implementing a Trait</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> PokerCard</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> rank</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> suit</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Suit</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Card</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> PokerCard</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> value</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> u8</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // implementation</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> display</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // implementation</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The syntax is <code>impl TRAIT for TYPE</code>. This is different from inherent methods which are just <code>impl Type</code>. The trait implementation attaches the behavior to the type. Now let me explain what we just did. <code>impl Card for PokerCard</code> says "PokerCard fulfills the Card contract." Inside the block, we provide the actual code for <code>value</code> and <code>display</code>. If we forget either method, the compiler will reject our code because the trait contract is incomplete.</p> <h3 id="default-implementations">Default Implementations</h3> <p>Traits can provide default behaviour. The implementor can use it or override it.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">trait</span><span style="color: #F9E2AF;font-style: italic;"> Card</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> value</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> u8</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> is_face</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> bool</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">value</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> &gt;=</span><span style="color: #FAB387;"> 10</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Here <code>is_face</code> has a default body. If you implement <code>Card</code> for <code>PokerCard</code> and only provide <code>value</code>, you get <code>is_face</code> for free. But you can override it if you want custom logic.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Card</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> PokerCard</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> value</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> u8</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>rank </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Two</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Three</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // ...</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Ace</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #FAB387;"> 11</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> is_face</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> bool</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // custom override</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> matches!</span><span style="color: #9399B2;">(</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>rank</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Jack</span><span style="color: #94E2D5;"> |</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Queen</span><span style="color: #94E2D5;"> |</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">King</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="trait-bounds">Trait Bounds</h3> <p>Remember the max function that would not compile? Traits fix it.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> max</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> PartialOrd</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">a</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> b</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> a</span><span style="color: #94E2D5;"> &gt;</span><span> b</span><span style="color: #9399B2;"> {</span><span> a</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span><span> b</span><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>T: PartialOrd</code> is a trait bound. It means "T must implement the PartialOrd trait." <code>PartialOrd</code> is a standard library trait that provides ordering operations like <code>&lt;</code>, <code>&gt;</code>, <code>&lt;=</code>, <code>&gt;=</code>. The compiler checks this at the call site. If you try to pass a type that does not implement PartialOrd, you get a clean compile error.</p> <h3 id="multiple-trait-bounds">Multiple Trait Bounds</h3> <p>Sometimes one bound is not enough.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> process</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Card</span><span style="color: #94E2D5;"> +</span><span style="color: #F9E2AF;font-style: italic;"> Clone</span><span style="color: #94E2D5;"> +</span><span style="color: #F9E2AF;font-style: italic;"> Debug</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">card</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">:?</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> card</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Value: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> card</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">value</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This means <code>T</code> must implement <code>Card</code> and <code>Clone</code> and <code>Debug</code>. When you have many bounds, the where clause is cleaner:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> process</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">card</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">where</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Card</span><span style="color: #94E2D5;"> +</span><span style="color: #F9E2AF;font-style: italic;"> Clone</span><span style="color: #94E2D5;"> +</span><span style="color: #F9E2AF;font-style: italic;"> Debug</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">:?</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> card</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Value: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> card</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">value</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Both mean the same thing. Pick whichever reads better. I prefer <code>where</code> when there are more than two bounds because it keeps the function signature readable.</p> <h3 id="derive">Derive</h3> <p>Rust can auto implement some traits for you.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Debug</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Clone</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Copy</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> PartialEq</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> PokerCard</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> rank</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> suit</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Suit</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This generates <code>Debug</code>, <code>Clone</code>, <code>Copy</code>, and <code>PartialEq</code> implementations automatically. You cannot derive everything. <code>Display</code> and custom traits like <code>Card</code> must be written by hand because the compiler does not know how you want them formatted. Here is a table of commonly derived traits:</p> <table><thead><tr><th>Trait</th><th>What It Gives You</th></tr></thead><tbody> <tr><td><code>Debug</code></td><td><code>{:?}</code> formatting for programmer output</td></tr> <tr><td><code>Clone</code></td><td><code>.clone()</code> method to duplicate</td></tr> <tr><td><code>Copy</code></td><td>Bitwise copy on assignment instead of move</td></tr> <tr><td><code>PartialEq</code></td><td><code>==</code> and <code>!=</code> operators</td></tr> <tr><td><code>Eq</code></td><td>Reflexive equality, used by HashMap</td></tr> <tr><td><code>PartialOrd</code></td><td><code>&lt;</code>, <code>&gt;</code>, <code>&lt;=</code>, <code>&gt;=</code> operators</td></tr> <tr><td><code>Ord</code></td><td>Total ordering, used by sorting</td></tr> <tr><td><code>Hash</code></td><td>Used by HashMap</td></tr> <tr><td><code>Default</code></td><td><code>Default::default()</code> constructor</td></tr> </tbody></table> <h3 id="the-orphan-rule">The Orphan Rule</h3> <p>You can implement a trait for a type if either the trait or the type is defined in your crate. You cannot implement a foreign trait for a foreign type. For example, you cannot do this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Display</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">u8</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // ERROR: both Display and Vec are from std</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This prevents conflicting implementations from different crates. If crate A and crate B both implemented <code>Display</code> for <code>Vec&lt;u8&gt;</code>, and you used both crates, which implementation would win? Rust avoids this ambiguity entirely. If you need to add behavior to a foreign type, wrap it in your own struct. This is called the newtype pattern.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> ByteVec</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">u8</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Display</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> ByteVec</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> fmt</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> f</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Formatter</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">_</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;"> fmt</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Result</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> write!</span><span style="color: #9399B2;">(</span><span>f</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">:?</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>ByteVec</code> is your type, so you can implement any trait for it.</p> <h3 id="traits-on-generic-structs">Traits on Generic Structs</h3> <p>This is where everything comes together. You can write impl blocks for generic structs with trait bounds.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Deck</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> cards</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Card</span><span style="color: #94E2D5;"> +</span><span style="color: #F9E2AF;font-style: italic;"> Clone</span><span style="color: #94E2D5;"> +</span><span style="color: #F9E2AF;font-style: italic;"> Debug</span><span style="color: #89DCEB;">&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Deck</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> shuffle</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">) {</span><span style="color: #94E2D5;"> ...</span><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> deal</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> GameError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span><span style="color: #94E2D5;"> ...</span><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> len</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;"> {</span><span style="color: #94E2D5;"> ...</span><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>impl&lt;T: Card + Clone + Debug&gt; Deck&lt;T&gt;</code> means these methods only exist for <code>Deck&lt;T&gt;</code> when T implements all three traits. Inside the block, you can call <code>card.value()</code> because <code>T: Card</code>. You can <code>card.clone()</code> because <code>T: Clone</code>. Without the bounds, <code>T</code> is an unknown blob and the compiler will reject any method call. But here is something important. A generic <code>Deck&lt;T&gt;</code> should not know how to create <code>T</code>. Creating 52 poker cards is specific to poker cards. A <code>Deck&lt;UnoCard&gt;</code> would need different cards entirely. So we keep the generic methods (shuffle, deal, len) on <code>impl&lt;T&gt; Deck&lt;T&gt;</code>, but we put the constructor on a separate, non-generic impl block:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Deck</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">PokerCard</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> new</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F38BA8;"> Self</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> cards</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> suit</span><span style="color: #CBA6F7;"> in</span><span style="color: #9399B2;"> [</span><span style="color: #F9E2AF;font-style: italic;">Suit</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Hearts</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Suit</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Diamonds</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Suit</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Clubs</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Suit</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Spades</span><span style="color: #9399B2;">] {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> rank</span><span style="color: #CBA6F7;"> in</span><span style="color: #9399B2;"> [</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Two</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Three</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Four</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Five</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Six</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Seven</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Eight</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Nine</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Ten</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Jack</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Queen</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">King</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Ace</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ] {</span></span> <span class="giallo-l"><span> cards</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">PokerCard</span><span style="color: #9399B2;"> {</span><span> rank</span><span style="color: #9399B2;">,</span><span> suit</span><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Deck</span><span style="color: #9399B2;"> {</span><span> cards</span><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>impl Deck&lt;PokerCard&gt;</code> means these methods only exist for <code>Deck&lt;PokerCard&gt;</code>, not for any other <code>Deck&lt;T&gt;</code>. This is how we keep the engine generic while still having a concrete constructor for our specific card type.</p> <h2 id="what-we-are-skipping">What We Are Skipping</h2> <p>We are not covering lifetimes in this article. We will cover them properly in a later article. We are also not covering trait objects. That comes later when we talk about smart pointers. We are also not covering associated types or generic associated types. Those are advanced topics for future articles.</p> <h2 id="the-project">The Project</h2> <p>Now that you understand generics and traits, let's build the blackjack engine. We will use proper error handling throughout, since we already learned about <code>Result</code>, custom error types, and the <code>?</code> operator in the previous article. We are going to build a command line blackjack game. We are going to build a generic card engine. The deck and the hand will work with any type of card that implements the <code>Card</code> trait.</p> <h3 id="project-setup">Project Setup</h3> <p>Open your terminal and run:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> new blackjack-card-engine</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> blackjack-card-engine</span></span></code></pre> <p>Now open the <code>Cargo.toml</code> file and add the dependencies:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;">[</span><span>package</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>name</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;blackjack-card-engine&quot;</span></span> <span class="giallo-l"><span>version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.1.0&quot;</span></span> <span class="giallo-l"><span>edition</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;2024&quot;</span></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>dependencies</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>rand</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.8&quot;</span></span> <span class="giallo-l"><span>thiserror</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;2&quot;</span></span></code></pre> <p>We added <code>thiserror</code> because we will define a custom error type for our game. We learned about <code>thiserror</code> in the previous article. Now open <code>src/main.rs</code> and delete the generated code. We will start fresh.</p> <h3 id="defining-error-types">Defining Error Types</h3> <p>Since we are using proper error handling, let's define our error type first.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> thiserror</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Error</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Error</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Debug</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> GameError</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Deck is empty&quot;</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> EmptyDeck</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid input: </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">0</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> InvalidInput</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;IO error: </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">0</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Io</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">from</span><span style="color: #9399B2;">]</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">io</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Error</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. <code>#[derive(Error)]</code> from <code>thiserror</code> automatically implements the <code>Error</code> and <code>Display</code> traits for us. <code>#[error("...")]</code> defines the display message for each variant. <code>#[from] std::io::Error</code> auto-implements <code>From&lt;std::io::Error&gt;</code> for our <code>GameError</code>, which means we can use the ? operator on <code>std::io</code> operations and they will automatically convert.</p> <h3 id="rank-and-suit">Rank and Suit</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Debug</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Clone</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Copy</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> PartialEq</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Two</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Three</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Four</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Five</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Six</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Seven</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Eight</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Nine</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Ten</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Jack</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Queen</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> King</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Ace</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Debug</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Clone</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Copy</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> PartialEq</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Suit</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Hearts</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Diamonds</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Clubs</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Spades</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>We derive <code>Debug</code>, <code>Clone</code>, <code>Copy</code>, and <code>PartialEq</code>. These are simple value types, so deriving all four makes sense. <code>Copy</code> means they are bitwise copied when assigned, not moved. This is important because we will be passing them around a lot.</p> <h3 id="the-card-trait">The Card Trait</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">trait</span><span style="color: #F9E2AF;font-style: italic;"> Card</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> value</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> u8</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> display</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Any type that implements <code>Card</code> must provide a numeric value and a display string.</p> <h3 id="the-pokercard-struct">The PokerCard Struct</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Debug</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Clone</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Copy</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> PartialEq</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> PokerCard</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> rank</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> suit</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Suit</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="display-implementation">Display Implementation</h3> <p>We cannot derive <code>Display</code>, so we implement it manually.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span>fmt</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;"> fmt</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Display</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> fmt</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> f</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;"> fmt</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Formatter</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">_</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;"> fmt</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Result</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Two</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;2&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Three</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;3&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Four</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;4&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Five</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;5&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Six</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;6&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Seven</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;7&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Eight</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;8&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Nine</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;9&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Ten</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;10&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Jack</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;J&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Queen</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;Q&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">King</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;K&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Ace</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;A&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> write!</span><span style="color: #9399B2;">(</span><span>f</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> s</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;"> fmt</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Display</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> Suit</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> fmt</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> f</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;"> fmt</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Formatter</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">_</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;"> fmt</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Result</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> symbol</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Suit</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Hearts</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;♥&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Suit</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Diamonds</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;♦&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Suit</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Clubs</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;♣&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Suit</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Spades</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;♠&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> write!</span><span style="color: #9399B2;">(</span><span>f</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> symbol</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;"> fmt</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Display</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> PokerCard</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> fmt</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> f</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;"> fmt</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Formatter</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">_</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;"> fmt</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Result</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> write!</span><span style="color: #9399B2;">(</span><span>f</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> of </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>rank</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>suit</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. <code>fmt::Display</code> is the trait for user-facing string formatting. It is what <code>println!("{}", value)</code> uses. The <code>Formatter&lt;'_&gt;</code> is the output target.</p> <blockquote> <p>You might notice the <code>'_</code> inside <code>Formatter&lt;'_&gt;</code>. This is a lifetime annotation. Every reference in Rust has a lifetime, which is how long the reference stays valid. The Formatter struct borrows an output buffer, and Rust needs to track how long that borrow lasts. Writing <code>'_</code> tells the compiler 'I don't want to name this lifetime, just figure it out automatically.<code>'</code> This is called lifetime elision. The compiler looks at the function signature and infers the correct lifetime for you. We will cover lifetimes properly in a later article, but for now just understand that <code>'_</code> means 'the compiler will handle this borrow check for us.'</p> </blockquote> <h3 id="implement-card-for-pokercard">Implement Card for PokerCard</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Card</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> PokerCard</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> value</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> u8</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>rank </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Two</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Three</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Four</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #FAB387;"> 4</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Five</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Six</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #FAB387;"> 6</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Seven</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #FAB387;"> 7</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Eight</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #FAB387;"> 8</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Nine</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #FAB387;"> 9</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Ten</span><span style="color: #94E2D5;"> |</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Jack</span><span style="color: #94E2D5;"> |</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Queen</span><span style="color: #94E2D5;"> |</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">King</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Ace</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #FAB387;"> 11</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> display</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The Ace returns 11. The hand scoring logic will handle the soft Ace calculation.</p> <h3 id="the-generic-deck">The Generic Deck</h3> <p>We need the <code>Debug</code> trait in scope for our generic bounds, so we import it:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">fmt</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Debug</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> rand</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">seq</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">SliceRandom</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Deck</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> cards</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now for the generic methods. These work with any <code>T</code> that implements <code>Card</code>, <code>Clone</code>, and <code>Debug</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Card</span><span style="color: #94E2D5;"> +</span><span style="color: #F9E2AF;font-style: italic;"> Clone</span><span style="color: #94E2D5;"> +</span><span style="color: #F9E2AF;font-style: italic;"> Debug</span><span style="color: #89DCEB;">&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Deck</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> shuffle</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>cards</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">shuffle</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;"> rand</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">thread_rng</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> deal</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> GameError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>cards</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">pop</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">ok_or</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">GameError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">EmptyDeck</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> len</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>cards</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. <code>impl&lt;T: Card + Clone + Debug&gt; Deck&lt;T&gt;</code> means these methods only exist when <code>T</code> implements all three traits. Inside this block, we can call <code>card.value()</code> because <code>T: Card</code>. We can <code>card.clone()</code> because <code>T: Clone</code>. Notice that <code>deal</code> now returns <code>Result&lt;T, GameError&gt;</code> instead of <code>Option&lt;T&gt;</code>. We use <code>ok_or</code> to convert <code>None</code> into our custom error. This is proper error handling. In the previous article, we might have used <code>expect</code> or <code>unwrap</code>. Now we use <code>Result</code>. But wait. Where is <code>new</code>? We cannot put <code>new</code> in the generic impl because a generic <code>Deck&lt;T&gt;</code> does not know how to create <code>T</code>. Creating 52 poker cards is specific to <code>PokerCard</code>. So we put it on a separate impl block that is only for <code>Deck&lt;PokerCard&gt;</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Deck</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">PokerCard</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> new</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F38BA8;"> Self</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> cards</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> suit</span><span style="color: #CBA6F7;"> in</span><span style="color: #9399B2;"> [</span><span style="color: #F9E2AF;font-style: italic;">Suit</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Hearts</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Suit</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Diamonds</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Suit</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Clubs</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Suit</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Spades</span><span style="color: #9399B2;">] {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> rank</span><span style="color: #CBA6F7;"> in</span><span style="color: #9399B2;"> [</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Two</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Three</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Four</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Five</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Six</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Seven</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Eight</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Nine</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Ten</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Jack</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Queen</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">King</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Rank</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Ace</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ] {</span></span> <span class="giallo-l"><span> cards</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">PokerCard</span><span style="color: #9399B2;"> {</span><span> rank</span><span style="color: #9399B2;">,</span><span> suit</span><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Deck</span><span style="color: #9399B2;"> {</span><span> cards</span><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>impl Deck&lt;PokerCard&gt;</code> means <code>new()</code> only exists for <code>Deck&lt;PokerCard&gt;</code>. If you tried to write <code>Deck::&lt;UnoCard&gt;::new()</code>, you would get a compile error because there is no <code>new</code> for that type. This is the correct way to handle it: keep the engine generic, but put concrete constructors on concrete types.</p> <h3 id="the-generic-hand">The Generic Hand</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Hand</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> cards</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Card</span><span style="color: #89DCEB;">&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Hand</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> new</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F38BA8;"> Self</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Hand</span><span style="color: #9399B2;"> {</span><span> cards</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">() }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> add</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> card</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>cards</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>card</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> score</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> u8</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> total</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> aces</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> card</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>cards </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> value</span><span style="color: #94E2D5;"> =</span><span> card</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">value</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> total</span><span style="color: #94E2D5;"> +=</span><span> value</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> value</span><span style="color: #94E2D5;"> ==</span><span style="color: #FAB387;"> 11</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> aces</span><span style="color: #94E2D5;"> +=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> while</span><span> total</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #FAB387;"> 21</span><span style="color: #94E2D5;"> &amp;&amp;</span><span> aces</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> total</span><span style="color: #94E2D5;"> -=</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> aces</span><span style="color: #94E2D5;"> -=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> total</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> display</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>cards</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">iter</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>c</span><span style="color: #94E2D5;">|</span><span> c</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">display</span><span style="color: #9399B2;">())</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Vec</span><span style="color: #89DCEB;">&lt;</span><span>_</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">join</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;, &quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain the scoring. We iterate through every card and add up the values. We also count how many Aces we saw. After the loop, if the total is over 21 and we have Aces, we convert each Ace from 11 to 1 by subtracting 10. We keep doing this until the total is 21 or below, or we run out of Aces. This is the standard blackjack soft hand rule.</p> <h3 id="the-run-pattern">The Run Pattern</h3> <p>Just like in the previous article, we keep <code>main</code> simple and put our game logic in a <code>run</code> function that returns <code>Result</code>.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> run</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(),</span><span style="color: #F9E2AF;font-style: italic;"> GameError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> deck</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Deck</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> deck</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">shuffle</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> player</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Hand</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> dealer</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Hand</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Deal initial cards</span></span> <span class="giallo-l"><span> player</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add</span><span style="color: #9399B2;">(</span><span>deck</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">deal</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> dealer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add</span><span style="color: #9399B2;">(</span><span>deck</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">deal</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> player</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add</span><span style="color: #9399B2;">(</span><span>deck</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">deal</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> dealer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add</span><span style="color: #9399B2;">(</span><span>deck</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">deal</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Your hand: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> (score: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">)&quot;</span><span style="color: #9399B2;">,</span><span> player</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">display</span><span style="color: #9399B2;">(),</span><span> player</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">score</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Dealer shows: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> dealer</span><span style="color: #94E2D5;">.</span><span>cards</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">display</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Player turn</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> loop</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Hit or stand? (h/s)&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> input</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">io</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">stdin</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">read_line</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span> input</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> input</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">trim</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;h&quot;</span><span style="color: #94E2D5;"> |</span><span style="color: #A6E3A1;"> &quot;hit&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> card</span><span style="color: #94E2D5;"> =</span><span> deck</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">deal</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;You drew: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> card</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">display</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span> player</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add</span><span style="color: #9399B2;">(</span><span>card</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Your hand: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> (score: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">)&quot;</span><span style="color: #9399B2;">,</span><span> player</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">display</span><span style="color: #9399B2;">(),</span><span> player</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">score</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> player</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">score</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &gt;</span><span style="color: #FAB387;"> 21</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Bust! You lose.&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(());</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;s&quot;</span><span style="color: #94E2D5;"> |</span><span style="color: #A6E3A1;"> &quot;stand&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">GameError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">InvalidInput</span><span style="color: #9399B2;">(</span><span>input</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">trim</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">()));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Dealer turn</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Dealer hand: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> (score: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">)&quot;</span><span style="color: #9399B2;">,</span><span> dealer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">display</span><span style="color: #9399B2;">(),</span><span> dealer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">score</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> while</span><span> dealer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">score</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &lt;</span><span style="color: #FAB387;"> 17</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> card</span><span style="color: #94E2D5;"> =</span><span> deck</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">deal</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Dealer drew: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> card</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">display</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span> dealer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">add</span><span style="color: #9399B2;">(</span><span>card</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Dealer hand: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> (score: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">)&quot;</span><span style="color: #9399B2;">,</span><span> dealer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">display</span><span style="color: #9399B2;">(),</span><span> dealer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">score</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> dealer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">score</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &gt;</span><span style="color: #FAB387;"> 21</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Dealer busts! You win.&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(());</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Determine winner</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> player_score</span><span style="color: #94E2D5;"> =</span><span> player</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">score</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> dealer_score</span><span style="color: #94E2D5;"> =</span><span> dealer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">score</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Final - You: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">, Dealer: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> player_score</span><span style="color: #9399B2;">,</span><span> dealer_score</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> player_score</span><span style="color: #94E2D5;"> &gt;</span><span> dealer_score</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;You win!&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else if</span><span> dealer_score</span><span style="color: #94E2D5;"> &gt;</span><span> player_score</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Dealer wins!&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Push! It&#39;s a tie.&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(())</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> run</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> eprintln!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Error: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> e</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">process</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">exit</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did. <code>run</code> returns <code>Result&lt;(), GameError&gt;</code>. We use <code>?</code> everywhere an operation can fail. <code>deck.deal()?</code> propagates the <code>EmptyDeck</code> error. <code>std::io::stdin().read_line(&amp;mut input)?</code> propagates IO errors, and thanks to <code>#[from] std::io::Error</code> on our error type, the <code>?</code> operator automatically converts it. <code>main</code> calls <code>run</code> and handles the error. If there is an error, it prints to stderr and exits with code 1. This is the exact pattern we used in the TOML parser article.</p> <h3 id="running-the-project">Running the Project</h3> <p>Type this in your terminal:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> run</span></span></code></pre> <p>You should see output like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>Your hand: A of ♠, 10 of ♥ (score: 21)</span></span> <span class="giallo-l"><span>Dealer shows: 7 of ♦</span></span> <span class="giallo-l"><span>Hit or stand? (h/s)</span></span></code></pre> <p>Try playing a few hands. The generic engine is working.</p> <h2 id="conclusion">Conclusion</h2> <p>In this post, you learned about generics and traits. You learned that generics let you write code once and use it with any type, and that traits define contracts that constrain those generics.</p> <p>You learned about trait bounds, default implementations, the orphan rule, and the derive macro. You also learned how to combine generics and traits to build truly reusable code.</p> <p>You built a generic blackjack card engine with proper error handling using <code>Result</code>, custom error types with <code>thiserror</code>, and the <code>?</code> operator. The engine works with any card type that implements the <code>Card</code> trait.</p> <p>In the next article, we will learn about HashMap and build an inverted index search engine. I hope to see you soon. Till then, goodbye.</p> 2026-05-06T00:00:00+00:00 2026-05-06T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/learn-error-hanlding-in-rust/ <p>In this post, we are going to learn about error handling in Rust. Once we cover all the concepts, we will build a <strong>TOML config parser with schema validation</strong>. Every error must be handled properly using <code>Result</code>. Let's start.</p> <p>You can get the source code from <strong><a rel="external" href="https://github.com/MrSheerluck/toml-config-parser-in-rust">here</a></strong></p> <h2 id="why-panic-and-unwrap-are-not-enough">Why <code>panic!</code> and <code>unwrap</code> Are Not Enough</h2> <p>In the previous articles, we used <code>panic!</code> and <code>.expect()</code> and <code>.unwrap()</code> all over the place. When something went wrong, we just crashed the program. Let me remind you:</p> <p>In the JSON parser, when the lexer hit an unexpected character, we did this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>panic!(&quot;Unexpected character: {}&quot;, c as char);</span></span></code></pre> <p>And when the parser encountered a token it didn't expect:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>panic!(&quot;Expected &#39;:&#39; in object&quot;);</span></span></code></pre> <p>This is fine for a learning exercise. But real software can't just crash when something goes wrong. A web server can't crash because one request had bad input, it needs to return an error to that client and keep serving others. A config parser can't crash because one field has the wrong type, it needs to tell the user exactly what's wrong and move on.</p> <p>Here's the rule you should internalise:</p> <blockquote> <p><code>panic!</code> is for <strong>programmer bugs</strong>: things that should never happen if your code is correct. Like indexing past the end of an array, or dividing by zero. These are "I messed up" situations.</p> <p><code>Result</code> is for <strong>expected failures</strong>: things that can happen even when your code is perfect. Like bad user input, missing files, network timeouts. These are "something went wrong and I need to handle it" situations.</p> </blockquote> <p>In this article, we are going to replace every <code>panic!</code> and <code>.unwrap()</code> with proper <code>Result</code> based error handling. By the end, our program will never crash unexpectedly. It will always produce a clear, specific error message telling you exactly what went wrong and where.</p> <h2 id="option-t-dealing-with-absence"><code>Option&lt;T&gt;</code> - Dealing with Absence</h2> <p>Before we get to <code>Result</code>, let's talk about its simpler cousin: <code>Option</code>.</p> <p>How many times have you written code that returns <code>null</code> or <code>-1</code> or some magic value to signal "nothing found"? In Rust, we don't do that. Instead, we use <code>Option&lt;T&gt;</code>.</p> <p><code>Option&lt;T&gt;</code> is an enum with two variants:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #9399B2;">),</span><span style="color: #9399B2;font-style: italic;"> // there is a value, and it&#39;s of type T</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #9399B2;">,</span><span style="color: #9399B2;font-style: italic;"> // there is no value</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Instead of returning <code>null</code> or <code>-1</code>, a function returns <code>Option&lt;T&gt;</code>. If it has a value, it returns <code>Some(value)</code>. If not, it returns <code>None</code>.</p> <h3 id="creating-options">Creating Options</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> some_number</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">42</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> some_string</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> nothing</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #9399B2;">;</span></span></code></pre> <p>When you create a <code>Some</code> value, Rust can infer the type <code>T</code>. But when you create a <code>None</code>, Rust needs to know what type <code>T</code> would be if it were <code>Some</code>, so you often need a type annotation.</p> <h3 id="pattern-matching-on-option">Pattern Matching on Option</h3> <p>You can <code>match</code> on an <code>Option</code> just like any other enum:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> maybe_number</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">42</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> maybe_number</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;got </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> n</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;got nothing&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Or use <code>if let</code> when you only care about one variant:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> maybe_number</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;got </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> n</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>We actually used <code>Option</code> in previous articles. Remember the brainfuck interpreter? <code>Lexer::current()</code> returned <code>Option&lt;u8&gt;</code>. <code>Some(byte)</code> when there was a byte to read, <code>None</code> when we reached the end of input. The JSON parser's <code>Parser::current()</code> also returned <code>Option&lt;&amp;Token&gt;</code>. These are natural uses of <code>Option</code>, sometimes there's a value, sometimes there isn't, and the type system forces you to handle both cases.</p> <h3 id="useful-methods-on-option">Useful Methods on Option</h3> <p><strong><code>.unwrap()</code></strong>: extract the value inside <code>Some</code>, or panic if <code>None</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">());</span><span style="color: #9399B2;font-style: italic;"> // 5</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">());</span><span style="color: #9399B2;font-style: italic;"> // PANICS!</span></span></code></pre> <p>We're trying to get away from <code>unwrap</code>, but you should still know what it does.</p> <p><strong><code>.unwrap_or(default)</code></strong>: extract the value, or return a default if <code>None</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap_or</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">));</span><span style="color: #9399B2;font-style: italic;"> // 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> y</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">42</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap_or</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">));</span><span style="color: #9399B2;font-style: italic;"> // 42</span></span></code></pre> <p><strong><code>.is_some()</code> and <code>.is_none()</code></strong>: check which variant you have:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_some</span><span style="color: #9399B2;">());</span><span style="color: #9399B2;font-style: italic;"> // true</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_none</span><span style="color: #9399B2;">());</span><span style="color: #9399B2;font-style: italic;"> // false</span></span></code></pre><h2 id="result-t-e-dealing-with-failure"><code>Result&lt;T, E&gt;</code> - Dealing with Failure</h2> <p><code>Option&lt;T&gt;</code> handles absence. <code>Result&lt;T, E&gt;</code> handles failure. They look similar, but serve different purposes:</p> <ul> <li><code>Option&lt;T&gt;</code> - "there might be a value, or there might be nothing" (like searching for something in a collection)</li> <li><code>Result&lt;T, E&gt;</code> - "this operation might succeed with a value of type T, or it might fail with an error of type E" (like parsing a file, reading from disk, making a network request)</li> </ul> <p><code>Result&lt;T, E&gt;</code> is an enum with two variants:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> E</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #9399B2;">),</span><span style="color: #9399B2;font-style: italic;"> // success, contains a value of type T</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">E</span><span style="color: #9399B2;">),</span><span style="color: #9399B2;font-style: italic;"> // failure, contains an error of type E</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>We actually already used <code>Result</code> in the grep article. <code>Regex::new(pattern)</code> returns <code>Result&lt;Regex, Error&gt;</code>. If the pattern is valid regex, you get <code>Ok(regex)</code>. If it's malformed, you get <code>Err(error)</code>. And we matched on it:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> regex</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #F9E2AF;font-style: italic;"> Regex</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>pattern</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>r</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> r</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> eprintln!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid pattern: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> e</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">process</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">exit</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">};</span></span></code></pre> <p>Now we're going to go much deeper.</p> <h3 id="pattern-matching-on-result">Pattern Matching on Result</h3> <p>Just like <code>Option</code>, you can match on <code>Result</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> result</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>value</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;success: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> value</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>error</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;failure: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> error</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="useful-methods-on-result">Useful Methods on Result</h3> <p><strong><code>.unwrap()</code></strong> - extract the <code>Ok</code> value, or panic on <code>Err</code>. Same warning as above: we're moving away from this.</p> <p><strong><code>.expect("message")</code></strong> - like <code>unwrap</code>, but panics with your custom message:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> bad</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;error&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span>bad</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">expect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;the number should be valid&quot;</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // PANICS with &quot;the number should be valid: error&quot;</span></span></code></pre> <p><strong><code>.unwrap_or(default)</code></strong> - extract the <code>Ok</code> value, or return a default on <code>Err</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> bad</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;oops&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> bad</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap_or</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">));</span><span style="color: #9399B2;font-style: italic;"> // 0</span></span></code></pre> <p><strong><code>.is_ok()</code> and <code>.is_err()</code></strong> - check which variant you have:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> result</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">42</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_ok</span><span style="color: #9399B2;">());</span><span style="color: #9399B2;font-style: italic;"> // true</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_err</span><span style="color: #9399B2;">());</span><span style="color: #9399B2;font-style: italic;"> // false</span></span></code></pre><h2 id="the-operator">The <code>?</code> Operator</h2> <p>Here's a common pattern in Rust. You call a function that returns a <code>Result</code>. If it's <code>Ok</code>, you continue. If it's <code>Err</code>, you return the error to the caller. Written out with <code>match</code>, it looks like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> do_something</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> MyError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> a</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #89B4FA;font-style: italic;"> step_one</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>value</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> value</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> b</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #89B4FA;font-style: italic;"> step_two</span><span style="color: #9399B2;">(</span><span>a</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>value</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> value</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> c</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #89B4FA;font-style: italic;"> step_three</span><span style="color: #9399B2;">(</span><span>b</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>value</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> value</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This is called the "pyramid of doom" and it's exhausting to write and read. Rust has the <code>?</code> operator to fix this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> do_something</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i32</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> MyError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> a</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> step_one</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> b</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> step_two</span><span style="color: #9399B2;">(</span><span>a</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> c</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> step_three</span><span style="color: #9399B2;">(</span><span>b</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The <code>?</code> operator does exactly what the <code>match</code> version does:</p> <ul> <li>If the <code>Result</code> is <code>Ok(value)</code>, it extracts the value and continues</li> <li>If the <code>Result</code> is <code>Err(error)</code>, it returns the error from the current function immediately</li> </ul> <p>It also works on <code>Option</code>:</p> <ul> <li>If <code>Some(value)</code>, it extracts the value and continues</li> <li>If <code>None</code>, it returns <code>None</code> from the current function</li> </ul> <blockquote> <p>There's one catch: the function you're using <code>?</code> in must return a <code>Result</code> (or <code>Option</code>). You can't use <code>?</code> in <code>main</code> unless <code>main</code> returns a <code>Result</code>. We'll handle this by keeping our main logic in a separate <code>run</code> function that returns <code>Result</code>.</p> </blockquote> <h3 id="also-converts-error-types"><code>?</code> Also Converts Error Types</h3> <p>If your function returns <code>Result&lt;T, ErrorA&gt;</code> and a function you call returns <code>Result&lt;T, ErrorB&gt;</code>, you can't just use <code>?</code> directly because the error types don't match. But if <code>ErrorA</code> implements <code>From&lt;ErrorB&gt;</code>, then <code>?</code> will automatically convert <code>ErrorB</code> into <code>ErrorA</code> for you.</p> <p>We'll use this in our project our custom <code>ConfigError</code> type will implement <code>From&lt;std::io::Error&gt;</code> (via <code>thiserror</code>) so that we can use <code>?</code> on file-reading operations that return <code>io::Error</code>.</p> <h2 id="defining-custom-error-types">Defining Custom Error Types</h2> <p>Using <code>String</code> as your error type works, but it's not great. You can't programmatically inspect what went wrong. You can't match on different kinds of errors. You can't add structured data like line numbers and column numbers.</p> <p>The solution is to define your own error type as an enum. Let me show you how.</p> <h3 id="creating-the-error-enum">Creating the Error Enum</h3> <p>First, define the error enum with a variant for each kind of error:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> ConfigError</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> UnexpectedCharacter</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> expected</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> found</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> UnterminatedString</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> InvalidNumber</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> detail</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Each variant carries specific data about what went wrong and where. <code>UnexpectedCharacter</code> tells you the line, column, what was expected, and what was found. <code>UnterminatedString</code> tells you where the string started. <code>InvalidNumber</code> gives you the position and what was wrong with the number.</p> <p>This is the structural approach. When you need to display an error message, you match on the variant and format it. When you need to handle specific errors differently, you match on the variant and take different actions.</p> <h3 id="using-thiserror-to-automate-the-boilerplate">Using <code>thiserror</code> to Automate the Boilerplate</h3> <p>Writing error messages by hand is repetitive. Every time you add a variant, you have to update the match. The <code>thiserror</code> crate automates this with derive macros:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> thiserror</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Error</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Debug</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> thiserror</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Error</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> ConfigError</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;unexpected character at line </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">line</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">, column </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">col</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">: expected </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">expected</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">, found &#39;</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">found</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&#39;&quot;</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> UnexpectedCharacter</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> expected</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> found</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;unterminated string starting at line </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">line</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">, column </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">col</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> UnterminatedString</span><span style="color: #9399B2;"> {</span><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;invalid number at line </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">line</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">, column </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">col</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">: </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">detail</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> InvalidNumber</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> detail</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The <code>#[error("...")]</code> attribute on each variant replaces the manual message formatting. The <code>{field}</code> placeholders inside the string are replaced with the field values, just like <code>println!</code>. And the <code>#[derive(thiserror::Error)]</code> macro generates all the necessary trait implementations for us.</p> <p>Under the hood, <code>thiserror</code> implements two traits for our <code>ConfigError</code>:</p> <ul> <li><strong>The Display trait</strong> - this controls how the error appears when you format it with <code>{}</code> (like <code>format!("{}", err)</code> or <code>println!("{}", err)</code>). The <code>#[error("...")]</code> attribute becomes the Display implementation.</li> <li><strong>The Error trait</strong> - this marks our type as an official error in Rust's error system. It's required for interoperability. We'll learn more about traits in a future article, but for now, just know that <code>#[derive(thiserror::Error)]</code> handles it for us.</li> </ul> <p>The <code>Io(#[from] std::io::Error)</code> variant is special. The <code>#[from]</code> attribute tells thiserror to automatically implement <code>From&lt;std::io::Error&gt; for ConfigError</code>. This means when we call a function that returns <code>Result&lt;_, std::io::Error&gt;</code> (like <code>fs::read_to_string</code>), we can use <code>?</code> and the <code>io::Error</code> will be automatically converted into <code>ConfigError::Io</code>.</p> <p>Notice how every error variant carries a <code>line</code> and (often) a <code>col</code>. This is deliberate. When you tell a user "invalid character", the first question they'll ask is "where?". By embedding position information in the error type itself, every error message can point to the exact location in the file.</p> <p>Compare this with the JSON parser from the last article, where errors just said <code>panic!("Unexpected character")</code> with no location information. The difference is night and day.</p> <p>Now, let's start working on our project.</p> <h2 id="what-is-toml">What is TOML?</h2> <p>TOML stands for <strong>Tom's Obvious Minimal Language</strong>. It's a configuration file format that's designed to be easy for humans to read and write. If you've ever used Rust, you've already seen TOML, every <code>Cargo.toml</code> file is a TOML file.</p> <p>Here's what a TOML file looks like:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># This is a comment</span></span> <span class="giallo-l"><span>host</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;localhost&quot;</span></span> <span class="giallo-l"><span>port</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 8080</span></span> <span class="giallo-l"><span>debug</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>server</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>host</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;localhost&quot;</span></span> <span class="giallo-l"><span>port</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 8080</span></span> <span class="giallo-l"><span>debug</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> true</span></span></code></pre> <p>The subset we'll support:</p> <ul> <li><strong>Key-value pairs</strong>: <code>key = value</code></li> <li><strong>Value types</strong>: strings (<code>"hello"</code>), integers (<code>8080</code>), floats (<code>3.14</code>), booleans (<code>true</code>/<code>false</code>)</li> <li><strong>Tables</strong>: <code>[section_name]</code> groups key-value pairs into sections</li> <li><strong>Comments</strong>: <code>#</code> lines</li> <li><strong>Dotted keys in table headers</strong>: <code>[server.host]</code> creates a nested section</li> </ul> <p>We won't support arrays, inline tables, or array-of-tables. This keeps the scope focused on error handling, which is the point of this article.</p> <h2 id="project-setup">Project Setup</h2> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo new config_parser</span></span> <span class="giallo-l"><span>cd config_parser</span></span></code></pre> <p>Open <code>Cargo.toml</code> and add <code>thiserror</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;">[</span><span>package</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>name</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;config_parser&quot;</span></span> <span class="giallo-l"><span>version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.1.0&quot;</span></span> <span class="giallo-l"><span>edition</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;2024&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>dependencies</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>thiserror</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;2&quot;</span></span></code></pre> <p>Open <code>src/main.rs</code> and delete everything. We'll write it from scratch.</p> <h2 id="step-1-the-error-types">Step 1: The Error Types</h2> <p>Type this into <code>src/main.rs</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span>fs</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Debug</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> thiserror</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Error</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> ConfigError</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;unexpected character at line </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">line</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">, column </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">col</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">: expected </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">expected</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">, found &#39;</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">found</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&#39;&quot;</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> UnexpectedCharacter</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> expected</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> found</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;unterminated string starting at line </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">line</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">, column </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">col</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> UnterminatedString</span><span style="color: #9399B2;"> {</span><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;invalid number at line </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">line</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">, column </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">col</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">: </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">detail</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> InvalidNumber</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> detail</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;expected </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">expected</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;"> at line </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">line</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">, column </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">col</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">, found </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">found</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> ExpectedToken</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> expected</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> found</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;missing value for key &#39;</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">key</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&#39; at line </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">line</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">, column </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">col</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> MissingValue</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> key</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;schema violation at line </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">line</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">: key &#39;</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">key</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&#39; expected type </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">expected</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">, found </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">found</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> SchemaViolation</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> key</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> expected</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> found</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;missing required key &#39;</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">key</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&#39;&quot;</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> MissingRequiredKey</span><span style="color: #9399B2;"> {</span><span> key</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;key &#39;</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">key</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&#39; has value </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">value</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;"> which is outside range </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">min</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;"> to </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">max</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> ValueOutOfRange</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> key</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> value</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> min</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> max</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;unknown key &#39;</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">key</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&#39; at line </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">line</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> UnknownKey</span><span style="color: #9399B2;"> {</span><span> key</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> #</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;io error: </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">0</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Io</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">from</span><span style="color: #9399B2;">]</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">io</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Error</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Let me explain the key parts:</p> <ul> <li><code>#[derive(Debug, thiserror::Error)]</code> - this tells Rust to automatically implement the <code>Debug</code> trait (for <code>{:?}</code> formatting) and the <code>Error</code> trait. The <code>thiserror::Error</code> derive macro generates everything based on the <code>#[error("...")]</code> attributes.</li> <li>Each <code>#[error("...")]</code> attribute is the error message for that variant. The <code>{field}</code> placeholders are replaced with the field values, just like in <code>println!</code>.</li> <li>The <code>Io(#[from] std::io::Error)</code> variant is special. The <code>#[from]</code> attribute tells thiserror to automatically implement <code>From&lt;std::io::Error&gt; for ConfigError</code>. This means when we call a function that returns <code>Result&lt;_, std::io::Error&gt;</code> (like <code>fs::read_to_string</code>), we can use <code>?</code> and the <code>io::Error</code> will be automatically converted into <code>ConfigError::Io</code>.</li> </ul> <p>Notice how every error variant carries a <code>line</code> and (often) a <code>col</code>. When you tell a user "invalid character", the first question they'll ask is "where?". By embedding position information in the error type itself, every error message can point to the exact location in the file.</p> <h2 id="step-2-the-token-type-and-lexer">Step 2: The Token Type and Lexer</h2> <h3 id="spannedtoken">SpannedToken</h3> <p>In the JSON parser, the <code>Token</code> enum only carried the token's kind. In this project, we need each token to know where it came from. So we split the token into two parts: the kind and the location.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Debug</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Clone</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> PartialEq</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> TokenKind</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Equal</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> StringLit</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Integer</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">i64</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Float</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">f64</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Boolean</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">bool</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Comment</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Identifier</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> TableHeader</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Newline</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Debug</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Clone</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> SpannedToken</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> kind</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> TokenKind</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <ul> <li><code>TokenKind</code> is the "what kind of token is this" enum. <code>Equal</code> is <code>=</code>, <code>StringLit("hello")</code> is a quoted string, <code>Integer(42)</code> is a number, <code>Boolean(true)</code> is a boolean, <code>TableHeader("server")</code> is <code>[server]</code>, <code>Newline</code> is a line break.</li> <li><code>SpannedToken</code> bundles the kind with its position in the source file (<code>line</code> and <code>col</code>). When we encounter an error, we can pull the position from the token that caused it.</li> </ul> <p>Compare this with the JSON parser's <code>Token</code> enum. The key difference: our <code>SpannedToken</code> knows where it came from. The JSON parser's tokens had no position information, which is why its error messages were just "unexpected character" with no location.</p> <h3 id="the-lexer">The Lexer</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Lexer</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> input</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">u8</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> pos</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This is very similar to the JSON parser's lexer, but with one crucial addition: <code>line</code> and <code>col</code> tracking. Every time <code>advance()</code> is called, we check if the current byte is a newline. If it is, we increment <code>line</code> and reset <code>col</code> to 1. Otherwise, we just increment <code>col</code>. This gives us exact position information for every byte in the input.</p> <h3 id="the-tokenize-method">The tokenize Method</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> tokenize</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">SpannedToken</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> ConfigError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span></code></pre> <p>Notice the return type: <code>Result&lt;Vec&lt;SpannedToken&gt;, ConfigError&gt;</code>. In the JSON parser, <code>tokenize</code> returned <code>Vec&lt;Token&gt;</code> and just paniced on errors. Here, it returns a <code>Result</code>. If tokenization succeeds, you get <code>Ok(tokens)</code>. If it fails, you get <code>Err(ConfigError)</code> with a specific variant telling you exactly what went wrong and where.</p> <p>The body of <code>tokenize</code> is similar to the JSON parser, but every error case returns <code>Err(ConfigError::...)</code> instead of <code>panic!()</code>. Here's the key difference: in the JSON parser, an unexpected character caused <code>panic!("Unexpected character: {}", c as char)</code>. In our project, it returns <code>Err(ConfigError::UnexpectedCharacter { line, col, expected, found })</code> with the exact position built in.</p> <h3 id="reading-strings">Reading Strings</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> read_string</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">),</span><span style="color: #F9E2AF;font-style: italic;"> ConfigError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> start_line</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>line</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> start_col</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>col</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> result</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> loop</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">UnterminatedString</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span> start_line</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span> start_col</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">((</span><span>result</span><span style="color: #9399B2;">,</span><span> start_line</span><span style="color: #9399B2;">,</span><span> start_col</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #F5C2E7;">\\</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">&#39;);</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #F5C2E7;">\\</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #F5C2E7;">\\</span><span style="color: #9399B2;">&#39;);</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">n</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #F5C2E7;">\n</span><span style="color: #9399B2;">&#39;);</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">t</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #F5C2E7;">\t</span><span style="color: #9399B2;">&#39;);</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">r</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #F5C2E7;">\r</span><span style="color: #9399B2;">&#39;);</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> found</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>b</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> (</span><span>b</span><span style="color: #CBA6F7;"> as</span><span style="color: #F9E2AF;font-style: italic;"> char</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;end of input&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">UnexpectedCharacter</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>line</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>col</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> expected</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;valid escape sequence&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> found</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #CBA6F7;"> as</span><span style="color: #F9E2AF;font-style: italic;"> char</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>In the JSON parser, unterminated strings caused <code>panic!("Unterminated string")</code>. Now they return <code>Err(ConfigError::UnterminatedString { line, col })</code> with the exact position where the string started. The error message will say "unterminated string starting at line 3, column 12" instead of just crashing.</p> <h3 id="reading-numbers">Reading Numbers</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> read_number</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">TokenKind</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">),</span><span style="color: #F9E2AF;font-style: italic;"> ConfigError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> start_line</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>line</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> start_col</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>col</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> has_dot</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">-</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">-</span><span style="color: #9399B2;">&#39;);</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> loop</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #94E2D5;"> @</span><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">0</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;">..=</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">9</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #CBA6F7;"> as</span><span style="color: #F9E2AF;font-style: italic;"> char</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">.</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> has_dot</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">InvalidNumber</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span> start_line</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span> start_col</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> detail</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;multiple decimal points&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> has_dot</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">.</span><span style="color: #9399B2;">&#39;);</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> has_dot</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> value</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f64</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">parse</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>v</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> v</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">InvalidNumber</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span> start_line</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span> start_col</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> detail</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;cannot parse &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39; as float&quot;</span><span style="color: #9399B2;">,</span><span> s</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">((</span><span style="color: #F9E2AF;font-style: italic;">TokenKind</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Float</span><span style="color: #9399B2;">(</span><span>value</span><span style="color: #9399B2;">),</span><span> start_line</span><span style="color: #9399B2;">,</span><span> start_col</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> value</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">parse</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>v</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> v</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">InvalidNumber</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span> start_line</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span> start_col</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> detail</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;cannot parse &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39; as integer&quot;</span><span style="color: #9399B2;">,</span><span> s</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">((</span><span style="color: #F9E2AF;font-style: italic;">TokenKind</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Integer</span><span style="color: #9399B2;">(</span><span>value</span><span style="color: #9399B2;">),</span><span> start_line</span><span style="color: #9399B2;">,</span><span> start_col</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Two important things here. First, multiple decimal points like <code>3.14.159</code> now return <code>Err(ConfigError::InvalidNumber { ... detail: "multiple decimal points" })</code> instead of panicking.</p> <p>Second, the <code>.parse()</code> calls use <code>match</code> instead of <code>.unwrap()</code>. When you call <code>"abc".parse::&lt;i64&gt;()</code>, it returns <code>Result&lt;i64, ParseIntError&gt;</code>. We can't use <code>?</code> here because <code>ParseIntError</code> is not our <code>ConfigError</code> type. Instead, we <code>match</code> on the result and construct our own error with the position information. This is a common pattern: when a library returns an error type that doesn't match yours, you match on their result and create your own error.</p> <h2 id="step-3-the-tomlvalue-type">Step 3: The TomlValue Type</h2> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Debug</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Clone</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> PartialEq</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> String</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Integer</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">i64</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Float</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">f64</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Boolean</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">bool</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Table</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This is similar to the <code>JsonValue</code> enum from the JSON parser, but simpler because TOML doesn't have arrays or null. The <code>Table</code> variant uses a <code>Vec&lt;(String, TomlValue)&gt;</code> just like the JSON parser's <code>Object</code>, each key-value pair is a tuple.</p> <p>To display a <code>TomlValue</code>, we write a standalone function, just like we did for <code>JsonValue</code> in the previous article:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> display</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">value</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">TomlValue</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> value</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">String</span><span style="color: #9399B2;">(</span><span>s</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #F5C2E7;">\&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #F5C2E7;">\&quot;</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> s</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Integer</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> n</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Float</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> n</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Boolean</span><span style="color: #9399B2;">(</span><span>b</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> b</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Table</span><span style="color: #9399B2;">(</span><span>pairs</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> result</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;{&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> first</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>k</span><span style="color: #9399B2;">,</span><span> v</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span> pairs</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> !</span><span>first</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push_str</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;, &quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push_str</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #89B4FA;font-style: italic;">format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> k</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> display</span><span style="color: #9399B2;">(</span><span>v</span><span style="color: #9399B2;">)));</span></span> <span class="giallo-l"><span> first</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">}</span><span style="color: #9399B2;">&#39;);</span></span> <span class="giallo-l"><span> result</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This is exactly the same pattern we used for the JSON parser, a recursive function that pattern matches on each variant and builds a string.</p> <h2 id="step-4-the-parser">Step 4: The Parser</h2> <p>The parser takes a <code>Vec&lt;SpannedToken&gt;</code> and turns it into a <code>TomlValue</code>. It uses the same cursor pattern as the lexer, a current position that advances as tokens are consumed.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Parser</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> tokens</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">SpannedToken</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> pos</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="the-main-parse-method">The Main Parse Method</h3> <p>The parser handles three kinds of top-level items:</p> <ol> <li><strong>Comments and newlines</strong> - skip them</li> <li><strong>Table headers</strong> like <code>[server]</code> - collect all following key-value pairs into a sub-table</li> <li><strong>Key-value pairs</strong> - parse key, equal sign, value</li> </ol> <p>Every place the JSON parser had <code>panic!()</code>, we have <code>Err(ConfigError::...)</code>. Even better, every error includes the line and column from the token. When a key is followed by something other than <code>=</code>, the error says "expected = at line 5, column 12, found Integer" instead of crashing with no context.</p> <p>The <code>?</code> operator is used throughout: <code>self.parse_value()?</code> propagates errors automatically. If <code>parse_value</code> fails, the error bubbles up through <code>parse</code> and up to the caller effortlessly.</p> <h3 id="parse-value">Parse Value</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> parse_value</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">TomlValue</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> ConfigError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> token</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> token</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>t</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> match</span><span style="color: #94E2D5;"> &amp;</span><span>t</span><span style="color: #94E2D5;">.</span><span>kind </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TokenKind</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">StringLit</span><span style="color: #9399B2;">(</span><span>s</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> val</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">String</span><span style="color: #9399B2;">(</span><span>s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>val</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TokenKind</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Integer</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> val</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Integer</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">*</span><span>n</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>val</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TokenKind</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Float</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> val</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Float</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">*</span><span>n</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>val</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TokenKind</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Boolean</span><span style="color: #9399B2;">(</span><span>b</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> val</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Boolean</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">*</span><span>b</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>val</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">ExpectedToken</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span> t</span><span style="color: #94E2D5;">.</span><span>line</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span> t</span><span style="color: #94E2D5;">.</span><span>col</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> expected</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;value (string, integer, float, or boolean)&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> found</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">:?</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> t</span><span style="color: #94E2D5;">.</span><span>kind</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">ExpectedToken</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> expected</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;value&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> found</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;end of input&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Clean and straightforward. If we have a token that's a valid value type, we return it. If not, we return a specific error saying what we expected and what we found instead.</p> <h2 id="step-5-the-schema">Step 5: The Schema</h2> <p>The schema defines what keys are expected in the config file, what types they should be, and whether they're required. The schema is itself a TOML file, parsed by our own parser.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> FieldType</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Integer</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Float</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Boolean</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> FieldSchema</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> field_type</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> FieldType</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> required</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> bool</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> default</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">TomlValue</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> min</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i64</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> max</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i64</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> FieldType</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> from_str</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">s</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">FieldType</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> s</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;string&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">FieldType</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;integer&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">FieldType</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Integer</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;float&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">FieldType</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Float</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;boolean&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">FieldType</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Boolean</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> name</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt; &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">static</span><span style="color: #F9E2AF;font-style: italic;"> str</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> FieldType</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;string&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> FieldType</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Integer</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;integer&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> FieldType</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Float</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;float&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> FieldType</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Boolean</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;boolean&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">derive</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Debug</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Clone</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> FieldSchema</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> field_type</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> FieldType</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> required</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> bool</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> default</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">TomlValue</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> min</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i64</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> max</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i64</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">type</span><span style="color: #F9E2AF;font-style: italic;"> Schema</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> FieldSchema</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">;</span></span></code></pre> <p><code>FieldType</code> - the expected type for a config key. <code>FieldSchema</code> - the full validation spec for a single key. <code>required</code> - if true, the key must be present (unless it has a default). <code>default</code> - a value to use if the key is missing. <code>min</code> and <code>max</code> - for integers, the valid range. <code>Schema</code> - a list of key names and their validation rules.</p> <p><code>FieldType::from_str</code> converts a string like <code>"integer"</code> into a <code>FieldType</code> variant (or <code>None</code> if the string isn't a valid type name). <code>FieldType::name</code> converts a variant back into a string for error messages.</p> <p>The schema TOML file looks like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;">[</span><span>server.host</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>type</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;string&quot;</span></span> <span class="giallo-l"><span>required</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>server.port</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>type</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;integer&quot;</span></span> <span class="giallo-l"><span>min</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 1</span></span> <span class="giallo-l"><span>max</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 65535</span></span> <span class="giallo-l"><span>required</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> true</span></span></code></pre> <p>When our parser processes this, <code>[server.host]</code> becomes a <code>TableHeader("server.host")</code>, and the key-value pairs inside it become entries in a sub-table. The <code>parse_schema</code> function walks this sub-table and extracts the validation rules:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> parse_schema</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">value</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">TomlValue</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Schema</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> ConfigError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> schema</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> table</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> value</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Table</span><span style="color: #9399B2;">(</span><span>pairs</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> pairs</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">UnexpectedCharacter</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> col</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> expected</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;table&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> found</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;non-table value&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>key</span><span style="color: #9399B2;">,</span><span> val</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span> table</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> inner</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> val</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Table</span><span style="color: #9399B2;">(</span><span>pairs</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> pairs</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> continue</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> field_type</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> FieldType</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> required</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> default_val</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">TomlValue</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> min_val</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i64</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> max_val</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">i64</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>field_name</span><span style="color: #9399B2;">,</span><span> field_val</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span> inner</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> field_name</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">as_str</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;type&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> type_str</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> field_val</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">String</span><span style="color: #9399B2;">(</span><span>s</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> ft</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> FieldType</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_str</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>type_str</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> ft</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>t</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> field_type</span><span style="color: #94E2D5;"> =</span><span> t</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">SchemaViolation</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> key</span><span style="color: #94E2D5;">:</span><span> key</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> expected</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;valid type (string, integer, float, boolean)&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> found</span><span style="color: #94E2D5;">:</span><span> type_str</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;required&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> required</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> field_val</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Boolean</span><span style="color: #9399B2;">(</span><span>b</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt; *</span><span>b</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;default&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> default_val</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>field_val</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;min&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> min_val</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> field_val</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Integer</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">*</span><span>n</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;max&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> max_val</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> field_val</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Integer</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">*</span><span>n</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {}</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> schema</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">((</span></span> <span class="giallo-l"><span> key</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> FieldSchema</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> field_type</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> required</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> default</span><span style="color: #94E2D5;">:</span><span> default_val</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> min</span><span style="color: #94E2D5;">:</span><span> min_val</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> max</span><span style="color: #94E2D5;">:</span><span> max_val</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>schema</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This function takes the parsed schema <code>TomlValue</code> (which is a <code>Table</code> of sub-tables) and walks each entry. For each key like <code>server.port</code>, it reads the <code>type</code>, <code>required</code>, <code>default</code>, <code>min</code>, and <code>max</code> fields from the sub-table. If the <code>type</code> string isn't one of our known types, it returns a <code>SchemaViolation</code> error.</p> <p>The <code>flatten_table</code> helper is also needed, it converts the nested <code>TomlValue::Table</code> into a flat list of dotted keys like <code>server.host</code>, <code>server.port</code>, etc.:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> flatten_table</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">table</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">TomlValue</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> prefix</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> pairs</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> table</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Table</span><span style="color: #9399B2;">(</span><span>pairs</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> pairs</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> return</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[],</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> result</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>key</span><span style="color: #9399B2;">,</span><span> value</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span> pairs</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> full_key</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if</span><span> prefix</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_empty</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span> key</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">.</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> prefix</span><span style="color: #9399B2;">,</span><span> key</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> value</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Table</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> nested</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> flatten_table</span><span style="color: #9399B2;">(</span><span>value</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>full_key</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> item</span><span style="color: #CBA6F7;"> in</span><span> nested</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>item</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">((</span><span>full_key</span><span style="color: #9399B2;">,</span><span> value</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">()));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> result</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>And a small <code>toml_type_name</code> helper that maps a <code>TomlValue</code> variant to a human-readable type name, used in schema violation error messages:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> toml_type_name</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">value</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">TomlValue</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt; &amp;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">static</span><span style="color: #F9E2AF;font-style: italic;"> str</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> value</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">String</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;string&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Integer</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;integer&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Float</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;float&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Boolean</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;boolean&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Table</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;table&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="step-6-schema-validation">Step 6: Schema Validation</h2> <p>The <code>validate</code> function takes a parsed config, a schema, and the original source text. It checks every key in the config against the schema and collects all errors.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> validate</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">config</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">TomlValue</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> schema</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">Schema</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> source</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(),</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">ConfigError</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> errors</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> flat_config</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> flatten_table</span><span style="color: #9399B2;">(</span><span>config</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>key</span><span style="color: #9399B2;">,</span><span> field</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span> schema</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> found_value</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">TomlValue</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>k</span><span style="color: #9399B2;">,</span><span> v</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>flat_config</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> k</span><span style="color: #94E2D5;"> ==</span><span> key</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> found_value</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>v</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> found_value</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> field</span><span style="color: #94E2D5;">.</span><span>required </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #94E2D5;"> &amp;</span><span>field</span><span style="color: #94E2D5;">.</span><span>default </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {}</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> errors</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">MissingRequiredKey</span><span style="color: #9399B2;"> {</span><span> key</span><span style="color: #94E2D5;">:</span><span> key</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">() });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>value</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> type_matches</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #9399B2;"> (</span><span style="color: #94E2D5;">&amp;</span><span>field</span><span style="color: #94E2D5;">.</span><span>field_type</span><span style="color: #9399B2;">,</span><span> value</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">FieldType</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">String</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">))</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">FieldType</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Integer</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Integer</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">))</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">FieldType</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Float</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Float</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">))</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">FieldType</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Float</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Integer</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">))</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">FieldType</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Boolean</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Boolean</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">))</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> !</span><span>type_matches</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> line</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> find_line_for_key</span><span style="color: #9399B2;">(</span><span>source</span><span style="color: #9399B2;">,</span><span> key</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> errors</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">SchemaViolation</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> line</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> key</span><span style="color: #94E2D5;">:</span><span> key</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> expected</span><span style="color: #94E2D5;">:</span><span> field</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">field_type</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">name</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> found</span><span style="color: #94E2D5;">:</span><span style="color: #89B4FA;font-style: italic;"> toml_type_name</span><span style="color: #9399B2;">(</span><span>value</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Integer</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #9399B2;">),</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>min</span><span style="color: #9399B2;">))</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span>value</span><span style="color: #9399B2;">,</span><span> field</span><span style="color: #94E2D5;">.</span><span>min</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> *</span><span>n</span><span style="color: #94E2D5;"> &lt;</span><span> min</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> errors</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">ValueOutOfRange</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> key</span><span style="color: #94E2D5;">:</span><span> key</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> value</span><span style="color: #94E2D5;">:</span><span> n</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> min</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> max</span><span style="color: #94E2D5;">:</span><span> field</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">max</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap_or</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">TomlValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Integer</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #9399B2;">),</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>max</span><span style="color: #9399B2;">))</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span>value</span><span style="color: #9399B2;">,</span><span> field</span><span style="color: #94E2D5;">.</span><span>max</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> *</span><span>n</span><span style="color: #94E2D5;"> &gt;</span><span> max</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> errors</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">ValueOutOfRange</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> key</span><span style="color: #94E2D5;">:</span><span> key</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> value</span><span style="color: #94E2D5;">:</span><span> n</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> min</span><span style="color: #94E2D5;">:</span><span> field</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">min</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap_or</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> max</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>key</span><span style="color: #9399B2;">,</span><span> _</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>flat_config</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> is_known</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>k</span><span style="color: #9399B2;">,</span><span> _</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span> schema</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> k</span><span style="color: #94E2D5;"> ==</span><span> key</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> is_known</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> !</span><span>is_known</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> line</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> find_line_for_key</span><span style="color: #9399B2;">(</span><span>source</span><span style="color: #9399B2;">,</span><span> key</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> errors</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">UnknownKey</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> key</span><span style="color: #94E2D5;">:</span><span> key</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> line</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> });</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> errors</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_empty</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(())</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>errors</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>validate</code> returns <code>Result&lt;(), Vec&lt;ConfigError&gt;&gt;</code>, not <code>Result&lt;(), ConfigError&gt;</code>. It collects <strong>all</strong> errors, not just the first one. This is important for a config validator — you want to see everything that's wrong, not fix one error, re-run, fix another, re-run, etc.</p> <p>The <code>flatten_table</code> helper converts the nested <code>TomlValue::Table</code> into a flat list of dotted keys like <code>server.host</code>, <code>server.port</code>, etc. This makes it easy to match against the schema keys.</p> <p>The <code>find_line_for_key</code> helper searches the original TOML source text for a key and returns its line number. It strips the section prefix from dotted keys (turning <code>server.host</code> into just <code>host</code>) and scans for lines matching <code>key =</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> find_line_for_key</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">source</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> target_key</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> short_key</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if</span><span> target_key</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">contains</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">.</span><span style="color: #9399B2;">&#39;) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> parts</span><span style="color: #94E2D5;"> =</span><span> target_key</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">rsplit</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">.</span><span style="color: #9399B2;">&#39;);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> parts</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">next</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>k</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> k</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span> target_key</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> target_key</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>i</span><span style="color: #9399B2;">,</span><span> line</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span> source</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">lines</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">enumerate</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> trimmed</span><span style="color: #94E2D5;"> =</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">trim</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> trimmed</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">starts_with</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">#</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> ||</span><span> trimmed</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">starts_with</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">[</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> ||</span><span> trimmed</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_empty</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> continue</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>eq_pos</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> trimmed</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">find</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">=</span><span style="color: #9399B2;">&#39;) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> key_part</span><span style="color: #94E2D5;"> =</span><span> trimmed</span><span style="color: #9399B2;">[</span><span style="color: #94E2D5;">..</span><span>eq_pos</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">trim</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> key_part</span><span style="color: #94E2D5;"> ==</span><span> short_key</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span> i</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 0</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>It skips comments, section headers, and empty lines, then looks for lines where the part before <code>=</code> matches the key. If it can't find the key, it returns <code>0</code> (which <code>format_error</code> treats as "no line information available").</p> <h2 id="step-7-displaying-errors">Step 7: Displaying Errors</h2> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> format_error</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">err</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">ConfigError</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> source</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> line_num</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> err</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">UnexpectedCharacter</span><span style="color: #9399B2;"> {</span><span> line</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> ..</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> =&gt; *</span><span>line</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">UnterminatedString</span><span style="color: #9399B2;"> {</span><span> line</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> ..</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> =&gt; *</span><span>line</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">InvalidNumber</span><span style="color: #9399B2;"> {</span><span> line</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> ..</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> =&gt; *</span><span>line</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">ExpectedToken</span><span style="color: #9399B2;"> {</span><span> line</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> ..</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> =&gt; *</span><span>line</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">MissingValue</span><span style="color: #9399B2;"> {</span><span> line</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> ..</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> =&gt; *</span><span>line</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">SchemaViolation</span><span style="color: #9399B2;"> {</span><span> line</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> ..</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> =&gt; *</span><span>line</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">UnknownKey</span><span style="color: #9399B2;"> {</span><span> line</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> ..</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> =&gt; *</span><span>line</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> line_num</span><span style="color: #94E2D5;"> ==</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Error: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> err</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> lines</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> source</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">lines</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> line_content</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> lines</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">get</span><span style="color: #9399B2;">(</span><span>line_num</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>l</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt; *</span><span>l</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;Error: </span><span style="color: #9399B2;">{}</span><span style="color: #F5C2E7;">\n</span><span style="color: #A6E3A1;"> |</span><span style="color: #F5C2E7;">\n</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">:&gt;2</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;"> | </span><span style="color: #9399B2;">{}</span><span style="color: #F5C2E7;">\n</span><span style="color: #A6E3A1;"> |&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> err</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> line_num</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> line_content</span></span> <span class="giallo-l"><span style="color: #9399B2;"> )</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This function takes an error and the original source text, finds the offending line, and formats it like:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>Error: schema violation at line 3: key &#39;server.host&#39; expected type string, found integer</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> 3 | host = 1234</span></span> <span class="giallo-l"><span> |</span></span></code></pre> <p>The <code>match err { ... }</code> extracts the line number from whichever error variant it is. All the variants that carry a <code>line</code> field get their line number extracted. Variants like <code>MissingRequiredKey</code> that don't have a specific line get <code>0</code>, in which case we just print the error message without a source line.</p> <h2 id="step-8-main-function-and-demo">Step 8: Main Function and Demo</h2> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> run</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">config_path</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> schema_path</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(),</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">ConfigError</span><span style="color: #89DCEB;">&gt;&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> config_source</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #F9E2AF;"> fs</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">read_to_string</span><span style="color: #9399B2;">(</span><span>config_path</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>s</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> s</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">vec!</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)]),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> schema_source</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #F9E2AF;"> fs</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">read_to_string</span><span style="color: #9399B2;">(</span><span>schema_path</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>s</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> s</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">vec!</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">ConfigError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)]),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> config_lexer</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Lexer</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>config_source</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> config_tokens</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> config_lexer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">tokenize</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>tokens</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> tokens</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">vec!</span><span style="color: #9399B2;">[</span><span>e</span><span style="color: #9399B2;">]),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> config_parser</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Parser</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>config_tokens</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> config_value</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> config_parser</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">parse</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>v</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> v</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">vec!</span><span style="color: #9399B2;">[</span><span>e</span><span style="color: #9399B2;">]),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> schema_lexer</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Lexer</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>schema_source</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> schema_tokens</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> schema_lexer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">tokenize</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>tokens</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> tokens</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">vec!</span><span style="color: #9399B2;">[</span><span>e</span><span style="color: #9399B2;">]),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> schema_parser</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Parser</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>schema_tokens</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> schema_value</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> schema_parser</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">parse</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>v</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> v</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">vec!</span><span style="color: #9399B2;">[</span><span>e</span><span style="color: #9399B2;">]),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> schema</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #89B4FA;font-style: italic;"> parse_schema</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>schema_value</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>s</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> s</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">vec!</span><span style="color: #9399B2;">[</span><span>e</span><span style="color: #9399B2;">]),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> validate</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>config_value</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>schema</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>config_source</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Config is valid!&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Parsed config:&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>key</span><span style="color: #9399B2;">,</span><span> value</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span style="color: #89B4FA;font-style: italic;"> flatten_table</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>config_value</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;&quot;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;"> {}</span><span style="color: #A6E3A1;"> = </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> key</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> display</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>value</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(())</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This is the beauty of proper error handling. Look at <code>run()</code>: it's a pipeline of operations, each of which can fail. Each <code>match</code> on a <code>Result</code> handles the error case explicitly. For cases where we want to convert a single error into a <code>Vec</code> of errors, we wrap it with <code>vec![e]</code>.</p> <p>Notice we use <code>match</code> here instead of <code>?</code>. That's because <code>run</code> returns <code>Result&lt;(), Vec&lt;ConfigError&gt;&gt;</code>, but most of the inner calls return <code>Result&lt;_, ConfigError&gt;</code> (a single error, not a Vec). The <code>?</code> operator only works when the error types match, so we explicitly match and wrap single errors into a Vec where needed.</p> <p>The <code>ConfigError::from(e)</code> on the <code>fs::read_to_string</code> error lines works because we defined <code>Io(#[from] std::io::Error)</code> in our error enum. The <code>#[from]</code> attribute generated a <code>From&lt;std::io::Error&gt; for ConfigError</code> implementation, so <code>ConfigError::from(e)</code> converts an <code>io::Error</code> into our <code>ConfigError::Io</code> variant.</p> <p>The <code>main</code> function reads the file paths from command-line arguments (or defaults to the example files), calls <code>run</code>, and handles any errors:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> args</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">env</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">args</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span style="color: #9399B2;"> (</span><span>config_path</span><span style="color: #9399B2;">,</span><span> schema_path</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if</span><span> args</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> &gt;=</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span>args</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(),</span><span> args</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">())</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;examples/valid_config.toml&quot;</span><span style="color: #9399B2;">),</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;examples/schema.toml&quot;</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #89B4FA;font-style: italic;"> run</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>config_path</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>schema_path</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(())</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {}</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>errors</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> source</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #F9E2AF;"> fs</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">read_to_string</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>config_path</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>s</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> s</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> err</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>errors</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> eprintln!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> format_error</span><span style="color: #9399B2;">(</span><span>err</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>source</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> eprintln!</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">process</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">exit</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>If <code>run</code> returns <code>Ok(())</code>, we're done. If it returns <code>Err(errors)</code>, we load the source text (so we can point to specific lines), format each error with <code>format_error</code>, print them to stderr, and exit with code 1.</p> <h3 id="running-with-a-valid-config">Running with a Valid Config</h3> <p>Create <code>examples/valid_config.toml</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Server configuration</span></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>server</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>host</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;localhost&quot;</span></span> <span class="giallo-l"><span>port</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 8080</span></span> <span class="giallo-l"><span>debug</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>database</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>url</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;postgres://localhost/mydb&quot;</span></span> <span class="giallo-l"><span>max_connections</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 10</span></span></code></pre> <p>Run it:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run -- examples/valid_config.toml examples/schema.toml</span></span></code></pre> <p>Output:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Config</span><span style="color: #A6E3A1;"> is valid!</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Parsed</span><span style="color: #A6E3A1;"> config:</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> server.host</span><span style="color: #A6E3A1;"> = &quot;localhost&quot;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> server.port</span><span style="color: #A6E3A1;"> =</span><span style="color: #FAB387;"> 8080</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> server.debug</span><span style="color: #A6E3A1;"> =</span><span style="color: #FAB387;"> true</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> database.url</span><span style="color: #A6E3A1;"> = &quot;postgres://localhost/mydb&quot;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> database.max_connections</span><span style="color: #A6E3A1;"> =</span><span style="color: #FAB387;"> 10</span></span></code></pre><h3 id="running-with-an-invalid-config">Running with an Invalid Config</h3> <p>Create <code>examples/invalid_config.toml</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;"># Config with multiple errors</span></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>server</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>host</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 1234</span></span> <span class="giallo-l"><span>port</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 99999</span></span> <span class="giallo-l"><span>debug</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;yes&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>database</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>url</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;postgres://localhost/mydb&quot;</span></span> <span class="giallo-l"><span>max_connections</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 200</span></span></code></pre> <p>Run it:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run -- examples/invalid_config.toml examples/schema.toml</span></span></code></pre> <p>Output:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>Error: schema violation at line 3: key &#39;server.host&#39; expected type string, found integer</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> 3 | host = 1234</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Error: key &#39;server.port&#39; has value 99999 which is outside range 1 to 65535</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Error: schema violation at line 5: key &#39;server.debug&#39; expected type boolean, found string</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> 5 | debug = &quot;yes&quot;</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Error: key &#39;database.max_connections&#39; has value 200 which is outside range 1 to 100</span></span></code></pre> <p>All four errors are reported at once. No panicking, no crashing, no vague messages. Every error tells you exactly what's wrong and where.</p> <h2 id="conclusion">Conclusion</h2> <p>In this post, we replaced every <code>panic!</code> and <code>unwrap</code> with proper <code>Result</code> based error handling. We defined a custom <code>ConfigError</code> enum with rich error variants carrying line numbers and context. We used <code>thiserror</code> to avoid writing boilerplate code. We used the <code>?</code> operator to propagate errors effortlessly. And we built a validator that collects <strong>all</strong> errors and displays them with source lines, not just the first one.</p> <p>In the next article, we'll learn about generics, traits, and lifetimes and build a <strong>Generic LRU Cache</strong>. See you soon.</p> 2026-04-29T00:00:00+00:00 2026-04-29T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/learn-rust-structs-enums-pattern-matching-by-building-a-json-parser/ <p>In this post, we are going to learn about structs, enums and pattern matching in Rust. Once we cover all these concepts, we will build a <strong>JSON Parser in Rust from scratch</strong>. I'm really excited about this project. Let's start.</p> <p>Get the source code from <a rel="external" href="https://github.com/MrSheerluck/json-parser-in-rust">here</a></p> <h2 id="structs-in-rust">Structs in Rust</h2> <h3 id="what-a-struct-is">What a Struct Is?</h3> <p>A struct is a way to define a new type of grouping related pieces of data together under a single name. Each piece of data inside a struct is called a <strong>field</strong>, and every field has a name and a type.</p> <p>Let's say you are building a product and you want to keep track of all the data for a user like name, age, etc. This is where you can use a struct to group together all the related data for a <strong>User</strong> type. Don't worry if you don't understand this, once we start working on the project this will be clear.</p> <h3 id="defining-a-struct-in-rust">Defining a Struct in Rust</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> age</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> u32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> active</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> bool</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This defines a new type called <code>User</code>. It has three fields. The definition itself doesn't create any data, its just a definition or schema of the type like what kind of data this struct can hold. No memory is allocated at this point.</p> <p>There are some rules to define a struct:</p> <ul> <li>The struct name uses <code>PascalCase</code> by convention</li> <li>Each field is <code>name: Type</code></li> <li>Fields are separated by commas</li> <li>A trailing comma after the last field is allowed and idiomatic in Rust</li> </ul> <h3 id="creating-an-instance-of-a-struct-in-rust">Creating an Instance of a Struct in Rust</h3> <p>To actually create a value of type <code>User</code>, you create an instance:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> user</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;alice&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> age</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 30</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> active</span><span style="color: #94E2D5;">:</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">};</span></span></code></pre> <p>This is called a <strong>struct literal</strong>. You provide values for every field by name. The order you write the fields doesn't matter, Rust matches them by bame and not by position. But remember that you must provide all the fields. If you skip any field then it'll show a compile error.</p> <h3 id="accessing-fields">Accessing Fields</h3> <p>You access fields with dot notation:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> user</span><span style="color: #94E2D5;">.</span><span>name</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // alice</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> user</span><span style="color: #94E2D5;">.</span><span>age</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // 30</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> user</span><span style="color: #94E2D5;">.</span><span>active</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // true</span></span></code></pre><h3 id="mutability">Mutability</h3> <p>Rust's mutability applies to the entire struct instance. You can't make just once field mutable. If you want to modify any field, the whole binding must be <code>mut</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> user</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;alice&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> age</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 30</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> active</span><span style="color: #94E2D5;">:</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">};</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>user</span><span style="color: #94E2D5;">.</span><span>age </span><span style="color: #94E2D5;">=</span><span style="color: #FAB387;"> 31</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // this is fine as user is a mutable struct</span></span> <span class="giallo-l"><span>user</span><span style="color: #94E2D5;">.</span><span>active </span><span style="color: #94E2D5;">=</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;font-style: italic;"> // this is fine too for the same reason</span></span></code></pre> <p>If <code>user</code> is not <code>mut</code>, no field can be modified. Let's not go to why this is the case, I might explain it at some point later in this series.</p> <h3 id="field-shorthand">Field Shorthand</h3> <p>When you're creating a struct instance and you have a local variable with the same name as a field, you don't need to repeat yourself:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> build_user</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">name</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> age</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> u32</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> name</span><span style="color: #9399B2;">,</span><span style="color: #9399B2;font-style: italic;"> // shorthand for name: name</span></span> <span class="giallo-l"><span> age</span><span style="color: #9399B2;">,</span><span style="color: #9399B2;font-style: italic;"> // shorthand for age: age</span></span> <span class="giallo-l"><span> active</span><span style="color: #94E2D5;">:</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This only works when the variable name and the field name are identical.</p> <h3 id="struct-update-syntax">Struct Update Syntax</h3> <p>If you want to create a new instance of a struct that's mostly same to an existing one, but with some fields changed, you can use struct update syntax:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> user2</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> age</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 25</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> ...</span><span>user</span></span> <span class="giallo-l"><span style="color: #9399B2;">};</span></span></code></pre> <p>The <code>...user</code> part means "fill in all remaining fields from <code>user</code>". Fields you specify explicitly take precedence. Fields not mentioned are copied or moved from <code>user</code>.</p> <blockquote> <p>There's an important ownership nuance here: if any field being moved out of user is a non-Copy type (like <code>String</code>), then <code>user</code> is partially moved and you can no longer use it as a whole after this. You can still use fields that were not moved (like <code>age</code> and <code>active</code>, which are Copy types), but <code>user.name</code> would be moved into <code>user2.name</code>.</p> </blockquote> <h3 id="impl-blocks-giving-a-struct-behaviour"><code>impl</code> Blocks (Giving a Struct Behaviour)</h3> <p>A struct definition only describes data but to give a struct behaviour that means functions that operate on that data, you write an <code>impl</code> block:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // methods and assocuated functions go here</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>impl</code> stands for "implementation". Everything inside an <code>impl User</code> block belongs to the <code>User</code> type. You can have multiple <code>impl</code> blocks for the same type and Rust will them as one, though conventionally you group everything into one block.</p> <h3 id="methods-functions-with-self">Methods (Functions with <code>self</code>)</h3> <p>A <code>method</code> is a function defined inside an <code>impl</code> block that takes <code>self</code> as its first parameter. <code>self</code> refers to the specific instance the method is being called on. There are three forms of <code>self</code> and each of them has a distinct meaning:</p> <h4 id="self-immutable-borrow-of-an-instance"><code>&amp;self</code> Immutable Borrow of an Instance</h4> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> greeting</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Hello, my name is </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> and I am </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> years old&quot;</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>name</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>age</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>&amp;self</code> is shorthand for <code>self: &amp;User</code>. The method borrows the instance immutably. It can read fields but cannot modify them. The caller retains the ownership of the instance after the call.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> user</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;alice&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> age</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 30</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> active</span><span style="color: #94E2D5;">:</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">};</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> user</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">greeting</span><span style="color: #9399B2;">());</span><span style="color: #9399B2;font-style: italic;"> // Hello, my name is alice and I am 30 year old</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// user is still valid here</span></span></code></pre> <p>This is by far the most common form. Use it whenever a method only needs to read data.</p> <h4 id="mut-self-mutable-borrow-of-an-instance"><code>&amp;mut self</code> Mutable Borrow of an Instance</h4> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> deactivate</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>active </span><span style="color: #94E2D5;">=</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> have_birthday</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>age </span><span style="color: #94E2D5;">+=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>&amp;mut self</code> is shorthand for <code>self: &amp;mut User</code>. The method borrows the instance mutably. It can read and modify fields. The caller must have a <code>mut</code> binding and the normal borrow rules apply (no other borrows of the instance can exist while this method runs).</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> user</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;alice&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> age</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 30</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> active</span><span style="color: #94E2D5;">:</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">};</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>user</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">have_birthday</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> user</span><span style="color: #94E2D5;">.</span><span>age</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // 31</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>user</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">decativate</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> user</span><span style="color: #94E2D5;">.</span><span>active</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // false</span></span></code></pre><h4 id="self-taking-ownership-of-the-instance"><code>self</code> Taking Ownership of the Instance</h4> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> into_name</span><span style="color: #9399B2;">(</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>name </span><span style="color: #9399B2;font-style: italic;">// self is consumed, we return just the name</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>self</code> (no reference) means the method takes the ownership of the instance. After calling it, the original binding is gone, it is moved into the method.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> user</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;alice&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> age</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 30</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> active</span><span style="color: #94E2D5;">:</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">};</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> name</span><span style="color: #94E2D5;"> =</span><span> user</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into_name</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// user is no longer valid here, it was moved to that method</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> name</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // alice</span></span></code></pre> <p>This is used when a method is meant to consume the instance and produce something else from it may be a transformation or conversion. It's less common than the borrow forms.</p> <h3 id="associated-functions">Associated Functions</h3> <p>An associated function is defined inside an <code>impl</code> block but does not take self in any form. It belongs to the type, not to any specific instance.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> new</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">name</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> age</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> u32</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> name</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> age</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> active</span><span style="color: #94E2D5;">:</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>You call it with <code>::</code> syntax on the type name, not on an instance:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> user</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;alice&quot;</span><span style="color: #9399B2;">),</span><span style="color: #FAB387;"> 30</span><span style="color: #9399B2;">);</span></span></code></pre> <p>This is the conventional way to write constructors in Rust. Rust has no special constructor syntax. <code>new</code> is just a naming convention for an associated function that produces an instance. You can name it anything.</p> <p>Another common pattern: associated functions that act as alternative constructors with specific defaults or validation logic:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> guest</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;guest&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> age</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> active</span><span style="color: #94E2D5;">:</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> g</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> User</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">guest</span><span style="color: #9399B2;">();</span></span></code></pre><h2 id="enums-in-rust">Enums in Rust</h2> <h3 id="what-an-enum-is">What an Enum Is?</h3> <p>An enum (short for enumeration) is a type that defines a fixed set of possible variants. A value of an enum type is exactly one of those variants at any given time. You've already used enums without thinking about it. <code>Option&lt;T&gt;</code> and <code>Result&lt;T, E&gt;</code> are both enums defined in Rust's standard library. But before we get to the advanced forms, we need to build up from the ground up.</p> <h3 id="basic-enums">Basic enums</h3> <p>The simplest form of an enum is a set of named variants that carry no data:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> North</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> South</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> East</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> West</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This defines a new type called <code>Direction</code>. A value of type <code>Direction</code> is one of exactly those four things. You create a value using <code>::</code> syntax:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> d</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">North</span><span style="color: #9399B2;">;</span></span></code></pre> <p>Each variant is namespaced under the enum name. You can't just write <code>North</code>, you need to write it like <code>Direction::North</code>. This prevents name collisions and makes code immediately readable.</p> <p>At the memory level, a basic enum with no data is stored as an integer. Rust chooses the smallest integer type that fits all variants. With four variants, it fits in a <code>u8</code>.</p> <h3 id="data-carrying-variants">Data Carrying Variants</h3> <p>This is where Rust enums become genuinely powerful and unlike enums in most other languages. Each variant of an enum can carry its own data, and each variant can carry different data with a different shape:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Circle</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">f64</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Rectangle</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">f64</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> f64</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Triangle</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">f64</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> f64</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> f64</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>Circle</code> carries one <code>f64</code> (the radius). <code>Rectangle</code> carries two <code>f64</code>s (width and height). <code>Triangle</code> carries three <code>f64</code>s (the three sides). These are called <strong>tuple variants</strong> because the data is positional just like a tuple.</p> <p>You can create them like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> c</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Circle</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> r</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Rectangle</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">4</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 6</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> t</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Triangle</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 4</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">);</span></span></code></pre> <p>Variants can also carry named fields, like a struct:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Circle</span><span style="color: #9399B2;">{</span><span> radius</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f64</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rectangle</span><span style="color: #9399B2;">{</span><span> width</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 64</span><span style="color: #9399B2;">,</span><span> height</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f64</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Triangle</span><span style="color: #9399B2;">{</span><span> a</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f64</span><span style="color: #9399B2;">,</span><span> b</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f64</span><span style="color: #9399B2;">,</span><span> c</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;">f64</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> r</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Rectangle</span><span style="color: #9399B2;">{</span><span> width</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 4</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span> height</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 6</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;"> };</span></span></code></pre> <p>These are called <strong>struct variants</strong>. Named fields are more verbose but more readable, especially when a variant carries several values that could be confused with each other.</p> <h3 id="what-an-enum-value-actually-looks-like-in-memory">What an Enum Value Actually Looks Like in Memory</h3> <p>This is important to understand. An enum value in memory is laid out as a <strong>tagged union</strong>. It consists of:</p> <ol> <li>A <strong>tag</strong> (the discriminant) - an integer identifying which variant this value is</li> <li><strong>Space for the largest variant's data</strong> - all variants share the same memory region, sized to fit whichever variant is biggest So if you have:</li> </ol> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Message</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Quit</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Move</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Write</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Color</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">u8</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> u8</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> u8</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The size of <code>Message</code> value in memory is the size of the largest variant (<code>Write(String)</code>) is the biggest here since <code>String</code> is 24 bytes on 64-bit machines plus the tag. Every <code>Message</code> value occupies the same amount of space, regardless of which variant it actually is. If it's <code>Quit</code>, most of those bytes are unused but they are still there, reserved.</p> <h3 id="enums-with-mixed-variant-shapes">Enums with Mixed Variant Shapes</h3> <p>Nothing forces all variants to have the same kind of data, you can feely mix:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Event</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> KeyPress</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">char</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> MouseClick</span><span style="color: #9399B2;">{</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> u32</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> u32</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Resize</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">u32</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> u32</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Quit</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>KeyPress</code> is a tuple variant with one value. <code>MouseClick</code> is a struct variant with named fields. <code>Resize</code> is a tuple variant with two values. <code>Quit</code> has no data. This is completely valid.</p> <h3 id="enums-in-impl-blocks">Enums in <code>impl</code> Blocks</h3> <p>Just like structs, enums can have <code>impl</code> blocks with methods:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> North</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> South</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> East</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> West</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> opposite</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">North</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">South</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">South</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">North</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">East</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">West</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">West</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">East</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> is_vertical</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> bool</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">North</span><span style="color: #94E2D5;"> |</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">South</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">East</span><span style="color: #94E2D5;"> |</span><span style="color: #F9E2AF;font-style: italic;"> Direction</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">West</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The <code>match</code> expression here is the primary tool for working with enum values. We'll cover it in depth in the next section, but notice already: you can't access the "contents" of an enum variant without pattern matching. There are no fields you can dot into directly. The match forces you to say "if it's this variant, do this; if it's that variant, do that."</p> <h3 id="recursive-enums-and-box-t">Recursive Enums and <code>Box&lt;T&gt;</code></h3> <p>Here's where enums become essential for building data structures like parsers, ASTs and trees. Suppose you want to define a type that represents a simple expression like a number, or an addition of two expressions:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Expr</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Number</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">f64</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Add</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Expr</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Expr</span><span style="color: #9399B2;">),</span><span style="color: #9399B2;font-style: italic;"> // ERROR: recursive type has infinite size</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This won't compile because the compiler needs to know the size of <code>Expr</code> at compile time. But <code>Expr::Add</code> contains two <code>Expr</code> values, each of which might be <code>Add</code> themselves which contain more <code>Expr</code> values. The could go on till infinity.</p> <p>The fix is <code>Box&lt;T&gt;</code>. A <code>Box&lt;T&gt;</code> is a heap allocated values basically its a pointer and a pointer always has a fixed, known size (8 bytes on 64-bit).So instead of storing the <code>Expr</code> directly inside <code>Add</code>, you store a pointer to it on the heap:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Expr</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Number</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">f64</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Add</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Box</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Expr</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Box</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Expr</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now the compiler knows the size of <code>Expr</code>: its the size of the largest variant. <code>Number(f64)</code> is 8 bytes and <code>Add(Box&lt;Expr&gt;, Box&lt;Expr&gt;)</code> is two pointers, so 16 bytes. The size is fixed and finite even though the actual tree in memory can be arbitrarily deep.</p> <p>Creating a recursive value with <code>Box</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> expr</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Expr</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Add</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Box</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Expr</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Number</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Box</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Expr</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Add</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Box</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Expr</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Number</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Box</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Expr</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Number</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> )),</span></span> <span class="giallo-l"><span style="color: #9399B2;">);</span></span></code></pre> <p>This represents <code>1 + (2 + 3)</code>. The outer <code>Add</code> holds two boxed <code>Expr</code> values on the heap. The inner <code>Add</code> is also heap-allocated. The leaves (<code>Number</code>) hold their data directly.</p> <h2 id="pattern-matching">Pattern Matching</h2> <p>Pattern matching is a mechanism for simultaneously inspecting the structure of a value and binding names to the parts inside it. A switch statement checks a condition and jumps to a branch. Pattern matching does that plus it destructures the value, extracts its internals, binds those internals to names you can use and the compiler verifies that every possible case is handled.</p> <h3 id="the-match-expression">The <code>match</code> Expression</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> some_value</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> pattern1</span><span style="color: #94E2D5;"> =&gt;</span><span> expression1</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> pattern2</span><span style="color: #94E2D5;"> =&gt;</span><span> expression2</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> pattern3</span><span style="color: #94E2D5;"> =&gt;</span><span> expression3</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>match</code> takes a value and compares it against a series of <strong>arms</strong>. Each arm has a pattern on the left of <code>=&gt;</code> and an expression on the right. Rust tries each pattern from top to bottom and executes the first one that matches. The entire <code>match</code> is an expression that means it produces a value and all arms must produce the same type of value.</p> <p>The simplest possible match is on a plain value:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;">i32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> description</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> x</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;one&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 2</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;two&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 3</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;three&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;something else&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">};</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> description</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // three</span></span></code></pre> <p><code>_</code> is the wildcard. It matches anything and binds nothing. Every <code>match</code> on a type with more possibilities than your explicit arms must include a catch-all or the compiler will complain.</p> <h3 id="matching-on-enum-variants-with-data">Matching on Enum Variants With Data</h3> <p>When a variant carries data, the pattern names bindings to extract that data:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Circle</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">f64</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Rectangle</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">f64</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> f64</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Rectangle</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">4</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 6</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> s</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Circle</span><span style="color: #9399B2;">(</span><span>radius</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Circle with radius </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> radius</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Rectangle</span><span style="color: #9399B2;">(</span><span>width</span><span style="color: #9399B2;">,</span><span> height</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Rectangle </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">x</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> width</span><span style="color: #9399B2;">,</span><span> height</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>Shape::Circle(radius)</code> is a pattern that matches any <code>Circle</code> variant and binds the inner <code>f64</code> to the name <code>radius</code>. Inside the arm, <code>radius</code> is a local variable holding that value. Same for width and height in the rectangle arm.</p> <p>For struct variants with named fields:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Circle</span><span style="color: #9399B2;"> {</span><span> radius</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f64</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Rectangle</span><span style="color: #9399B2;"> {</span><span> width</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f64</span><span style="color: #9399B2;">,</span><span> height</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f64</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Circle</span><span style="color: #9399B2;"> {</span><span> radius</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> s</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Circle</span><span style="color: #9399B2;"> {</span><span> radius</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Circle, radius = </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> radius</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Rectangle</span><span style="color: #9399B2;"> {</span><span> width</span><span style="color: #9399B2;">,</span><span> height</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">x</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> width</span><span style="color: #9399B2;">,</span><span> height</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The pattern <code>Shape::Circle { radius }</code> matches any <code>Circle</code> variant and binds the <code>radius</code> field to a local variable also called <code>radius</code>. If you want to rename it, you write <code>Shape::Circle { radius: r }</code></p> <h3 id="how-ownership-works-in-match">How ownership works in match</h3> <p>This is subtle and important. When you match on a value, what happens to ownership depends on whether you match by value or by reference.</p> <h4 id="matching-by-value">Matching by value</h4> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Circle</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> s</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Circle</span><span style="color: #9399B2;">(</span><span>r</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> r</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Rectangle</span><span style="color: #9399B2;">(</span><span>w</span><span style="color: #9399B2;">,</span><span> h</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{} {}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> w</span><span style="color: #9399B2;">,</span><span> h</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// s is moved — no longer usable</span></span></code></pre> <p>The entire value <code>s</code> is moved into the match. The matched arm receives ownership of the extracted data.</p> <h4 id="matching-by-reference">Matching by reference</h4> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Circle</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">match</span><span style="color: #94E2D5;"> &amp;</span><span>s</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Circle</span><span style="color: #9399B2;">(</span><span>r</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> r</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Shape</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Rectangle</span><span style="color: #9399B2;">(</span><span>w</span><span style="color: #9399B2;">,</span><span> h</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{} {}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> w</span><span style="color: #9399B2;">,</span><span> h</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// s is still valid here</span></span></code></pre> <p>When you match on <code>&amp;s</code>, the patterns automatically match against references. The bindings <code>r</code>, <code>w</code>, <code>h</code> become references to the data inside the variant (<code>&amp;f64</code> in this case)</p> <p>In practice, when you have a method taking <code>&amp;self</code>, you match on <code>self</code> (which is already <code>&amp;Shape</code> inside the method), and your bindings are references. If you're in a context where you own the value and want to consume it, you match on the value directly.</p> <h3 id="binding-with">Binding with <code>@</code></h3> <p>Sometimes you want to test whether a value matches a pattern and also give that value a name to use in the arm. The <code>@</code> operator does this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> n</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> u32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 7</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> n</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> small</span><span style="color: #94E2D5;"> @</span><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;">..=</span><span style="color: #FAB387;">5</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> is small&quot;</span><span style="color: #9399B2;">,</span><span> small</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> medium</span><span style="color: #94E2D5;"> @</span><span style="color: #FAB387;"> 6</span><span style="color: #94E2D5;">..=</span><span style="color: #FAB387;">10</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> is medium&quot;</span><span style="color: #9399B2;">,</span><span> medium</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> large</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> is large&quot;</span><span style="color: #9399B2;">,</span><span> large</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>medium @ 6..=10</code> means: match any value in the range 6 to 10, and bind that value to the name <code>medium</code>. Without <code>@</code>, a range pattern matches but gives you no name for the value. With <code>@</code>, you get both the test and the binding.</p> <h3 id="range-patterns">Range Patterns</h3> <p>Numeric and character types support range patterns:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> grade</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> u32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 85</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> letter</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> grade</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 90</span><span style="color: #94E2D5;">..=</span><span style="color: #FAB387;">100</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;A&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 80</span><span style="color: #94E2D5;">..=</span><span style="color: #FAB387;">89</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;B&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 70</span><span style="color: #94E2D5;">..=</span><span style="color: #FAB387;">79</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;C&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 60</span><span style="color: #94E2D5;">..=</span><span style="color: #FAB387;">69</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;D&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;F&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">};</span></span></code></pre> <p><code>90..=100</code> is an <strong>inclusive range pattern</strong>, it matches any value from 90 through 100 inclusive. The <code>..=</code> syntax is required for patterns (exclusive ranges with <code>..</code> are not allowed in match patterns because the compiler can't always verify exhaustiveness with them).</p> <h3 id="multiple-patterns-with">Multiple Patterns with <code>|</code></h3> <p>A single arm can match multiple patterns using <code>|</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> x</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;"> |</span><span style="color: #FAB387;"> 2</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;one or two&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 3</span><span style="color: #94E2D5;"> |</span><span style="color: #FAB387;"> 4</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;three or four&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;something else&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This is OR, the arm firsts if the value matches any of the listed patterns. You can combine this with ranges:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> x</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;"> |</span><span style="color: #FAB387;"> 2</span><span style="color: #94E2D5;"> |</span><span style="color: #FAB387;"> 3</span><span style="color: #94E2D5;">..=</span><span style="color: #FAB387;">5</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;between 1 and 5&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;out of range&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="match-guards">Match Guards</h3> <p>A <strong>match guard</strong> is an additional <code>if</code> condition attached to an arm. The arm only fires if both the pattern matches and the guard is true:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> pair</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> pair</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span>x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> if</span><span> x</span><span style="color: #94E2D5;"> ==</span><span> y</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;equal&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span>x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> if</span><span> x</span><span style="color: #94E2D5;"> +</span><span> y</span><span style="color: #94E2D5;"> ==</span><span style="color: #FAB387;"> 0</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;sum is zero&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span>x</span><span style="color: #9399B2;">,</span><span> _</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> if</span><span> x</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #FAB387;"> 0</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;x is positive&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;anything else&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// prints: sum is zero</span></span></code></pre> <p>The guard <code>if x + y == 0</code> has access to the bindings created by the pattern. Bindings are established first, then the guard is evaluated. If the guard fails, Rust moves on to the next arm</p> <blockquote> <p>One important caveat: <strong>the compiler does not consider guards when checking exhaustiveness</strong>. Guards are runtime conditions, and the compiler can't reason about their runtime truth. So even if your guards collectively cover all cases, the compiler will still require a wildcard arm if the patterns themselves don't cover all cases.</p> </blockquote> <h3 id="wildcard-patterns-in-depth">Wildcard Patterns in Depth</h3> <p><code>_</code> is not just a catch-all for the whole value. It can appear inside patterns to ignore specific parts:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> triple</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> triple</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span> _</span><span style="color: #9399B2;">,</span><span> _</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;starts with zero&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span>x</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span><span> _</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;middle is zero, first is </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span>x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;">,</span><span> _</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;first two: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> and </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The <code>_</code> in position means "match anything here, but don't bind it to a name". This is different from a named binding, which would move or copy the value. <code>_</code> explicitly discards it. If you are coming from languages like go or python, this should be familiar.</p> <p>You can also use <code>..</code> to ignore multiple fields at once in a struct pattern:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> z</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> p</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span> z</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> p</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> ..</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;x is </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>..</code> means "ignore all remaining fields". This is especially useful for structs with many fields when you only care about one or two.</p> <h3 id="matching-on-structs-directly">Matching on Structs Directly</h3> <p>You don't have to put a struct inside an enum to match on it. Structs support pattern matching directly in a <code>match</code> or a <code>let</code> binding:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> p</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 7</span><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> p</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;on y-axis at </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;on x-axis at </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;at (</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">, </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">)&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>Point { x: 0, y }</code> matches only when <code>x</code> is exactly <code>0</code>, and binds whatever <code>y</code> is to the name <code>y</code>. <code>Point { x, y }</code> matches any <code>Point</code> and binds both fields.</p> <h2 id="if-let-and-while-let"><code>if let</code> And <code>while let</code></h2> <p><code>match</code> is exhaustive by design, it forces you to handle every variant. That's exactly what you want most of the time. But sometimes you only care about one specific variant and want to do nothing for all other cases. Writing a full <code>match</code> for that feels like unnecessary:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Message</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Quit</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Write</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Move</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> msg</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Message</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Write</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> msg</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Message</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Write</span><span style="color: #9399B2;">(</span><span>text</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> text</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> (),</span><span style="color: #9399B2;font-style: italic;"> // do nothing — feels like noise</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The <code>_ =&gt; ()</code> arm is doing nothing meaningful. It's just there to satisfy exhaustiveness. <code>if let</code> exists precisely for this situation.</p> <h3 id="if-let"><code>if let</code></h3> <p><code>if let</code> combines a pattern match with a conditional. It executes the body only if the pattern matches, and does nothing otherwise:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> msg</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Message</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Write</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">if let</span><span style="color: #F9E2AF;font-style: italic;"> Message</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Write</span><span style="color: #9399B2;">(</span><span>text</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> msg</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> text</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Read this as: "if <code>msg</code> matches the pattern <code>Message::Write(text)</code>, bind the inner value to <code>text</code> and execute the block." If <code>msg</code> is <code>Message::Quit</code> or <code>Message::Move { .. }</code>, the block is skipped entirely</p> <p>The binding <code>text</code> only exists inside the <code>if let</code> block. Outside it, <code>text</code> doesn't exist.</p> <h3 id="if-let-with-an-else-branch"><code>if let</code> with an <code>else</code> branch</h3> <p>You can attach an <code>else</code> to handle the non-matching case:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> msg</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Message</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Quit</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">if let</span><span style="color: #F9E2AF;font-style: italic;"> Message</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Write</span><span style="color: #9399B2;">(</span><span>text</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> msg</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Message: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> text</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Not a write message&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>And you can chain <code>else if let</code> to check multiple patterns sequentially:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> msg</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Message</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Move</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 7</span><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">if let</span><span style="color: #F9E2AF;font-style: italic;"> Message</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Write</span><span style="color: #9399B2;">(</span><span>text</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> msg</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Write: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> text</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span><span style="color: #CBA6F7;"> else if let</span><span style="color: #F9E2AF;font-style: italic;"> Message</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Move</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> =</span><span> msg</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Move to (</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">, </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">)&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Something else&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This is a chain of independent pattern tests, tried in order. Unlike <code>match</code>, this does not have exhaustiveness checking. Use <code>match</code> when you need exhaustiveness, use <code>if let</code> when you genuinely only care about one case.</p> <h3 id="ownership-in-if-let">Ownership in <code>if let</code></h3> <p>The same ownership rules that apply to <code>match</code> apply here. If you write:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> msg</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Message</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Write</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">if let</span><span style="color: #F9E2AF;font-style: italic;"> Message</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Write</span><span style="color: #9399B2;">(</span><span>text</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> msg</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> text</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// msg is moved — no longer usable</span></span></code></pre> <p><code>msg</code> is moved into the pattern. To avoid moving, match on a reference:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> msg</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Message</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Write</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">if let</span><span style="color: #F9E2AF;font-style: italic;"> Message</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Write</span><span style="color: #9399B2;">(</span><span>text</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> = &amp;</span><span>msg</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> text</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // text is &amp;String</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// msg is still valid</span></span></code></pre> <p>Same thing as <code>match</code></p> <h3 id="while-let"><code>while let</code></h3> <p><code>while let</code> runs a loop for as long as a pattern keeps matching. The moment the pattern stops matching, the loop exits:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> stack</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">while let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>top</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> stack</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">pop</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> top</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>Vec::pop()</code> returns <code>Option&lt;T&gt;</code>. <code>Some(value)</code> if the vector has elements, <code>None</code> when it's empty. The <code>while let</code> keeps looping and binding <code>top</code> to each popped value as long as <code>pop()</code> returns <code>Some</code>. The instant it returns <code>None</code>, the pattern doesn't match and the loop exits.</p> <p>Without <code>while let</code>, you'd write this as:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">loop</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> stack</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">pop</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>top</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> top</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>while let</code> is just cleaner syntax for this exact pattern</p> <h3 id="what-if-let-and-while-let-actually-are">What <code>if let</code> and <code>while let</code> actually are</h3> <p>They are not new features with new rules. They are shorthand for specific shapes of <code>match</code> that are common enough to deserve their own syntax. The compiler desugars them into <code>match</code> expressions before doing anything else.</p> <p><code>if let</code> = <code>match</code> with one meaningful arm and <code>_ =&gt; ()</code> for everything else, plus an optional <code>else</code>.</p> <p><code>while let</code> = <code>loop</code> containing a <code>match</code> that breaks on the non-matching case.</p> <h3 id="guards-in-if-let">Guards in <code>if let</code></h3> <p>You can attach a guard to <code>if let</code> the same way as in <code>match</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> number</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">7</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> number</span><span style="color: #94E2D5;"> &amp;&amp;</span><span> n</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> is greater than 5&quot;</span><span style="color: #9399B2;">,</span><span> n</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This syntax (using <code>&amp;&amp;</code> directly after the pattern) is available in Rust 1.65+</p> <h2 id="destructuring-in-let-bindings-and-for-loops">Destructuring in <code>let</code> Bindings and <code>for</code> Loops</h2> <p>Destructuring is using a pattern on the left side of a <code>let</code> binding or in a <code>for</code> loop to simultaneously unpack a value and bind its parts to names.</p> <h3 id="destructuring-tuples-in-let">Destructuring tuples in <code>let</code></h3> <p>The simplest case is a tuple:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span style="color: #9399B2;"> (</span><span>x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;">,</span><span> z</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{} {} {}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;">,</span><span> z</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // 1 2 3</span></span></code></pre> <p>The left side <code>(x, y, z)</code> is a pattern. Rust matches the right side <code>(1, 2, 3)</code> against it, binding <code>1</code> to <code>x</code>, <code>2</code> to <code>y</code>, <code>3</code> to <code>z</code>. All three bindings are created simultaneously in a single statement.</p> <p>You can ignore parts with <code>_</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span style="color: #9399B2;"> (</span><span>first</span><span style="color: #9399B2;">,</span><span> _</span><span style="color: #9399B2;">,</span><span> third</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span style="color: #FAB387;">10</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 20</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 30</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{} {}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> first</span><span style="color: #9399B2;">,</span><span> third</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // 10 30</span></span></code></pre> <p>Or ignore a trailing portion with <code>..</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span style="color: #9399B2;"> (</span><span>head</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> ..</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 4</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> head</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // 1</span></span></code></pre><h3 id="destructuring-structs-in-let">Destructuring Structs in <code>let</code></h3> <p>Struct patterns work directly in <code>let</code> bindings too:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> p</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 20</span><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> =</span><span> p</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{} {}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // 10 20</span></span></code></pre> <p><code>let Point { x, y } = p</code> destructures <code>p</code> into two bindings <code>x</code> and <code>y</code>. After this, <code>p</code> is moved (since <code>Point</code> doesn't implement <code>Copy</code>), and <code>x</code> and <code>y</code> are the extracted values</p> <p>To rename while destructuring:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #94E2D5;">:</span><span> horizontal</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #94E2D5;">:</span><span> vertical</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> =</span><span> p</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{} {}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> horizontal</span><span style="color: #9399B2;">,</span><span> vertical</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // 10 20</span></span></code></pre> <p>The field <code>x</code> is bound to the local name <code>horizontal</code>. The field <code>y</code> is bound to <code>vertical</code>. The struct field name is on the left of <code>:</code>, the local binding name is on the right.</p> <p>To avoid moving, destructure from a reference:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> p</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 20</span><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;"> }</span><span style="color: #94E2D5;"> = &amp;</span><span>p</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// x and y are &amp;i32 here</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{} {}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// p is still valid</span></span></code></pre><h3 id="destructuring-enums-in-let">Destructuring Enums in <code>let</code></h3> <p>You can destructure an enum variant directly in a <code>let</code> binding, but only if you're certain which variant it is because <code>let</code> patterns are <strong>irrefutable</strong>. An irrefutable pattern is one that is guaranteed to match for any possible value of the type.</p> <p>A tuple <code>(x, y)</code> is irrefutable for any tuple with two elements, it always matches. A struct pattern <code>Point { x, y }</code> is irrefutable for a <code>Point</code>, it always matches. But <code>Some(x)</code> is refutable for <code>Option&lt;T&gt;</code>, it doesn't match <code>None</code>.</p> <p>If you try:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>value</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> some_option</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // ERROR: refutable pattern</span></span></code></pre> <p>The compiler rejects this. It can't guarantee the pattern matches. For refutable patterns, you must use <code>match</code> or <code>if let</code>.</p> <p>This restriction exists because a failing <code>let</code> binding has nowhere to go, there's no else branch, no other arm. The compiler catches this at compile time rather than letting it panic at runtime.</p> <h3 id="destructuring-in-for-loops">Destructuring in <code>for</code> loops</h3> <p>A <code>for</code> loop iterates over a sequence and binds each element to a pattern. Most of the time people write:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">for</span><span> item</span><span style="color: #CBA6F7;"> in</span><span> collection</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // use item</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>But <code>item</code> is actually a pattern, not just a name. You can put any irrefutable pattern there:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> pairs</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[(</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">, &#39;</span><span style="color: #A6E3A1;">a</span><span style="color: #9399B2;">&#39;), (</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">, &#39;</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;), (</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">, &#39;</span><span style="color: #A6E3A1;">c</span><span style="color: #9399B2;">&#39;)];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">for</span><span style="color: #9399B2;"> (</span><span>number</span><span style="color: #9399B2;">,</span><span> letter</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span> pairs</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> number</span><span style="color: #9399B2;">,</span><span> letter</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Each element of <code>pairs</code> is a tuple <code>(i32, char)</code>. The pattern <code>(number, letter)</code> destructures each tuple on the spot, giving you both values named and ready to use inside the loop body. Without destructuring, you'd need to write <code>pair.0</code> and <code>pair.1</code>, which is less clear.</p> <p>Destructuring structs in <code>for</code> loops works the same way:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> points</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 4</span><span style="color: #9399B2;"> },</span></span> <span class="giallo-l"><span style="color: #9399B2;">];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">for</span><span style="color: #F9E2AF;font-style: italic;"> Point</span><span style="color: #9399B2;"> {</span><span> x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>points</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;(</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">, </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">)&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <blockquote> <p>Note <code>&amp;points</code> iterating over a reference to the vector gives you references to each element, so <code>x</code> and <code>y</code> are <code>&amp;i32</code>. The vector remains valid after the loop.</p> </blockquote> <h3 id="nested-destructuring">Nested Destructuring</h3> <p>Patterns can be nested to match nested structures:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> nested</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> ((</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">), (</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 4</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span style="color: #9399B2;"> ((</span><span>a</span><span style="color: #9399B2;">,</span><span> b</span><span style="color: #9399B2;">), (</span><span>c</span><span style="color: #9399B2;">,</span><span> d</span><span style="color: #9399B2;">))</span><span style="color: #94E2D5;"> =</span><span> nested</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{} {} {} {}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> a</span><span style="color: #9399B2;">,</span><span> b</span><span style="color: #9399B2;">,</span><span> c</span><span style="color: #9399B2;">,</span><span> d</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // 1 2 3 4</span></span></code></pre> <p>The outer pattern <code>((a, b), (c, d))</code> matches a tuple of two tuples. Rust unpacks both levels simultaneously. This scales to arbitrary depth.</p> <h3 id="destructuring-function-parameters">Destructuring Function Parameters</h3> <p>Patterns also work directly in function parameter position:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> print_point</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">x</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> y</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">i32</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">)) {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;x=</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">, y=</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #9399B2;">,</span><span> y</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> p</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 7</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">print_point</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>p</span><span style="color: #9399B2;">);</span></span></code></pre> <p><code>&amp;(x, y)</code> in the parameter position is a pattern that matches a reference to a tuple and immediately destructures it. Inside the function, <code>x</code> and <code>y</code> are <code>i32</code> values, not references. This is occasionally useful but less common than destructuring in <code>let</code> or <code>for</code>.</p> <p>Now, its time to start working on our JSON parser. If you think you don't understand all the above concepts thats fine. I would say just start building the project and read the required concept again. It's too much to take at once, so take your time.</p> <h2 id="what-a-json-parser-actually-does">What a JSON Parser Actually Does</h2> <p>Parsing is the process of taking raw text and turning it into structured data your program can work with. For JSON, that means taking a string like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="json"><span class="giallo-l"><span style="color: #9399B2;">{&quot;</span><span style="color: #89B4FA;">name</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;alice&quot;</span><span style="color: #9399B2;">, &quot;</span><span style="color: #89B4FA;">age</span><span style="color: #9399B2;">&quot;:</span><span style="color: #FAB387;"> 30</span><span style="color: #9399B2;">, &quot;</span><span style="color: #89B4FA;">scores</span><span style="color: #9399B2;">&quot;: [</span><span style="color: #FAB387;">95</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 87</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 100</span><span style="color: #9399B2;">], &quot;</span><span style="color: #89B4FA;">active</span><span style="color: #9399B2;">&quot;:</span><span style="color: #FAB387;"> true</span><span style="color: #9399B2;">}</span></span></code></pre> <p>and producing a value in memory that your Rust code can inspect, traverse and query. Something like: "this is an object with four keys, the first key <code>name</code> maps to the string <code>alice</code>, the second key <code>age</code> maps to the number <code>30</code>" and so on</p> <p>A parser typically works in two stages:</p> <ol> <li>Tokenization (lexing) - walk the raw input character by character and group characters into meaningful units called tokens. A token might be <code>{</code> or <code>"alice"</code> or <code>30</code> or <code>true</code> or <code>[</code>. At this stage you are not thinking about structure, you are just identifying the atoms of the language.</li> <li>Parsing - Take the stream of tokens and build a structured value from them according to the grammar rules of JSON. This is where you recognise that <code>{</code> starts an object, that an object contains key-value pairs separated by ",", that each key is a string followed by <code>:</code> followed by a value and so on.</li> </ol> <h3 id="the-grammar-of-json">The Grammar of JSON</h3> <p>JSON is simple, precise grammar. A JSON value is exactly one of:</p> <ul> <li>An object: <code>{</code> followed by zero or more <code>"key": value</code> pairs separated by <code>,</code>, followed by <code>}</code></li> <li>An array: <code>[</code> followed by zero or more values separated by <code>,</code>, followed by <code>]</code></li> <li>A string: <code>"</code> followed by characters followed by <code>"</code></li> <li>A number: an optional <code>-</code>, digits, optional decimal point and more digits</li> <li>A boolean: exactly <code>true</code> or <code>false</code></li> <li>null: exactly <code>null</code></li> </ul> <p>Objects and arrays contain values and values can themselves be objects or arrays. This is what makes JSON recursive, and why recursive enum is the right representation.</p> <h3 id="the-jsonvalue-type">The <code>JSONValue</code> type</h3> <p>Before writing any parsing code, we define the type that represents a parsed JSON value:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> JSONValue</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Object</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> JSONValue</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Array</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">JSONValue</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Str</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Number</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">f64</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Bool</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">bool</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Null</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Let's understand each and every variant:</p> <ul> <li><code>Object(Vec&lt;(String, JsonValue)&gt;)</code> - A JSON object is an unordered collection of key-value pairs. Each key is always a string. Each value is any <code>JsonValue</code>. We represent this as a <code>Vec</code> of <code>(String, JsonValue)</code> tuples. We're using a <code>Vec</code> of tuples rather than a <code>HashMap</code> because we haven't covered hashmap concept yet. A <code>Vec</code> of tuples works correctly and is simpler.</li> <li><code>Array(Vec&lt;JsonValue&gt;)</code> - A JSON array is an ordered sequence of values. Each element is any <code>JsonValue</code>. Straightforward.</li> <li><code>Str(String)</code> - A JSON string. We name the variant <code>Str</code> rather than <code>String</code> to avoid conflicting with Rust's built-in <code>String</code> type name.</li> <li><code>Number(f64)</code> - JSON makes no distinction between integers and floats. The spec says all numbers are IEEE 754 doubles, so <code>f64</code> is the correct choice.</li> <li><code>Bool(bool)</code> - JSON booleans <code>true</code> and <code>false</code>.</li> <li><code>Null</code> - JSON null. No data needed.</li> </ul> <p>Notice that <code>Object</code> contains <code>JsonValue</code> inside it, and <code>Array</code> contains <code>JsonValue</code> inside it. This is the recursive structure. But unlike the <code>Expr</code> example from the enums section, we don't need explicit <code>Box</code> here because <code>Vec</code> already heap-allocates its contents. The <code>Vec</code> itself is a fixed-size struct on the stack (a pointer, a length, and a capacity of 24 bytes). The actual <code>JsonValue</code> elements live on the heap inside the <code>Vec</code>'s buffer. So the indirection is already there.</p> <h3 id="the-token-type">The Token Type</h3> <p>The tokenizer will produce a sequence of tokens. Here's what the token type looks like:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> LeftBrace</span><span style="color: #9399B2;">,</span><span style="color: #9399B2;font-style: italic;"> // {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> RightBrace</span><span style="color: #9399B2;">,</span><span style="color: #9399B2;font-style: italic;"> // }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> LeftBracket</span><span style="color: #9399B2;">,</span><span style="color: #9399B2;font-style: italic;"> // [</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> RightBracket</span><span style="color: #9399B2;">,</span><span style="color: #9399B2;font-style: italic;"> // ]</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Colon</span><span style="color: #9399B2;">,</span><span style="color: #9399B2;font-style: italic;"> // :</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Comma</span><span style="color: #9399B2;">,</span><span style="color: #9399B2;font-style: italic;"> // ,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> StringToken</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> NumberToken</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">f64</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> True</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> False</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Null</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Each variant represents one meaningful unit from the input. Single-character punctuation maps to simple variants with no data. Strings and numbers carry their parsed value. <code>True</code>, <code>False</code>, and <code>Null</code> are keyword tokens.</p> <h3 id="project-setup">Project Setup</h3> <p>Create the project:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> new json_parser</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> json_parser</span></span></code></pre> <p>Open <code>src/main.rs</code>. We'll put everything in one file for simplicity, we will later learn about modularising our code. Here's the skeleton we'll fill in:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// The token type</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> LeftBrace</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> RightBrace</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> LeftBracket</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> RightBracket</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Colon</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Comma</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> StringToken</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> NumberToken</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">f64</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> True</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> False</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Null</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// The JSON value type</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Object</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Array</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">JsonValue</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Str</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Number</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">f64</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Bool</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">bool</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Null</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// Stage 1: tokenizer</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> tokenize</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">input</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Token</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> todo!</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// Stage 2: parser</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> parse</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">tokens</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">Token</span><span style="color: #9399B2;">])</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> todo!</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> input</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> r#&quot;{&quot;name&quot;: &quot;alice&quot;, &quot;age&quot;: 30, &quot;active&quot;: true}&quot;#</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> tokens</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> tokenize</span><span style="color: #9399B2;">(</span><span>input</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> value</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> parse</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>tokens</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>todo!()</code> is a macro that panics with "not yet implemented". It lets the code compile while functions are incomplete.</p> <p>The <code>r#"..."#</code> syntax is a raw string literal. The <code>#</code> delimiters mean backslashes and inner quotes are not treated as escape sequences. This makes it easier to write JSON strings in Rust source code without escaping every <code>"</code>.</p> <h3 id="the-tokenizer">The Tokenizer</h3> <p>The tokenizer's job is to walk the input string character by character and produce a <code>Vec&lt;Token&gt;</code>. It needs to:</p> <ul> <li>Skip whitespace</li> <li>Recognise single-character punctuation (<code>{</code>, <code>}</code>, <code>[</code>, <code>]</code>, <code>:</code>, <code>,</code>)</li> <li>Recognise string literals (everything between <code>"</code> and <code>"</code>, handling escape sequences)</li> <li>Recognise numbers (digits, optional minus sign, optional decimal)</li> <li>Recognise the keywords <code>true</code>, <code>false</code>, <code>null</code></li> <li>Panic on anything unexpected</li> </ul> <h3 id="how-we-ll-walk-the-input">How We'll Walk the Input</h3> <p>We need to walk through the characters of the input string with the ability to:</p> <ul> <li>Look at the current character</li> <li>Advance past it</li> <li>Sometimes look ahead without advancing</li> </ul> <p>The right tool for this is a <strong>struct</strong> that holds the input as a slice of bytes and tracks the current position:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Lexer</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> input</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">u8</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> pos</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>input</code> is the raw bytes of the input string, owned by the lexer. <code>pos</code> is the current position, its the index of the next character to be processed.</p> <blockquote> <p>We could use a concept called lifetime here but lets not go there as we haven't understood that concept as of now. We will keep it simple by letting the lexer own its data</p> </blockquote> <p>Now the <code>impl</code> block:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Lexer</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> new</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">input</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Lexer</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Lexer</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> input</span><span style="color: #94E2D5;">:</span><span> input</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">as_bytes</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_vec</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> pos</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> current</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">u8</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>pos</span><span style="color: #94E2D5;"> &lt;</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>input</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>input</span><span style="color: #9399B2;">[</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>pos</span><span style="color: #9399B2;">])</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> advance</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>pos </span><span style="color: #94E2D5;">+=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> peek</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">u8</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>pos </span><span style="color: #94E2D5;">+</span><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;"> &lt;</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>input</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>input</span><span style="color: #9399B2;">[</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>pos </span><span style="color: #94E2D5;">+</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">])</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <ul> <li><code>new</code> converts the <code>&amp;str</code> to a <code>Vec&lt;u8&gt;</code>, we work with raw bytes because JSON is ASCII-compatible for all structural characters, and byte indexing is simpler than character indexing for this purpose.</li> <li><code>current</code> returns the byte at the current position, wrapped in <code>Option</code>, <code>None</code> if we've reached the end.</li> <li><code>advance</code> moves the position forward by one.</li> <li><code>peek</code> looks one position ahead without moving. We'll need this for number parsing to distinguish <code>-3</code> (a negative number) from <code>-</code> followed by something invalid.</li> </ul> <h3 id="the-main-tokenize-loop">The Main Tokenize Loop</h3> <p>Now the <code>tokenize</code> function creates a <code>Lexer</code> and drives a loop:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> tokenize</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">input</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Token</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> lexer</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Lexer</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>input</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> tokens</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> loop</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> lexer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39; &#39;)</span><span style="color: #94E2D5;"> |</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #F5C2E7;">\t</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> |</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #F5C2E7;">\n</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> |</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #F5C2E7;">\r</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> lexer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">{</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> tokens</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">LeftBrace</span><span style="color: #9399B2;">);</span><span> lexer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">}</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> tokens</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RightBrace</span><span style="color: #9399B2;">);</span><span> lexer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">[</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> tokens</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">LeftBracket</span><span style="color: #9399B2;">);</span><span> lexer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">]</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> tokens</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RightBracket</span><span style="color: #9399B2;">);</span><span> lexer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">:</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> tokens</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Colon</span><span style="color: #9399B2;">);</span><span> lexer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">,</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> tokens</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Comma</span><span style="color: #9399B2;">);</span><span> lexer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> s</span><span style="color: #94E2D5;"> =</span><span> lexer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">read_string</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> tokens</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Token</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">StringToken</span><span style="color: #9399B2;">(</span><span>s</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">t</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> lexer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">read_keyword</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;true&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> tokens</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">True</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">f</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> lexer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">read_keyword</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;false&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> tokens</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">False</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">n</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> lexer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">read_keyword</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;null&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> tokens</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Null</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">-</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> |</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">0</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;">..=</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">9</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> n</span><span style="color: #94E2D5;"> =</span><span> lexer</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">read_number</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> tokens</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">Token</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NumberToken</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Unexpected character: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> c</span><span style="color: #CBA6F7;"> as</span><span style="color: #F9E2AF;font-style: italic;"> char</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> tokens</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>A few things to understand here:</p> <p><code>b' '</code> is a <strong>byte literal</strong> - the ASCII value of the space character as a <code>u8</code>. This is how you write character comparisons when working with <code>&amp;[u8]</code> instead of <code>&amp;str</code>.</p> <p><code>b'0'..=b'9'</code> is a byte range pattern - it matches any byte whose value is between the ASCII value of <code>'0'</code> and the ASCII value of <code>'9'</code> inclusive. This is how you check "is this character a digit" without calling any methods.</p> <p>The <code>Some(b't')</code>, <code>Some(b'f')</code>, <code>Some(b'n')</code> arms peek at the first character to decide which keyword we're reading, then delegate to <code>read_keyword</code> which consumes the full keyword and panics if it doesn't match.</p> <p><code>Some(c)</code> at the bottom is the catch-all - if we hit any character we don't recognise, we panic with a message showing what it was.</p> <h3 id="reading-keywords">Reading Keywords</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Lexer</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> read_keyword</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> keyword</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> expected</span><span style="color: #CBA6F7;"> in</span><span> keyword</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">as_bytes</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> if</span><span> c</span><span style="color: #94E2D5;"> == *</span><span>expected</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;Unexpected character &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39; while reading keyword &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39;&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> c</span><span style="color: #CBA6F7;"> as</span><span style="color: #F9E2AF;font-style: italic;"> char</span><span style="color: #9399B2;">,</span><span> keyword</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Unexpected end of input while reading keyword &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39;&quot;</span><span style="color: #9399B2;">,</span><span> keyword</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>We iterate over the bytes of the expected keyword string. For each expected byte, we check the current character. If it matches, we advance. If it doesn't match or we hit the end of input, we panic.</p> <p>The pattern <code>Some(c) if c == *expected</code> is a match guard. <code>expected</code> is <code>&amp;u8</code> (a reference to a byte in the keyword slice), so we dereference it with <code>*expected</code> to compare against <code>c</code> which is <code>u8</code></p> <h3 id="reading-strings">Reading Strings</h3> <p>String reading is the most involved part of the tokenizer because JSON strings support escape sequences: <code>\"</code>, <code>\\</code>, <code>\/</code>, <code>\n</code>, <code>\t</code>, <code>\r</code>, and Unicode escapes <code>\uXXXX</code>.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Lexer</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> read_string</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // consume the opening &quot;</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> result</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> loop</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Unterminated string&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span><span style="color: #9399B2;font-style: italic;"> // consume closing &quot;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span> result</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #F5C2E7;">\\</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span><span style="color: #9399B2;font-style: italic;"> // consume the backslash</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">&#39;);</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #F5C2E7;">\\</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #F5C2E7;">\\</span><span style="color: #9399B2;">&#39;);</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">/</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">/</span><span style="color: #9399B2;">&#39;);</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">n</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #F5C2E7;">\n</span><span style="color: #9399B2;">&#39;);</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">t</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #F5C2E7;">\t</span><span style="color: #9399B2;">&#39;);</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">r</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #F5C2E7;">\r</span><span style="color: #9399B2;">&#39;);</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #F5C2E7;">\x08</span><span style="color: #9399B2;">&#39;);</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">f</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #F5C2E7;">\x0C</span><span style="color: #9399B2;">&#39;);</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">(); }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">u</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span><span style="color: #9399B2;font-style: italic;"> // consume &#39;u&#39;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> codepoint</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">read_unicode_escape</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> ch</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> char</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_u32</span><span style="color: #9399B2;">(</span><span>codepoint</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">unwrap_or_else</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">||</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid unicode codepoint: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> codepoint</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>ch</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid escape sequence: </span><span style="color: #F5C2E7;">\\</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> c</span><span style="color: #CBA6F7;"> as</span><span style="color: #F9E2AF;font-style: italic;"> char</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Unterminated escape sequence&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #CBA6F7;"> as</span><span style="color: #F9E2AF;font-style: italic;"> char</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> read_unicode_escape</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> u32</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> value</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> u32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> _</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 0</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">4</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> digit</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> c</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">0</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;">..=</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">9</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> (</span><span>c</span><span style="color: #94E2D5;"> -</span><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">0</span><span style="color: #9399B2;">&#39;)</span><span style="color: #CBA6F7;"> as u32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">a</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;">..=</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">f</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> (</span><span>c</span><span style="color: #94E2D5;"> -</span><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">a</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> as u32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">A</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;">..=</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">F</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> (</span><span>c</span><span style="color: #94E2D5;"> -</span><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">A</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> as u32</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid hex digit in unicode escape: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> c</span><span style="color: #CBA6F7;"> as</span><span style="color: #F9E2AF;font-style: italic;"> char</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"><span> value</span><span style="color: #94E2D5;"> =</span><span> value</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> 16</span><span style="color: #94E2D5;"> +</span><span> digit</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> None</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Unterminated unicode escape&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> value</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The outer loop runs until we hit the closing <code>"</code> or the end of input. Three cases:</p> <ul> <li><code>Some(b'"')</code> - closing quote, we advance past it and return the accumulated string.</li> <li><code>Some(b'\\')</code> - backslash, meaning an escape sequence follows. We advance past the backslash, then look at the next character to determine which escape it is. Each escape character maps to its actual value. The <code>\uXXXX</code> case reads exactly four hex digits and converts them to a Unicode codepoint.</li> <li><code>Some(c)</code> - any other character, push it directly onto the result string. <code>c as char</code> converts the <code>u8</code> byte to a Rust <code>char</code>.</li> </ul> <p>In <code>read_unicode_escape</code>, the hex digit parsing uses byte arithmetic: <code>c - b'0'</code> gives the numeric value of a decimal digit (e.g., <code>b'3' - b'0'</code> = <code>3</code>). <code>c - b'a' + 10</code> gives the numeric value of a lowercase hex letter (e.g., <code>b'c' - b'a' + 10</code> = <code>12</code>). We accumulate the four digits into a <code>u32</code> using <code>value = value * 16 + digit</code>, shifting left one hex place each iteration.</p> <h3 id="reading-numbers">Reading Numbers</h3> <p>JSON numbers can be negative, can have a decimal point, and can have an exponent (<code>1.5e10</code>). We'll support negative, integer, and decimal forms. Exponent notation is rare in practice and we'll leave it out to keep the code focused.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Lexer</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> read_number</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> f64</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // optional minus sign</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">-</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">-</span><span style="color: #9399B2;">&#39;);</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // integer part</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> loop</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #94E2D5;"> @</span><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">0</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;">..=</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">9</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #CBA6F7;"> as</span><span style="color: #F9E2AF;font-style: italic;"> char</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // optional decimal part</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">.</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">.</span><span style="color: #9399B2;">&#39;);</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> loop</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #94E2D5;"> @</span><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">0</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;">..=</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">9</span><span style="color: #9399B2;">&#39;)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #CBA6F7;"> as</span><span style="color: #F9E2AF;font-style: italic;"> char</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">parse</span><span style="color: #94E2D5;">::</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">f64</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap_or_else</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>_</span><span style="color: #94E2D5;">|</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid number: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> s</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>We accumulate the number's characters into a <code>String</code>, then use Rust's built-in <code>str::parse::&lt;f64&gt;()</code> to convert it. This avoids reimplementing float parsing from scratch.</p> <p><code>Some(c @ b'0'..=b'9')</code> is an <code>@</code> binding combined with a range pattern, it matches any digit byte and simultaneously binds it to <code>c</code> so we can push it onto the string. Without <code>@</code>, we'd match the digit but have no name for it.</p> <p>The <code>if let Some(b'.') = self.current()</code> checks for a decimal point without consuming it first, if it's there, we push it and advance into the fractional digits loop.</p> <h3 id="the-parser">The Parser</h3> <p>The parser takes the <code>Vec&lt;Token&gt;</code> the tokenizer produced and turns it into a <code>JsonValue</code>. It works through the token list using the same cursor pattern as the lexer, a current position that advances as tokens are consumed.</p> <h3 id="the-parser-struct">The parser Struct</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Parser</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> tokens</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Token</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> pos</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Parser</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> new</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">tokens</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Token</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Parser</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Parser</span><span style="color: #9399B2;"> {</span><span> tokens</span><span style="color: #9399B2;">,</span><span> pos</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> current</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt; &amp;</span><span style="color: #F9E2AF;font-style: italic;">Token</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>pos</span><span style="color: #94E2D5;"> &lt;</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>tokens</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &amp;</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>tokens</span><span style="color: #9399B2;">[</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>pos</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Unexpected end of token stream&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> advance</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>pos </span><span style="color: #94E2D5;">+=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> expect</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> description</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt; &amp;</span><span style="color: #F9E2AF;font-style: italic;">Token</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>pos</span><span style="color: #94E2D5;"> &lt;</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>tokens</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> token</span><span style="color: #94E2D5;"> = &amp;</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>tokens</span><span style="color: #9399B2;">[</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span>pos</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>pos </span><span style="color: #94E2D5;">+=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> token</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Expected </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> but reached end of input&quot;</span><span style="color: #9399B2;">,</span><span> description</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>current</code> returns a reference to the token at the current position without advancing. Unlike the lexer's <code>current</code> which returned <code>Option&lt;u8&gt;</code>, this one panics on end-of-input, by the time we're parsing, a well-formed token stream always has a next token when the grammar says there should be one.</p> <p><code>expect</code> is a convenience method that returns the current token and advances past it in one step. We'll use it when we need to consume a token we know must be there like the <code>:</code> between a key and value in an object.</p> <p>Notice <code>current</code> and <code>expect</code> both return <code>&amp;Token</code> a reference into the parser's token vector. The parser owns the tokens, and we borrow them out. This means when we pattern match on <code>self.current()</code>, we're matching on a <code>&amp;Token</code>. Keep that in mind we'll see it immediately.</p> <h3 id="the-core-parse-value">The Core <code>parse_value</code></h3> <p>The parser is built around one central method: <code>parse_value</code>. It looks at the current token and dispatches to the appropriate parsing logic:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Parser</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> parse_value</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">LeftBrace</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">parse_object</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">LeftBracket</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">parse_array</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">True</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Bool</span><span style="color: #9399B2;">(</span><span style="color: #F38BA8;">true</span><span style="color: #9399B2;">) }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">False</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Bool</span><span style="color: #9399B2;">(</span><span style="color: #F38BA8;">false</span><span style="color: #9399B2;">) }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Null</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Null</span><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NumberToken</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> value</span><span style="color: #94E2D5;"> = *</span><span>n</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Number</span><span style="color: #9399B2;">(</span><span>value</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">StringToken</span><span style="color: #9399B2;">(</span><span>s</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> value</span><span style="color: #94E2D5;"> =</span><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Str</span><span style="color: #9399B2;">(</span><span>value</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RightBrace</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Unexpected &#39;}&#39;&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RightBracket</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Unexpected &#39;]&#39;&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Colon</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Unexpected &#39;:&#39;&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Comma</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Unexpected &#39;,&#39;&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This is the grammar of JSON encoded directly as Rust code. A value is one of six things and the first token tells us which one.</p> <p>There are two important ownership details here that need explaining.</p> <p><strong>Why <code>*n</code> for the number:</strong> <code>self.current()</code> returns <code>&amp;Token</code>. When we match <code>Token::NumberToken(n)</code> on a <code>&amp;Token</code>, the binding <code>n</code> is <code>&amp;f64</code>, a reference to the <code>f64</code> inside the token. We write <code>let value = *n</code> to dereference it and copy the <code>f64</code> out. <code>f64</code> is <code>Copy</code>, so this is a copy, not a move. We need <code>value</code> as an owned <code>f64</code> to put inside <code>JsonValue::Number(value)</code>.</p> <p><strong>Why <code>s.clone()</code> for the string:</strong> Same situation, <code>s</code> is <code>&amp;String</code>, a reference to the string inside the token. We can't move out of it because we only have a reference. <code>String</code> is not <code>Copy</code>. So we call <code>.clone()</code> to produce an owned <code>String</code> we can put inside <code>JsonValue::Str(value)</code>. The token keeps its copy, our new <code>JsonValue</code> gets its own copy.</p> <p>The <code>parse_object</code> and <code>parse_array</code> calls are where the recursive structure lives, we'll write those next.</p> <h3 id="parsing-objects">Parsing Objects</h3> <p>A JSON object looks like:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="json"><span class="giallo-l"><span style="color: #9399B2;">{&quot;</span><span style="color: #89B4FA;">key1</span><span style="color: #9399B2;">&quot;:</span><span> value</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">, &quot;</span><span style="color: #89B4FA;">key2</span><span style="color: #9399B2;">&quot;:</span><span> value</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">}</span></span></code></pre> <p>The grammar is: <code>{</code>, then zero or more <code>string : value</code> pairs separated by <code>,</code>, then <code>}</code>.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Parser</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> parse_object</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span><span style="color: #9399B2;font-style: italic;"> // consume &#39;{&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> pairs</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // handle empty object</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RightBrace</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Object</span><span style="color: #9399B2;">(</span><span>pairs</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> loop</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // parse the key, must be a string</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> key</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">expect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;object key&quot;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">StringToken</span><span style="color: #9399B2;">(</span><span>s</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clone</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> other</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Expected string key, got something else&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // consume the colon</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">expect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;colon&quot;</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Colon</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {}</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Expected &#39;:&#39; after object key&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // parse the value, recursive call</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> value</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">parse_value</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> pairs</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">((</span><span>key</span><span style="color: #9399B2;">,</span><span> value</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // after a pair, expect either &#39;,&#39; or &#39;}&#39;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Comma</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span><span style="color: #9399B2;font-style: italic;"> // consume comma, loop for next pair</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RightBrace</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span><span style="color: #9399B2;font-style: italic;"> // consume &#39;}&#39;, we&#39;re done</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Expected &#39;,&#39; or &#39;}}&#39; in object&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Object</span><span style="color: #9399B2;">(</span><span>pairs</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Walk through the logic step by step:</p> <p>We advance past the <code>{</code>. Then we immediately check for <code>}</code>, an empty object <code>{}</code> is valid and we return early with an empty <code>Vec</code>.</p> <p>For non-empty objects we enter a loop. Each iteration parses one key-value pair. We call <code>self.expect("object key")</code> which gives us the current token and advances. We match it, if it's a <code>StringToken</code> we clone the string out. If it's anything else, we panic.</p> <p>Then we expect a <code>Colon</code>. The match arm <code>Token::Colon =&gt; {}</code> matches and does nothing, we just needed to consume the token and verify it was a colon.</p> <p>Then <code>self.parse_value()</code>, this is the recursive call. The value after the colon can itself be any JSON value, including a nested object or array. <code>parse_value</code> handles all of that. This recursion is what makes the parser work for arbitrarily deep JSON.</p> <p>After parsing the pair, we look at the current token. A comma means there's another pair, consume it and loop. A <code>}</code> means we're done, consume it and break. Anything else is malformed JSON.</p> <p>One thing to note: the <code>other</code> binding in <code>match self.expect("object key")</code>, we write it as <code>other</code> rather than <code>_</code> so we have a name if we wanted to include it in the panic message. With our current conceptual understanding we can't easily format arbitrary token types, so we just use a generic message. In later articles we'll learn to make error messages much richer</p> <h3 id="parsing-arrays">Parsing Arrays</h3> <p>A JSON array looks like:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="json"><span class="giallo-l"><span style="color: #9399B2;">[</span><span>value</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span> value</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">,</span><span> value</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">]</span></span></code></pre> <p>The grammar is: <code>[</code>, then zero or more values separated by <code>,</code>, then <code>]</code>. It's structurally identical to object parsing but simpler</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> Parser</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> parse_array</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span><span style="color: #9399B2;font-style: italic;"> // consume &#39;[&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> elements</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">JsonValue</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // handle empty array</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RightBracket</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Array</span><span style="color: #9399B2;">(</span><span>elements</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> loop</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> element</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">parse_value</span><span style="color: #9399B2;">();</span><span style="color: #9399B2;font-style: italic;"> // recursive call</span></span> <span class="giallo-l"><span> elements</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>element</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">current</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Comma</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span><span style="color: #9399B2;font-style: italic;"> // consume comma, loop for next element</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Token</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RightBracket</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">advance</span><span style="color: #9399B2;">();</span><span style="color: #9399B2;font-style: italic;"> // consume &#39;]&#39;, we&#39;re done</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Expected &#39;,&#39; or &#39;]&#39; in array&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Array</span><span style="color: #9399B2;">(</span><span>elements</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Same pattern as <code>parse_object</code>, advance past the opening bracket, handle the empty case, loop parsing values separated by commas, break on the closing bracket.</p> <p>The <code>self.parse_value()</code> call inside <code>parse_array</code> is also recursive. An array element can be another array, or an object, or anything else. The mutual recursion between <code>parse_value</code>, <code>parse_object</code>, and <code>parse_array</code> is what handles arbitrary nesting depth correctly.</p> <h3 id="the-top-level-parse-function">The Top-Level <code>parse</code> Function</h3> <p>Now we wire everything together:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> parse</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">tokens</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Token</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> parser</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Parser</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>tokens</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> value</span><span style="color: #94E2D5;"> =</span><span> parser</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">parse_value</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> value</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Note we changed the signature from <code>parse(tokens: &amp;[Token])</code> to <code>parse(tokens: Vec&lt;Token&gt;)</code>, we're passing ownership into the parser, which is cleaner since the parser owns its token list.</p> <h3 id="displaying-results">Displaying Results</h3> <p>We need a way to verify our parser works. Let's write a function that converts a <code>JsonValue</code> back into a JSON string. This is recursive too and it's a great demonstration of how naturally the recursive enum structure enables recursive processing:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> display</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">value</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">JsonValue</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> value</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Null</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;null&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Bool</span><span style="color: #9399B2;">(</span><span style="color: #F38BA8;">true</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;true&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Bool</span><span style="color: #9399B2;">(</span><span style="color: #F38BA8;">false</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;false&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Number</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> n</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Str</span><span style="color: #9399B2;">(</span><span>s</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #F5C2E7;">\&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #F5C2E7;">\&quot;</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> s</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Array</span><span style="color: #9399B2;">(</span><span>elements</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> result</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;[&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> first</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> element</span><span style="color: #CBA6F7;"> in</span><span> elements</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> !</span><span>first</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push_str</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;, &quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push_str</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #89B4FA;font-style: italic;">display</span><span style="color: #9399B2;">(</span><span>element</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span> first</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">]</span><span style="color: #9399B2;">&#39;);</span></span> <span class="giallo-l"><span> result</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> JsonValue</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Object</span><span style="color: #9399B2;">(</span><span>pairs</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> result</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;{&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> first</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>key</span><span style="color: #9399B2;">,</span><span> value</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span> pairs</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> !</span><span>first</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push_str</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;, &quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push_str</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #89B4FA;font-style: italic;">format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #F5C2E7;">\&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #F5C2E7;">\&quot;</span><span style="color: #A6E3A1;">: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> key</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> display</span><span style="color: #9399B2;">(</span><span>value</span><span style="color: #9399B2;">)));</span></span> <span class="giallo-l"><span> first</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">}</span><span style="color: #9399B2;">&#39;);</span></span> <span class="giallo-l"><span> result</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>display</code> takes <code>&amp;JsonValue</code>, a reference, so it doesn't consume the value. For the simple variants it produces strings directly. For <code>Array</code> and <code>Object</code> it loops over the children, recursively calling <code>display</code> on each one, building up the output string with proper separators.</p> <p>The <code>first</code> boolean flag is how we handle comma separation without a trailing comma, we skip the comma before the first element and add it before every subsequent one.</p> <h2 id="updating-main-function">Updating Main function</h2> <p>Lets update the main function to add some test json and check if our parser is working correctly or not.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> tests</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;null&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;true&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;42&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;-3.14&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;&quot;hello world&quot;&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;[]&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;{}&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;[1, 2, 3]&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;{&quot;name&quot;: &quot;alice&quot;, &quot;age&quot;: 30, &quot;active&quot;: true}&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;{&quot;scores&quot;: [95, 87, 100], &quot;info&quot;: {&quot;city&quot;: &quot;delhi&quot;, &quot;zip&quot;: null}}&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;[&quot;hello\nworld&quot;, &quot;tab\there&quot;, &quot;\u0041\u0042\u0043&quot;]&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> ];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> input</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>tests</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> tokens</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> tokenize</span><span style="color: #9399B2;">(</span><span>input</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> value</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> parse</span><span style="color: #9399B2;">(</span><span>tokens</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Input: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> input</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Output: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> display</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>value</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Run it with <code>cargo run</code> and you should see:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Input:</span><span style="color: #A6E3A1;"> null</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Output:</span><span style="color: #A6E3A1;"> null</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Input:</span><span style="color: #FAB387;"> true</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Output:</span><span style="color: #FAB387;"> true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Input:</span><span style="color: #FAB387;"> 42</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Output:</span><span style="color: #FAB387;"> 42</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Input:</span><span style="color: #A6E3A1;"> -3.14</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Output:</span><span style="color: #A6E3A1;"> -3.14</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Input:</span><span style="color: #A6E3A1;"> &quot;hello world&quot;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Output:</span><span style="color: #A6E3A1;"> &quot;hello world&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Input:</span><span> []</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Output:</span><span> []</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Input:</span><span style="color: #A6E3A1;"> {}</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Output:</span><span style="color: #A6E3A1;"> {}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Input:</span><span> [1,</span><span style="color: #A6E3A1;"> 2, 3]</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Output:</span><span> [1,</span><span style="color: #A6E3A1;"> 2, 3]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Input:</span><span style="color: #A6E3A1;"> {&quot;name&quot;: &quot;alice&quot;, &quot;age&quot;: 30, &quot;active&quot;:</span><span style="color: #FAB387;"> true</span><span style="color: #A6E3A1;">}</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Output:</span><span style="color: #A6E3A1;"> {&quot;name&quot;: &quot;alice&quot;, &quot;age&quot;: 30, &quot;active&quot;:</span><span style="color: #FAB387;"> true</span><span style="color: #A6E3A1;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Input:</span><span style="color: #A6E3A1;"> {&quot;scores&quot;:</span><span> [95,</span><span style="color: #A6E3A1;"> 87, 100], &quot;info&quot;: {&quot;city&quot;: &quot;delhi&quot;, &quot;zip&quot;: null}}</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Output:</span><span style="color: #A6E3A1;"> {&quot;scores&quot;:</span><span> [95,</span><span style="color: #A6E3A1;"> 87, 100], &quot;info&quot;: {&quot;city&quot;: &quot;delhi&quot;, &quot;zip&quot;: null}}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Input:</span><span> [</span><span style="color: #A6E3A1;">&quot;hello\nworld&quot;</span><span>,</span><span style="color: #A6E3A1;"> &quot;tab\there&quot;, &quot;\u0041\u0042\u0043&quot;]</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Output:</span><span> [</span><span style="color: #A6E3A1;">&quot;hello</span></span> <span class="giallo-l"><span style="color: #A6E3A1;">world&quot;</span><span>,</span><span style="color: #A6E3A1;"> &quot;tab here&quot;, &quot;ABC&quot;]</span></span></code></pre> <p>The last test shows escape sequences working, <code>\n</code> becomes a real newline, <code>\t</code> becomes a real tab, and <code>\u0041\u0042\u0043</code> decodes to <code>ABC</code>.</p> <h2 id="conclusion">Conclusion</h2> <p>That's it. You've built a real, working JSON parser from scratch. It was a long one but I hope you learned a lot. In the next one we are going to build a TOML config parser and learn about error handling in detail, we will understand about <code>Result&lt;T, E&gt;</code> and stop using <code>unwrap</code> calls. See you soon.</p> 2026-04-18T00:00:00+00:00 2026-04-18T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/crito/ <p>The trial is over. Socrates has been convicted and sentenced to death. But he is not dead yet.</p> <p>In Athens at this time, there was a religious custom. Every year, a state galley sailed to the island of Delos for a sacred mission, and no executions were permitted while the ship was away. The ship had left the day before the trial, which means Socrates gets roughly a month in prison before his execution.</p> <p>The Crito takes place in that prison, early one morning, very close to the end. His old friend Crito has come to tell him the ship is almost back and to make one final argument: Socrates should escape.</p> <p>Socrates refuses. The question is why, and whether he is right.</p> <h2 id="the-setup">The Setup</h2> <p>Crito arrives before dawn. He has bribed the prison warder and slipped in. He watches Socrates sleeping peacefully and does not wake him. When Socrates wakes on his own, he is not surprised to see Crito. He tells him about a dream he had: a beautiful woman in white told him he would arrive at fertile Phthia on the third day. This is a quote from Homer, where Achilles says his ships will reach home in three days. Socrates takes it to mean his soul will reach its home in three days, which means the ship has not arrived yet and will not arrive today.</p> <p>Crito confirms the ship is expected today. Socrates says it will be tomorrow. Either way, time is very short.</p> <h2 id="crito-s-arguments-for-escaping">Crito's Arguments for Escaping</h2> <p>Crito makes several arguments. Lets go through each one.</p> <p><strong>His own reputation.</strong> If Socrates dies when he could have been saved, people will think Crito valued money more than his friend. He will be blamed for not doing enough.</p> <p>Socrates dismisses this immediately. Why should we care what the majority thinks? The majority cannot make a man wise or foolish. They inflict things haphazardly. What matters is what reasonable, informed people think, not the crowd.</p> <p><strong>The money is there.</strong> Crito says not to worry about cost. He has the money, and so do friends like Simmias and Cebes. There are people in other cities like Thessaly who would welcome Socrates and keep him safe.</p> <p>Socrates does not directly respond to this but it becomes irrelevant once he establishes the core argument.</p> <p><strong>Socrates is abandoning his children.</strong> This is Crito's most emotionally charged point. By accepting death, Socrates is leaving his sons, one a teenager and two younger, effectively as orphans. He had a choice. He could have proposed exile as his penalty at the trial. He did not. Now he is choosing death when escape is possible. That is not courage, Crito says. It is the easy path. A good and courageous man would choose to stay alive for his children.</p> <p><strong>It would be unjust to stay.</strong> Crito also argues that it would actually be unjust for Socrates to accept the verdict. It hands a victory to his enemies. It abandons his friends. It means accepting a result that was itself unjust.</p> <h2 id="socrates-framework">Socrates' Framework</h2> <p>Before addressing any of this directly, Socrates lays down the principle he will reason from. He says he is not about to start listening to different things just because he is in danger of death. His principles are the same as they have always been.</p> <p>The first principle: <strong>you should only follow the opinions of those who know, not the opinions of the majority</strong>. He walks Crito through an example. A man who is serious about physical training listens to his trainer, not to the crowd. The crowd's praise and blame do not determine what is actually good for his body. The expert's judgment does. The majority can sometimes put you to death, sure. But they cannot make something true or false, right or wrong. The one whose opinion matters is the one with genuine knowledge of the subject.</p> <p>The second principle: <strong>the most important thing is not life, but the good life</strong>. And the good life, the beautiful life, and the just life are the same thing. Crito agrees with both of these.</p> <p>This means the question is not "will Socrates survive?" but "will escaping be just or unjust?" Everything else, reputation, money, children, follows from that.</p> <h2 id="the-voice-of-the-laws">The Voice of the Laws</h2> <p>Here is where the Crito gets genuinely original. Socrates says: imagine the Laws of Athens came to us right now and spoke. What would they say?</p> <p>He then gives them a voice and lets them make the argument against escaping. This is one of the earliest examples of a social contract argument in philosophy.</p> <p>The Laws say this: <strong>You cannot destroy us just because a court made an error in your case.</strong></p> <p>Their argument has several layers.</p> <p>First, the Laws point out what they have done for Socrates. They governed the marriage of his parents, which is how he was born. They supervised his upbringing and education. They gave him everything he has. In that sense, he is their offspring. And you do not get to strike back at your parents just because they discipline you unfairly on one occasion.</p> <p>Second, the Laws gave him a real choice. Every Athenian, when they reach adulthood, can look at how the city is run and decide to leave. No one is forced to stay. If you stay, you implicitly agree to live under the laws. Socrates stayed for 70 years. He barely left the city except for military service. He raised a family here. He chose this city more completely than almost any other Athenian. That choice is a binding agreement.</p> <p>Third, the Laws point out that Socrates had a chance to propose exile as his penalty at the trial and did not. He chose to stay and fight. He even said in court he would rather die than stop doing philosophy. He cannot now, when the result has gone against him, decide exile is acceptable after all.</p> <p>Fourth, the Laws ask what happens if he escapes. He goes to a nearby well-governed city like Thebes or Megara and arrives as a man who broke his agreement with Athens. Anyone who cares about the law will see him as a threat, someone who destroys the very thing that holds cities together. Or he goes to Thessaly, where Crito has friends, and lives out his days eating at banquets and telling people how he escaped in a disguise. What happens to his philosophical life then? And what happens to his children, who will either follow him as strangers in a foreign city or stay behind without him, with friends theoretically looking after them? The Laws point out that those same friends will look after the children whether Socrates goes to Thessaly or to the underworld, so his children are not actually a good reason to escape.</p> <p>Fifth, and most sharply: if Socrates escapes, he has done a wrong in return for a wrong. He was wronged by men, not by the Laws. The Laws themselves did not fail him. A court of humans made an unjust decision using a just process. Responding to that by escaping means attacking the process itself, not the people who abused it.</p> <h2 id="the-core-principle-no-retaliation">The Core Principle: No Retaliation</h2> <p>Throughout this whole argument, Socrates has established one underlying rule that he keeps returning to. <strong>You should never do wrong in return for wrong done to you.</strong></p> <p>This was not a commonly accepted view in ancient Athens. The traditional Greek idea of justice was helping your friends and harming your enemies. Crito would have been very comfortable with that framing. But Socrates rejects it completely. Doing harm is always wrong, regardless of what was done to you first. Retaliation does not become just because the original injury was real.</p> <p>This is why the personal arguments about reputation, money, and children do not move him. All of those are arguments about consequences, about what will happen to various people. Socrates has already decided to reason from principle. If escaping is unjust, no consequence makes it right.</p> <p>And then he adds something that shows he really means it. He says that the people who hold this view and the people who do not share no common ground. They inevitably despise each other's positions. He is not trying to win an argument about whether retaliation is generally a bad idea. He is identifying a genuine philosophical divide. If Crito agrees that you should never do wrong in return for wrong, then the rest of the argument follows. If he does not, they have nothing to talk about on this subject.</p> <p>Crito agrees with the principle.</p> 2026-04-17T00:00:00+00:00 2026-04-17T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/apology/ <p>The Apology is not an apology. The Greek word <em>apologia</em> means defense speech, and that is exactly what this is. Socrates does not apologize for anything. He stands in front of a jury of 501 Athenians, faces a death sentence, and spends the entire time telling them they are wrong.</p> <p>He is found guilty and executed.</p> <p>This is the second dialogue in Plato's complete works, right after the Euthyphro. In the Euthyphro, Socrates was on his way into court. Now we are inside the court, watching the trial happen.</p> <h2 id="the-setup">The Setup</h2> <p>Athens, 399 BC. Socrates is 70 years old. Three men have brought charges against him: Meletus, Anytus, and Lycon. The formal charge is impiety, specifically that he does not believe in the gods the city believes in, that he introduces new spiritual beings, and that he corrupts the youth.</p> <p>The jury is 501 ordinary Athenian citizens, randomly selected. A majority vote determines guilt. Then there is a second vote on the penalty.</p> <p>Socrates opens by telling the jury that he will speak plainly, the way he talks in the marketplace, and asks them to judge him on what he says and not on how he says it. He warns them not to create a disturbance if his manner seems unusual. This is his first appearance in a lawcourt.</p> <h2 id="two-sets-of-accusers">Two Sets of Accusers</h2> <p>Before addressing the formal charges, Socrates says there are actually two sets of accusers he needs to deal with.</p> <p>The recent accusers are Meletus and his associates. But there are older accusers, people who have been spreading a reputation about him for years. They say he is a wise man who studies things in the sky and below the earth, makes the worse argument the stronger, and teaches these things to others. Socrates says these old accusers are actually the more dangerous ones. They got to the jurors when they were young, when they would most readily believe, and there was no one there to refute them.</p> <p>He also points to Aristophanes, the comedian, whose play <em>Clouds</em> portrayed a character called Socrates swinging in a basket and talking nonsense about the heavens. That image has stuck in people's minds for years.</p> <p>So before he even gets to Meletus, Socrates has to fight a reputation built up over decades by people he cannot even identify or cross-examine.</p> <h2 id="what-actually-caused-all-this">What Actually Caused All This</h2> <p>Socrates says his reputation for wisdom comes from something very specific. Here is the story.</p> <p>His friend Chaerephon once went to the oracle at Delphi and asked whether anyone was wiser than Socrates. The oracle said no. When Socrates heard this, he was puzzled. He knew he had no great wisdom. So why would the god say this?</p> <p>He decided to investigate by going to people who were considered wise and testing whether they actually were. First he went to politicians. He found that the ones with the greatest reputations were the most deficient, while they themselves thought they knew a great deal. Socrates concluded that he was slightly better off than them, because at least he did not think he knew things he did not know.</p> <p>Then he went to the poets. He took their best work and asked them what they meant. He found that almost anyone could explain the poems better than the poets themselves. They did not compose from knowledge but from some kind of inspiration, like seers. And yet they thought themselves very wise in all matters because of their poetry.</p> <p>Finally he went to the craftsmen. They did know things he did not know, and in that they were wiser. But they made the same mistake as the poets: because they were skilled at their craft, they assumed they were wise about everything else too.</p> <p>After all this investigation, Socrates arrived at an interpretation of the oracle. The god is not saying Socrates is literally the wisest person. He is using Socrates as an example of someone who understands that his wisdom is worthless. <strong>Human wisdom is worth little or nothing.</strong> The one who is wisest is the one who, like Socrates, knows that he does not know.</p> <p>This investigation is also why people hate him. The people he exposed in front of bystanders became angry, not with themselves but with Socrates. They started spreading the accusations that Meletus eventually formalized. Meletus speaks for the poets, Anytus for the craftsmen and politicians, Lycon for the orators.</p> <h2 id="dismantling-meletus">Dismantling Meletus</h2> <p>Socrates now cross-examines Meletus directly, which is where the dialogue gets sharp.</p> <p><strong>On corrupting the youth.</strong> Socrates asks Meletus who improves the youth. Meletus eventually says everyone does: the jurymen, the assembly members, all the Athenians. Socrates uses a horse-breeding example to expose the absurdity. With horses, one person or very few know how to improve them. The majority, if they have horses and use them without knowing what they are doing, corrupt them. Surely the same is true with people. The claim that only one man in all of Athens corrupts the youth while everyone else improves them is not just false, it is incoherent.</p> <p>He then pushes further. Does Socrates corrupt them deliberately or unwillingly? Meletus says deliberately. Socrates says that cannot be right. If I deliberately make the people around me worse, I risk being harmed by them myself. No one makes others worse on purpose. So either I do not corrupt them, or I do so unwillingly. If unwillingly, the law does not bring people to court for that. It requires you to take them aside privately and instruct them. Meletus never did that.</p> <p><strong>On not believing in gods.</strong> Socrates shows that Meletus has contradicted himself. Meletus says Socrates does not believe in gods at all. But the formal charge also mentions that he introduces new spiritual beings. Does anyone believe in spiritual activities but not in spirits? And if he believes in spirits, which are either gods themselves or the children of gods, how can he simultaneously not believe in gods? Meletus is either saying Socrates is guilty of not believing in gods and of believing in gods, which is a contradiction. He has made this deposition either to test Socrates or because he genuinely could not find any real wrongdoing.</p> <h2 id="why-he-will-not-stop">Why He Will Not Stop</h2> <p>Socrates says something important here. Even if the jury offers to acquit him on the condition that he stop doing philosophy, he will refuse. He is not being stubborn. He genuinely believes he cannot stop, because stopping would mean disobeying the god who commanded him to examine himself and others.</p> <p>And then he says the thing that probably sealed his fate:</p> <blockquote> <p>The unexamined life is not worth living for men.</p> </blockquote> <p>He compares himself to a gadfly sent by the god to sting a great but sluggish horse into action. The city is the horse, and he is the gadfly. If they kill him, they will sleep undisturbed. Another gadfly will not easily come along.</p> <p>He also explains why he never went into public life. His <strong>divine sign</strong>, a kind of inner voice, has always stopped him from doing things. It always says no, never yes. It stopped him from entering politics. He thinks that is fortunate, because a man who genuinely opposes the crowd on matters of justice does not survive long in public life.</p> <p>He gives two examples from his own life to prove he has always acted on principle regardless of personal risk. During the trial of the ten generals after the battle of Arginusae, he was the only member of the presiding council to vote against an illegal mass trial. The crowd wanted blood and shouted him down, but he refused to participate. Under the Thirty Tyrants, when they ordered him and four others to go arrest Leon of Salamis for execution, Socrates simply went home. The others obeyed. He did not. He might have been killed for this but the regime fell shortly after.</p> <h2 id="no-begging-no-dramatics">No Begging, No Dramatics</h2> <p>Socrates explicitly says he will not bring his family into court to cry in front of the jury. He has three sons, one a teenager and two younger children. He will not parade them before the jury to gain sympathy. He thinks this behavior is undignified and inappropriate, especially for someone who has spent his life claiming to care about virtue. If someone with a reputation for wisdom collapses into begging when facing death, it makes the city look bad.</p> <p>He asks the jury to judge him by the facts of the case, not by pity.</p> <h2 id="the-verdict-and-the-penalty">The Verdict and the Penalty</h2> <p>The jury votes guilty. He lost by a relatively narrow margin. He notes that if just 30 votes had gone the other way he would have been acquitted.</p> <p>Meletus proposes the death penalty. Now Socrates has to propose a counter-penalty.</p> <p>He starts by saying what he actually deserves: free meals in the Prytaneum, the magistrates' hall where Athenian olympic victors were honored. He genuinely believes he has been doing the city a great service by going around making people examine their lives. An Olympian victor makes you feel happy, he says. He makes you actually be happy.</p> <p>He knows the jury will take this as arrogance. He is right that they do.</p> <p>He considers the alternatives. A fine? He has no money. Imprisonment? Why would he want to live in prison? Exile? Wherever he goes, he will do the same thing and end up in the same situation. He eventually offers 30 minas, with his friends Plato, Crito, and others standing as guarantors.</p> <p>The jury votes for death.</p> <h2 id="after-the-verdict">After the Verdict</h2> <p>Socrates speaks to both groups separately. To those who voted against him, he says they have not escaped examination. After he is gone, more questioners will come, younger and harsher, and the jury will resent them even more. You cannot escape being held accountable by silencing the person holding you accountable.</p> <p>Then he says something remarkable. His divine sign did not stop him at any point during this trial. Not when he left home, not when he entered the court, not at any moment during his speech. He takes this as a sign that what happened was actually good.</p> <p>He lays out two possibilities for what death is. Either it is complete unconsciousness, like dreamless sleep, in which case it is nothing to fear and may even be pleasant. Or it is a relocation of the soul to another place, where all the famous dead are. In that case it would be an extraordinary opportunity to meet Homer, Hesiod, Odysseus, and the great heroes, and to question them and test whether they are actually wise. Socrates says he would happily die many times over for that chance.</p> <p>He closes by saying a good man cannot be harmed in life or in death. He is not angry with those who convicted him. He only asks one thing: when his sons grow up, if they care more for money or reputation than for virtue, reproach them the way he reproached the Athenians.</p> <p>The last line is this:</p> <blockquote> <p>Now the hour to part has come. I go to die, you go to live. Which of us goes to the better lot is known to no one, except the god.</p> </blockquote> 2026-04-13T00:00:00+00:00 2026-04-13T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/euthyphro/ <p>Plato wrote a bunch of dialogues. The Euthyphro is one of the shortest. In this post, we will understand the <strong>Euthyphro</strong> dialogue.</p> <h2 id="the-setup">The Setup</h2> <p>Athens, 399 BCE. Socrates is at the court of the king-archon because a man named Meletus has indicted him for impiety. Corrupting the youth and inventing new gods.</p> <p>Outside the same court he runs into Euthyphro. Euthyphro is there to file murder charges against his own father. Here is the story. A laborer on the family estate killed a household slave in drunken anger. Euthyphro's father bound the laborer, threw him in a ditch, and sent someone to ask the priests what the correct ritual procedure was. The laborer died in the ditch before the messenger came back. Hunger, cold, and his bonds. Euthyphro believes his father is guilty of murder by negligence and that prosecuting him is the pious thing to do. His entire family thinks he has lost his mind.</p> <p>In Athenian religion, murder caused <strong>pollution</strong> (miasma). If you knowingly kept company with a killer without ritual purification, the pollution spread to you. So Euthyphro is not just making a family decision. He is claiming he has expert, esoteric knowledge of piety, the kind that lets him navigate a case his whole family cannot agree on.</p> <p>Socrates hears this and sees an opportunity. He is facing impiety charges himself. If Euthyphro genuinely knows what piety is, Socrates can learn from him and use that in court. So he asks. What is piety?</p> <p>One thing to understand before we get into the answers. Socrates is not asking for examples of pious actions. He wants the <strong>form</strong>, the single thing present in every pious act and absent in every impious act. Something he can look at like a model and use to evaluate any action at all. This distinction between an instance and a definition is what every single answer in this dialogue misses.</p> <h2 id="definition-1-what-i-am-doing-right-now">Definition 1: What I Am Doing Right Now</h2> <p>Euthyphro says piety is to do what he himself is doing right now. Prosecuting wrongdoers, be it about murder, temple robbery, or anything else, regardless of who they are. And he backs this up with a divine precedent. Zeus himself bound his own father Cronus because Cronus unjustly swallowed his sons. So prosecuting one's father is not crazy. It is what the gods do.</p> <p>Socrates does not even argue about the Zeus example. He just points out the category error. That is one instance of a pious action, not a definition. There are many other pious actions. Giving one case does not tell us what makes any of them pious. What is the <strong>form</strong> that makes all pious actions pious?</p> <p>Euthyphro agrees there are many pious actions and tries again.</p> <h2 id="definition-2-what-is-dear-to-the-gods">Definition 2: What Is Dear to the Gods</h2> <p>Now we get an actual definition. Piety is what is dear to the gods. Impiety is what is not.</p> <p>Socrates says splendid, this is the kind of answer I wanted. Now let us examine whether it is true.</p> <p>He reminds Euthyphro of something Euthyphro already agreed to earlier in the conversation. The gods are in a state of discord. They are at odds with each other. They have enmities and even wars, exactly like the stories the poets tell and the ones embroidered on the robe of Athena carried up to the Acropolis. Euthyphro confirmed all of this is true.</p> <p>So here is the problem Socrates raises. What kinds of things cause disagreement that cannot be settled? Not numbers. If you and I disagree about which number is greater, we just count and resolve it. Not size. We measure. Not weight. We weigh. These disputes get resolved because there are procedures for settling them.</p> <p>But what about the just and the unjust, the beautiful and the ugly, the good and the bad? Those are the things people genuinely fight over and cannot settle, because there is no neutral procedure. And that is exactly what the gods must be disagreeing about too, since they are at odds with each other.</p> <p>So different gods consider different things just, beautiful, good. And each god loves what it considers good and hates the opposite. Which means the same action can be loved by some gods and hated by others. Which means under Definition 2, the same action would be both pious and impious at the same time.</p> <p>Socrates puts it directly. Euthyphro's own action, prosecuting his father, might be pleasing to Zeus but displeasing to Cronus and Uranus, pleasing to Hephaestus but displeasing to Hera. The definition gives you contradictory answers for the same case.</p> <p>Euthyphro tries to escape. He says surely on this particular subject, whether unjust killing must be punished, no gods would disagree with each other.</p> <p>Socrates closes that exit. Think about how humans disagree. Nobody actually disputes the principle that wrongdoers should be punished. What they dispute is the specifics. Did this person actually do wrong? What exactly happened? When? The dispute is always about particular cases, not abstract principles. The gods would be the same. They might agree in the abstract that unjust killers should be punished, but they can still disagree about whether this specific killing was unjust.</p> <p>And even if we grant that all gods agree on Euthyphro's case, that does not save the definition. Because the definition was "what the gods love is pious." Even if all gods agree here, we already showed that the same thing can be loved and hated by different gods in other cases. The definition still produces contradictions.</p> <h2 id="definition-2-revised-what-all-the-gods-love">Definition 2 Revised: What All the Gods Love</h2> <p>Socrates himself proposes the fix. What if we say: piety is what <strong>all</strong> the gods love, impiety is what all the gods hate, and whatever splits divine opinion is neither or both?</p> <p>Euthyphro agrees. Yes, that is what he would say.</p> <p>Socrates says good, lets examine it. And then he asks the most famous question in the dialogue.</p> <blockquote> <p>Is the pious being loved by the gods because it is pious, or is it pious because it is being loved by the gods?</p> </blockquote> <p>This is the <strong>Euthyphro Dilemma</strong>. Two options.</p> <p><strong>Option A.</strong> Piety is prior. Things are pious independently, and the gods love them because they are pious. The gods are tracking something that already has value.</p> <p><strong>Option B.</strong> Divine love is prior. Things are pious because the gods love them. There is no independent standard. The gods' approval is what makes something pious.</p> <p>Euthyphro does not understand the question at first, so Socrates works through it carefully using simpler examples. Something carried is a "carried thing" because it is being carried, not the other way around. Something seen is a "thing seen" because it is being seen. Something led is a "thing led" because it is being led. The state is always downstream of the act. A thing does not get carried because it is "a carried thing." It becomes "a carried thing" because something carries it.</p> <p>The same goes for love. A thing is "something loved" because it is being loved by someone. That status comes from the love, not the other way around.</p> <p>Now. Euthyphro already agreed that the pious is being loved because it is pious. That means piety is the prior thing, the reason the love happens. But "god-loved" works in the opposite direction, it gets its character from the loving. So the two are pointing in opposite directions and cannot be the same thing.</p> <p>Conclusion: "god-loved" is a property pious things have as a result of being pious. It is not what piety is. Socrates says it plainly. You did not tell me what the pious is. You told me an <strong>affect</strong> of it, a quality it happens to have. The pious is god-loved, sure. But that tells me nothing about what piety actually is in itself.</p> <p>At this point Euthyphro basically admits defeat on this one. He says whatever proposition they put forward goes around and refuses to stay put. Socrates jokes that his definitions behave like the statues of Daedalus, the legendary craftsman who made statues that could walk. They move and will not stay in place. Euthyphro says no, it is Socrates who is the Daedalus here, making everything move. Socrates says fair enough, but he would rather have stable answers and is clever without wanting to be. Lets keep going.</p> <h2 id="definition-3-piety-is-the-part-of-justice-concerned-with-the-care-of-the-gods">Definition 3: Piety Is the Part of Justice Concerned with the Care of the Gods</h2> <p>Socrates pushes forward and gets Euthyphro to agree that everything pious is also just. But is everything just also pious? Not necessarily. Piety might be a <strong>part</strong> of justice, not all of it.</p> <p>He explains this with an example about fear and shame. A poet wrote: "where there is fear there is also shame." Socrates disagrees. People fear disease and poverty but they are not ashamed of those things. So fear does not always come with shame. But the reverse is true. Where there is shame, there is always fear, because anyone who feels shame is afraid of having a reputation for wickedness. So shame is a <strong>part of</strong> fear, not equal to it. Fear covers more ground. Wherever you have shame you have fear, but not the other way around.</p> <p>Same structure applies to piety and justice. Wherever you have piety you have justice, but not wherever you have justice do you have piety. Piety is a part of justice.</p> <p>So now the question is: which part? If the pious is a part of the just, what specific part?</p> <p>Euthyphro answers. The part of justice concerned with the <strong>care of the gods</strong> is piety. The part concerned with the care of men is the rest of justice.</p> <p>Socrates likes this. But he immediately asks: what do you mean by care? In every other domain, care aims at the benefit of the thing being cared for. Horse breeders care for horses and horses become better. Hunters care for dogs. Farmers care for cattle. Care improves the object. So does piety improve the gods? Do our pious actions make the gods better?</p> <p>Euthyphro says absolutely not. That is not what he means.</p> <h2 id="definition-3a-piety-is-the-service-slaves-give-their-masters">Definition 3a: Piety Is the Service Slaves Give Their Masters</h2> <p>Euthyphro adjusts. The kind of care he means is not improvement-care. It is <strong>service</strong>. The kind a slave gives a master.</p> <p>Socrates accepts this framing and asks the next question. Every service aims at producing something. Service to doctors produces health. Service to shipbuilders produces ships. Service to housebuilders produces houses. Every service has a goal it is working toward. So what excellent goal are the gods working toward that our service helps them achieve?</p> <p>Euthyphro says the gods achieve many fine things.</p> <p>Socrates says yes, so do generals. But you can easily say the main thing generals are working toward is victory in war. Farmers achieve many things too, but the main point is producing food. What is the main point of what the gods are doing, that our service contributes to?</p> <p>Euthyphro cannot answer. He says it is a considerable task to acquire any precise knowledge of these things.</p> <h2 id="definition-3b-piety-is-knowing-how-to-pray-and-sacrifice">Definition 3b: Piety Is Knowing How to Pray and Sacrifice</h2> <p>Pushed further, Euthyphro gives something more concrete. If a man knows how to say and do what is <strong>pleasing to the gods</strong> at prayer and sacrifice, those are pious actions, the kind that preserve private households and public affairs of state. Their opposites are impious and destroy everything.</p> <p>Socrates compresses this. So piety is the knowledge of how to sacrifice and pray? To sacrifice is to make a gift to the gods. To pray is to beg from the gods. So piety is the knowledge of how to give to and beg from the gods correctly.</p> <p>Euthyphro agrees.</p> <h2 id="definition-3c-piety-is-a-trading-skill-between-gods-and-men">Definition 3c: Piety Is a Trading Skill Between Gods and Men</h2> <p>Socrates follows the logic one more step. If piety is knowing how to correctly give to and receive from the gods, it sounds like a kind of <strong>trading skill</strong>, an art of exchange between gods and men.</p> <p>Euthyphro reluctantly agrees. Trading, yes, if you want to call it that.</p> <p>Then Socrates asks the trap question. What do the gods actually get from us in this exchange? We receive everything good from the gods. What do they receive from us? Euthyphro says we give them honor, reverence, and what pleases them.</p> <p>Socrates closes it. So the pious is what pleases the gods.</p> <p>But that is the same as "what is dear to the gods."</p> <p>We are right back at Definition 2. After the entire detour through care, service, prayer, sacrifice, and exchange, the argument has made a full circle and arrived exactly where it started. At a definition that was already shown to fail.</p> <h2 id="the-end">The End</h2> <p>Euthyphro says he is in a hurry and has to go.</p> <p>This is intentional. The dialogue is <strong>aporetic</strong>, from the Greek <em>aporia</em>, without a path forward. Euthyphro entered the conversation certain enough about piety to prosecute his own father on that certainty. He leaves unable to say what that certainty is actually based on.</p> <p>Socrates is not satisfied. He says Euthyphro has cast him down from a great hope. He wanted to learn the nature of piety and use it to defend himself against Meletus. Now he has nothing. The dialogue failed to produce what it was looking for.</p> <p>This is the first in a series reading through Plato's complete works. Next: the Apology</p> 2026-04-13T00:00:00+00:00 2026-04-13T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/lessons-in-stoicism/ <p>John Sellars is a philosophy lecturer at Royal Holloway and one of the people behind Modern Stoicism, the group that runs Stoic Week. This book is short, around 100 pages, and it does one thing. It walks you through the core ideas of the three major Roman Stoics, Seneca, Epictetus, and Marcus Aurelius, and explains what they were actually saying without making it boring.</p> <p>The three could not have lived more different lives. Seneca was a tutor to Emperor Nero, a member of the Roman elite, and ended his life with a forced suicide. Epictetus was a slave from Asia Minor who was eventually freed, banished from Rome, and opened a philosophy school in Greece. Marcus Aurelius was the Emperor of Rome. And yet all three embraced the same philosophy.</p> <p>By the time these three were writing, Stoicism was already hundreds of years old. It started in Athens around 300 BC with a man named Zeno from Cyprus, who lectured at the Painted Stoa, a covered colonnade, and gathered followers who became known as Stoics. None of the early Stoic writings survived. What we have comes almost entirely from these three Romans.</p> <p>The book is structured around seven lessons. Lets go through each one.</p> <h2 id="chapter-1-the-philosopher-as-doctor">Chapter 1: The Philosopher as Doctor</h2> <p>Epictetus described the philosopher as a doctor and the philosophy school as a hospital for souls. This is not a metaphor he invented. It traces back to Socrates, who argued that the job of philosophy is to take care of your soul the same way a physician takes care of your body. By soul here they mean your mind, thoughts, and beliefs, not anything supernatural.</p> <p>The core argument Socrates made, which the Stoics took up, is that material things are <strong>value-neutral</strong>. Money is neither good nor bad. Whether it benefits or harms depends entirely on the character of the person who has it. A good person uses money to do good things. A bad person uses it to cause harm. So the real source of value is not in the money itself but in the character of the person who holds it.</p> <p>This led to the Stoic concept of <strong>indifferents</strong>. Only an excellent, virtuous character is genuinely good. Only a vicious character is genuinely bad. Everything else, wealth, health, reputation, success, is an indifferent. Not good or bad in itself.</p> <p>But the Stoics were not like the Cynics. Diogenes of Sinope, the most famous Cynic, lived in a barrel and threw away his cup after seeing a child drink water with its hands. He praised poverty and rejected possessions entirely. Zeno, the first Stoic, found this too extreme. If money is truly neutral, why treat poverty as better than wealth?</p> <p>Instead, Zeno introduced the idea of <strong>preferred indifferents</strong>. All else being equal, we naturally prefer to be healthy rather than sick, wealthy rather than broke, respected rather than despised. That is completely rational and nothing to feel bad about. But and this is the key point, you should never compromise your character to get these things. A virtuous character is the only truly good thing. Chasing money or fame at the cost of your integrity means trading the only real good for something that is not actually good at all.</p> <p>So what does having good character actually mean? For the Stoics it means being wise, just, courageous and moderate. These are the four cardinal virtues. This is what it means to be a good human being, which the Stoics thought about the same way you might think about a good knife. A good knife cuts well. A good human, as a social animal, behaves well toward others.</p> <h2 id="chapter-2-what-do-you-control">Chapter 2: What Do You Control?</h2> <p>This is probably the most well-known Stoic idea and it comes directly from Epictetus. The Handbook of Epictetus opens with this.</p> <p>The things within our power: our judgements, impulses, and desires. Pretty much everything else is not within our power. Our bodies, our possessions, our reputation, our worldly success. All of these are ultimately outside our control.</p> <p>Now, that sounds like Epictetus is saying we have almost no control over anything. But he is actually saying the opposite. Because <strong>judgements are the source of everything</strong>. We see something, judge it as good, which creates a desire, which drives us to pursue it. The whole chain of behavior starts with a judgement. If you master your judgements, you master your desires and your actions. Your happiness becomes entirely your own.</p> <p>Marcus Aurelius put this into practice. He would pause before evaluating seemingly desirable things and think about them physically. A fine meal is just the dead body of a pig or a fish. An expensive car is just a lump of metal and plastic. Whatever value these things appear to have is something we project onto them with our judgements. It is not in the things themselves.</p> <p>Epictetus makes another important point. If you tie your happiness to something outside your control, you have effectively handed your happiness over to forces that do not care about you. A romantic relationship, a career goal, a specific level of wealth. If any of these goes wrong and it might because you cannot control outcomes, only actions, then your wellbeing collapses with it.</p> <p>The Stoics use the archer as an example here. Antipater, a Stoic writing before Epictetus, pointed out that even an expert archer sometimes misses because the wind might blow the arrow off course. The archer cannot control that. What the archer can control is the quality of the shot itself. So make your goal doing the best you can, not hitting the target. Then nothing can prevent you from succeeding at your actual goal.</p> <p>Marcus Aurelius extends this to the whole of Nature. Everything changes. Nothing stays stable. He reminds himself of this constantly in the Meditations. All we can do is accept what happens that is not within our control and direct our efforts at what is.</p> <p>Epictetus says this vigilance cannot be occasional. It has to be constant. He uses a sailing image. It is much easier for a mariner to wreck a ship than to keep it sailing safely. A momentary loss of attention produces disaster. Philosophy has to be a daily practice, not something you dip into when life gets hard.</p> <p>Both Marcus and Seneca built reflection into their routines. Marcus would do morning reflection to prepare for the day. Seneca would do evening reflection to review what he did well, where he slipped, and what he could do better.</p> <h2 id="chapter-3-the-problem-with-emotions">Chapter 3: The Problem with Emotions</h2> <p>Someone came to Epictetus's school and complained about his brother, who had become angry with him. What could he do about his brother's anger? Epictetus said nothing. You cannot do anything about it. The only person who can change the brother's anger is the brother.</p> <p>But Epictetus did not stop there. He shifted attention to what the man could actually control, his own reaction. The man was upset about his brother's anger and that upset was something the man himself could address. The real problem was not the brother. It was the judgement the man had made about the brother's anger.</p> <p>The Stoic position on emotions is often misunderstood. The word stoic in everyday English means unfeeling and cold, which is not what the ancient Stoics meant. They did not want to eliminate all emotional responses. They wanted to eliminate the harmful ones. Anger, resentment, jealousy, possessiveness, obsession, perpetual fear.</p> <p>The central claim is that <strong>emotions are the product of judgements</strong>. Because they come from judgements, and we control our judgements, we are responsible for our emotions. Not responsible for having involuntary physical reactions, but responsible for whether those reactions become full emotions.</p> <p>Chrysippus compared having an emotion to running so fast you can no longer stop. Once an emotion has momentum, you are out of control and you cannot just switch it off. Seneca extended this. He likens being angry to having been thrown off a building and hurtling toward the ground. The emotion takes over the whole mind. This is what the Stoics warn against.</p> <p>Seneca draws three stages. First, an <strong>involuntary first movement</strong>. A shock, a flinch, a sudden nervousness, even tears. These are physiological responses, not emotions in the Stoic sense. They are not within our control and that is fine. Second, a <strong>judgement</strong> in response to what happened. This is within our control and this is where the critical moment is. Third, an <strong>emotion</strong> that once formed is out of our control and must simply subside on its own.</p> <p>The space between stage one and stage two is where the work happens. Epictetus says if someone insults you, pause before reacting. Ask whether what they said is true or false. If true, they have pointed out a fault you can now fix. They have helped you. If false, they are simply wrong and the only one being harmed is themselves. Either way, you suffer no harm from the insult itself. The only way you can be harmed is if you let it produce anger.</p> <p>What about love? Are the Stoics saying to eliminate that too? No. A parent's love for a child is a natural instinct, not an irrational emotion. Healthy romantic relationships built on companionship and natural affection are fine. What they wanted to avoid were the destructive emotional attachments, possessiveness, jealousy, obsession. And even with grief, the Stoics acknowledge that first movements like crying are natural. What they want to prevent is grief becoming a debilitating, consuming habit of mind.</p> <h2 id="chapter-4-dealing-with-adversity">Chapter 4: Dealing with Adversity</h2> <p>Seneca's own life was a test case. His son died. He was exiled to Corsica for nearly a decade. He was forced to become Nero's tutor on condition of being allowed back. He watched close friends die. He was eventually forced to commit suicide on Nero's orders. His wife insisted on dying with him. Neither died quickly.</p> <p>His essay On Providence asks why bad things happen. His first answer is that nothing external is genuinely bad. Events are neither good nor bad in themselves. Someone who has internalized this will not rush to judge something terrible as terrible. They will simply accept what is.</p> <p>But he goes further than that. He argues we should actually welcome adversity as a training exercise. He uses a wrestling image. A wrestler only improves by facing tough opponents. An easy opponent teaches nothing and allows skills to atrophy. Adversity in life works the same way. It gives you a chance to demonstrate your virtues and strengthen them.</p> <p>He also makes the inverse argument. Excessive good fortune is bad for you. If everything always goes your way, you are never tested, never pushed to develop patience, courage, or resilience. Unending luxury breeds laziness, complacency, and greed. Real misfortune, Seneca says, is a life with no difficulty at all.</p> <p>Then there is the <strong>premeditation of future evils</strong>, an idea advocated by Chrysippus and developed by Seneca. The idea is to regularly reflect on potentially bad things that could happen, so that you are better prepared to handle them if they do. Seneca wrote a letter of consolation to his friend Marcia, who had been consumed by grief for three years after the death of her son. Part of her problem, Seneca said, was that she had never reflected on the possibility of her son dying. But everyone dies. This is not something that might happen. It is something that must happen.</p> <p>Grief hits hardest when it is unexpected. Seneca lists the uncomfortable truths. All our loved ones will die, and could do so at any moment. Whatever security or prosperity we have could be taken away at any moment by forces outside our control. When we think things are tough, they can always get worse. Not thinking about these things does not protect you from them. It just means you will be blindsided when they happen.</p> <p>This is not pessimism. It is practical preparation. Seneca does not say you should go looking for adversity or pretend to welcome every hardship cheerfully. In one letter to Lucilius he is clear he does not agree with those who charge straight into difficult situations as a matter of principle. The goal is simply to be prepared so that when adversity comes, and it will come, you are not completely undone by it.</p> <h2 id="chapter-5-our-place-in-nature">Chapter 5: Our Place in Nature</h2> <p>Marcus Aurelius spent the later years of his reign on military campaigns near modern-day Vienna. He kept a private notebook during those campaigns, writing to himself to process his experiences and prepare for the next day. That notebook is the Meditations.</p> <p>One of its central themes is how small we are.</p> <p>Marcus imagines looking down at the earth from a great height, as astronauts have since actually done, and seeing how tiny each country is, how minuscule each city. From that perspective, the people living in those cities with their full lives of cares and concerns are practically nothing. He also reflects on time. Each human life is a tiny fraction of the boundless abyss of time.</p> <p>This is not nihilism. The Stoic view is that Nature is not blind or chaotic. It is a single living organism, ordered and animated by a rational principle they called God or Zeus, though not in the personal sense. This rational principle within Nature is what accounts for the order and patterns we observe. The Stoics identified this with fate, which they meant in a physical sense, a chain of causes and effects. Physics, not superstition.</p> <p>Sellars compares this to the Gaia hypothesis of James Lovelock, the idea that life on earth functions as a single self-regulating system, including organic and inorganic matter together. The Stoics had a remarkably similar view. Nature as a unified, intelligent organism, not a collection of isolated parts.</p> <p>What does this mean practically? It means that the events of your life are part of a causal chain. When something happens, given all the causes at play at that moment, it could not have turned out otherwise. Wishing it had turned out differently is not just futile, it is a failure to understand how the world works.</p> <p>Marcus puts it this way. Nature gives all and takes all back. The person educated into humility says to Nature: give what you will, take back what you will. Not in defiance, but as a loyal subject.</p> <p>Marcus was honest enough to acknowledge uncertainty about whether Nature is truly providential, a rational order working for our benefit, or simply atoms colliding in a void. His view was that for practical purposes it does not matter. Whether the universe is guided by a providential deity, a cybernetic feedback system, or pure chance, the correct response is the same. Accept what happens and act as well as you can.</p> <h2 id="chapter-6-life-and-death">Chapter 6: Life and Death</h2> <p>Seneca knew his life could end at any moment. A bad-tempered emperor, his own poor health. This made him think hard about time.</p> <p>His essay On the Shortness of Life makes a counterintuitive argument. The problem is not that our lives are too short. The problem is that we waste most of the time we have. All of us have enough time. We just fritter it.</p> <p>He lists the ways people waste their lives. Some chase wealth and success so they can buy luxury goods that end up in rubbish bins. Some go through daily routines on autopilot with no sense that time is running out. Some know what they want to do but postpone it, paralyzed by fear of failure, waiting for conditions to be perfect. All of these, Seneca says, are ways of failing to actually live.</p> <p>He is also sharp about what comes with worldly success. People spend their whole lives chasing it. They get it and find they now lack the one thing they wanted most: time. Time for themselves, for peace, for quiet, for just being. Success brings its own demands, and many people who achieve it are more trapped than they were before.</p> <p>Then there is distraction. Constant noise, interruptions, news, social media, all competing for attention to the point where it becomes difficult to complete anything or to simply be present in your own life. Seneca says living is the least important activity of the preoccupied man. They are effectively busy doing nothing.</p> <p>His remedy is to hold the fact of death in your mind. Not morbidly, but practically. We do not know how much time we have left. Today could be your last day. Maybe you have weeks, maybe decades. The assumption that you will definitely make it to old age may simply be false. And even if it is true, assuming you have unlimited time encourages you to postpone everything into a future that may arrive too late or not at all.</p> <p>Epictetus adds something important here. Life is a gift. It was given to you and it can be taken back. He says to think of it like being invited to a fair or a party. At some point the host says it is time to go. You can either leave feeling grateful for the time you had, or you can complain that it could not go on longer.</p> <p>He applies this to the people you love too. Nothing and no one belongs to you permanently. Your wife, your child, your friends. They are on loan. One day they will be returned. He says plainly that it is foolish to want your loved ones to be immortal, since that is not within your power or theirs.</p> <p>The goal for both Seneca and Epictetus is not to be gloomy about death but to make your appreciation of life more real and more urgent. Live each day as though it could be your last, not in the sense of giving up on planning, but in the sense of not deferring the actual experience of being alive to some imagined future.</p> <h2 id="chapter-7-how-we-live-together">Chapter 7: How We Live Together</h2> <p>Most of what the Stoics teach looks self-focused. Control your judgements, manage your emotions, deal with your adversity. Marcus Aurelius talked about retreating to his inner citadel to escape external noise. Does any of this leave room for other people?</p> <p>It does, and substantially so.</p> <p>The Stoics agreed with Aristotle that humans are by nature social and political animals. We are born into communities, first family, then local community, then country, and ultimately all of humanity. The inner work is not a retreat from the world. It is preparation to engage with it better. By improving your character and eliminating destructive emotions like anger and resentment, you become a more effective member of the communities you belong to.</p> <p>Epictetus stressed that each of us occupies multiple social <strong>roles</strong>. Some roles come from nature, like being a parent. Some come from social positions, like being a doctor or a magistrate. Each role comes with duties and responsibilities, and neglecting those duties is a failure.</p> <p>He gives a concrete example. A magistrate visited his school. On being asked about his family, the man said his daughter had been so gravely ill that he could not bear to be with her and had run away. Epictetus challenged him on two counts. First, he was prioritizing his own feelings over his daughter's wellbeing. Second, he was neglecting his role as a father. He claimed to have left because of his love for her. But his love for her should have made him stay.</p> <p>Beyond specific roles, the Stoics held a vision of a single human community. A slightly obscure Stoic called Hierocles developed this through the idea of expanding circles of concern. At the center is yourself. Then your immediate family. Then your local community. Then your country. Then all of humanity. You have duties at every level, and the outermost circle does not erase the inner ones. You are a member of both your local community and of humanity at large.</p> <p>Seneca put it plainly. There are two commonwealths. One vast and common, embracing gods and men. One assigned to us by the accident of birth. We belong to both.</p> <p>This was not just abstract theory. Stoics in Rome actually put their lives on the line for it. Helvidius Priscus, a senator, refused to back down when Emperor Vespasian abused his authority over the Senate. He was warned to stay away. He insisted on defending the rights of his fellow senators. He was executed. Marcus Aurelius later named him as one of the people who taught him the ideal of a community based on equality and freedom of speech.</p> <p>Musonius Rufus, a Stoic lecturer who taught Epictetus, argued that women have the same capacity for reason and the same natural inclination toward virtue as men, and should therefore be able to study philosophy. This was roughly two thousand years before universal suffrage.</p> <p>Epictetus also has a practical warning. If you are trying to develop new habits and improve your character, be very careful about who you spend time with. Spending time with people who embody the habits you are trying to escape is like brushing against someone covered in soot. You will get covered in soot. Find people whose values you share or admire.</p> 2026-04-09T00:00:00+00:00 2026-04-09T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/learn-rust-ownership-by-building-mini-grep/ <p>In this post, we are going to learn about the problem Rust is solving, Rust's ownership, borrowing concept and build a mini grep clone in Rust. I'm really excited for the project and I hope you are too. I won't go too deep in theory, just practical and we will build our knowledge of these concepts over time with more articles. Let's start.</p> <p>You can get the complete source code <a rel="external" href="https://github.com/MrSheerluck/mini-grep-in-rust">here</a></p> <h2 id="the-problem-rust-is-solving">The Problem Rust is Solving</h2> <p>Every program needs memory and you use memory to store data like strings, numbers, lists whatever. There is an important question we need to answer and that is <strong>who is responsible for freeing that memory when you're done with it?</strong></p> <p>There are two traditional answers.</p> <h3 id="the-programmer-does-it-manually">The Programmer Does it Manually</h3> <p>Like in C programming language, you call <code>malloc</code> to allocate memory and <code>free</code> to release it. The best part of this thing is speed and control but the problem is that we can make mistakes and we might free memory twice or forget to free it or use it after freeing it.</p> <p>These bugs are problematic. They're hard to reproduce and hard to debug.</p> <h3 id="the-language-does-it-automatically">The Language Does it Automatically</h3> <p>Like in Python programming language. There is a garbage collector runs in the background, figures out what memory is no longer reachable, and frees it. The best part is you basically can't have those dangerous memory bugs but the problem is performance. The garbage collector runs at unpredictable times, pauses your program and add overhead.</p> <p>When it comes to Rust, it gives you memory safety without a garbage collector. It does this through a system. This system is built on three ideas: ownership, borrowing and slices.</p> <h2 id="ownership">Ownership</h2> <p>Here's the core idea: in Rust, every piece of data has exactly one variable that "owns" it. When that variable goes out of scope, the data is automatically freed. No GC needed, because the compiler can figure out exactly when each piece of data should be cleaned up just by looking at the code.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // s owns the string</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span><span style="color: #9399B2;font-style: italic;"> // s goes out of scope here and Rust automatically frees the string</span></span></code></pre> <p>I hope you understand the above example but now lets get to the interesting part.</p> <p>What happens when you do this?</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> s1</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> s2</span><span style="color: #94E2D5;"> =</span><span> s1</span><span style="color: #9399B2;">;</span></span></code></pre> <p>In most languages, you'd expect both <code>s1</code> and <code>s2</code> to point to the same string or <code>s2</code> to be a copy of <code>s1</code>. In Rust, neither happens. **Ownership moves from <code>s1</code> to <code>s2</code>.</p> <p>After the second line, <code>s1</code> no longer exists as far as the compiler is concerned. Try to use it and you get a compile error:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> s1</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> s2</span><span style="color: #94E2D5;"> =</span><span> s1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> s1</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // ERROR: value borrowed here after move</span></span></code></pre> <p>You might ask, <strong>why does Rust do this?</strong> Because <code>String</code> is heap allocated. If both <code>s1</code> and <code>s2</code> owned it, who would free it? If both tried, you'd have a double free bug.</p> <p>So by keeping a single owner, Rust keeps it simple.</p> <p>But for simple types like integers don't have this issue as they live on the stack, copying them is trivial and there's no heap memory to worry about. So, for those, Rust just copies:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> y</span><span style="color: #94E2D5;"> =</span><span> x</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // Fine - integers are copied not moved</span></span></code></pre> <p>Technically, integers implement the <code>Copy</code> trait. <code>String</code> does not, so it moves instead. We will understand what trait is later in the series.</p> <h2 id="borrowing">Borrowing</h2> <p>Now the question is, if ownership moves when you pass data around, how do you actually use data in function? If you pass a <code>String</code> into a function, does the function consume it?</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> print_it</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">s</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> s</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span><span style="color: #9399B2;font-style: italic;"> // s is dropped here</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> print_it</span><span style="color: #9399B2;">(</span><span>s</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // ownership moves into the function</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> s</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // ERROR: s was moved</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span></code></pre> <p>Now, this is a problem. If you can't use <code>s</code> anymore once you pass it to a function, then its too much restrictive. You don't want every function call to permanently consume your data. To handle this situation, Rust gives you <strong>borrowing</strong>. This means instead of giving ownership, you lend a <em>reference</em> to the data.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> print_it</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">s</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> s</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span><span style="color: #9399B2;font-style: italic;"> // the reference goes out of scope, but the original string is unaffected</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> print_it</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>s</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // lend a reference, don&#39;t move ownership</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> s</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // still works, s is still the owner</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The <code>&amp;</code> means "a reference to". You're not passing the string directly instead you are passing a pointer to the string and the compiler tracks this carefully. The function can look at the data through the reference but it doesn't own it, so it can't free it and ownership stays with the original variable.</p> <p>This is called a <strong>shared reference</strong> or an <strong>immutable reference</strong>. Through this reference, you can read, but you can't modify. You can have as many of these as you want simultaneously because reading doesn't conflict with reading.</p> <h3 id="mutable-references">Mutable References</h3> <p>What if you need to modify data? There's a mutable reference for that:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> add_world</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">s</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push_str</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot; world&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> add_world</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span> s</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> s</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // &quot;hello world&quot;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>If you want mutable access, then you need to make the variable as <code>mut</code> mutable and give a mutable reference to the function. But there's a catch, <strong>you can have one mutable reference at a time, and you cannot have any immutable references at the same time</strong>. Wait, let me give you an example:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> r1</span><span style="color: #94E2D5;"> = &amp;</span><span>s</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // immutable borrow</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> r2</span><span style="color: #94E2D5;"> = &amp;</span><span style="color: #CBA6F7;">mut</span><span> s</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // ERROR: can&#39;t borrow as mutable while immutable borrow exists</span></span></code></pre> <p>But why can't we do this, what's the issue? Because if you could read and write at the same time, you'd have a data race, you're reading data while something else is modifying it. The result is undefined and Rust makes this entire category of bug impossible at the compile time.</p> <p>To give you a mental model of this borrowing concept:</p> <blockquote> <p>You can have either many readers or one write, never both simultaneously. This is not enforced at runtime but by the compiler before your code runs.</p> </blockquote> <h2 id="slices-borrowing-a-piece-of-something">Slices - Borrowing a Piece of Something</h2> <p>Sometimes you don't want to borrow an entire <code>String</code>, you just want to borrow part of it. That's what slices are for.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello world&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> hello</span><span style="color: #94E2D5;"> = &amp;</span><span>s</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> world</span><span style="color: #94E2D5;"> = &amp;</span><span>s</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">6</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">11</span><span style="color: #9399B2;">];</span></span></code></pre> <p><code>hello</code> here is of type <code>&amp;str</code>. Note that, its not a new string, instead it's a reference that points directly into the memory of <code>s</code>.</p> <blockquote> <p>A slice is a borrow. It points into someone else's data and that means while a slice is alive, the borrow checker won't let you modify or drop the original.</p> </blockquote> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;hello world&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> word</span><span style="color: #94E2D5;"> = &amp;</span><span>s</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;">];</span><span style="color: #9399B2;font-style: italic;"> // word borrows from s</span></span> <span class="giallo-l"><span>s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clear</span><span style="color: #9399B2;">()</span><span style="color: #9399B2;font-style: italic;"> // ERROR: can&#39;t mutate s while word is borrowing from it</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> word</span><span style="color: #9399B2;">)</span></span></code></pre> <p>If <code>s.clear()</code> were allowed, it would wipe out that <code>word</code> is pointing and you'd have a dangling reference (a pointer into freed memory). In C, this compiles and runs, and crashes or corrupts data unpredictably. In Rust, it doesn't compile. The borrow checker sees that <code>word</code> is still alive and still pointing into s, and it rejects the mutation.</p> <blockquote> <p><code>&amp;str</code> vs <code>&amp;String</code> You'll see both <code>&amp;str</code> and <code>&amp;String</code> in Rust code, and the distinction matters: <code>&amp;String</code> is a reference to a heap allocated <code>String</code> object <code>&amp;str</code> is a reference to a sequence of UTF-8 bytes</p> </blockquote> <p>In practice, when writing functions that just need to read a string, you should prefer <code>&amp;str</code> as the parameter type as it accepts both string literals and references to <code>String</code> values.</p> <p>Let's now start building our grep clone but before that lets learn a little bit about mini grep.</p> <h2 id="grep-101">Grep 101</h2> <p><code>grep</code> is a command line tool that searches through text for lines that match a pattern. That's it. The name stands for <strong>Global Regular Expression Print</strong>. It reads input, tests every line against a pattern and prints the lines that match.</p> <p>Open your terminal and try this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">echo</span><span style="color: #A6E3A1;"> -e &quot;hello world\ngoodbye world\nhello rust&quot;</span><span style="color: #94E2D5;"> |</span><span style="color: #89B4FA;font-style: italic;"> grep</span><span style="color: #A6E3A1;"> &quot;hello&quot;</span></span></code></pre> <p>Output:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">hello</span><span style="color: #A6E3A1;"> world</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">hello</span><span style="color: #A6E3A1;"> rust</span></span></code></pre> <p>It went through three lines and found two that contained the word "hello", and printed those. The third line didn't match so it was ignored. Now, lets try with a flag:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">echo</span><span style="color: #A6E3A1;"> -e &quot;hello world\ngoodbye world\nhello rust&quot;</span><span style="color: #94E2D5;"> |</span><span style="color: #89B4FA;font-style: italic;"> grep</span><span style="color: #A6E3A1;"> -v &quot;hello&quot;</span></span></code></pre> <p>output:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">goodbye</span><span style="color: #A6E3A1;"> world</span></span></code></pre> <p><code>-v</code> means invert, this print lines that do not match</p> <p>Let's try another flag:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">echo</span><span style="color: #A6E3A1;"> -e &quot;hello world\ngoodbye world\nhello rust&quot;</span><span style="color: #94E2D5;"> |</span><span style="color: #89B4FA;font-style: italic;"> grep</span><span style="color: #A6E3A1;"> -c &quot;hello&quot;</span></span></code></pre> <p>output:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">2</span></span></code></pre> <p><code>-c</code> means count, this don't print lines instead just print how many matched</p> <h2 id="what-are-we-building">What are we Building</h2> <p>Before touching <code>main.rs</code>, let me tell you what we are building: Our program will:</p> <ul> <li>accept a pattern and a path from the command line</li> <li>accept optional flags</li> <li>walk the directory (or read a single file) recursively</li> <li>for each file, read its contents, search line by line</li> <li>print results with filename, line number</li> </ul> <h2 id="project-setup">Project Setup</h2> <p>Run this in your terminal:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> new rgrep</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> rgrep</span></span></code></pre> <p>Now open the <code>Cargo.toml</code> file and add the dependencies with this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;">[</span><span>package</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>name</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;rgrep&quot;</span></span> <span class="giallo-l"><span>version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.1.0&quot;</span></span> <span class="giallo-l"><span>edition</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;2024&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>dependencies</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>regex</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&quot;</span></span> <span class="giallo-l"><span>walkdir</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;2&quot;</span></span></code></pre> <p>We have added three dependencies:</p> <ul> <li><code>regex</code> compiles and runs regular expression patterns against text</li> <li><code>walkdir</code> recursively walks a directory tree, giving you every file one by one</li> </ul> <h2 id="imports">Imports</h2> <p>Open <code>src/main.rs</code> and delete everything. Write this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> regex</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Regex</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span>env</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span>fs</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> walkdir</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">WalkDir</span><span style="color: #9399B2;">;</span></span></code></pre> <ul> <li><code>use regex::Regex</code> is used for regex operations</li> <li><code>use std::env</code> is used access process environment like command line arguments and environment variables</li> <li><code>use std::fs</code> here <code>fs</code> stands for file system and we are using this to read files, write files, checking if path exists etc.</li> <li><code>use walkdir::WalkDir</code> this helps us to do recursive directory walk. Basically we can give it a directory and it'll return the every entry inside</li> </ul> <h3 id="reading-command-line-arguments">Reading Command Line Arguments</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> args</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> env</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">args</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">collect</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Here, <code>env::args()</code> returns an <strong>iterator</strong> over the command line arguments. For example, when a user runs:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> run -- -v &quot;hello&quot; ./src</span></span></code></pre> <p>the arguments are: <code>["rgrep", "-v", "hello", "./src"]</code>. The first element is always the program's own name.</p> <blockquote> <p>An iterator is something you can step through one element at a time. The <code>.collect()</code> exhausts the iterator and gathers every element into a collection.</p> </blockquote> <p>The type annotation <code>Vec&lt;String&gt;</code> tells Rust what kind of collection you want. <code>.collect()</code> can produce several types, so you have to specify.</p> <blockquote> <p><code>Vec&lt;String&gt;</code> means a growable list of owned strings. You can check my previous article for more info.</p> </blockquote> <h4 id="why-string-and-not-str">Why <code>String</code> and not <code>&amp;str</code>?</h4> <p>You might ask, why use <code>String</code> and not <code>&amp;str</code>? To answer this, you need to understand what <code>&amp;str</code> actually is. A <code>&amp;str</code> is a reference, it does not own data, it points to data that already exists somewhere in memory and has a defined lifetime. String literals like <code>"hello"</code> work as <code>&amp;str</code> because the compiler compiles them directly into the binary, so they live for the entire duration of the program.</p> <p>Command line arguments are different, they come from the operating system at runtime. There is no pre-existing place in your program's memory where they live. Rust has to allocate heap memory to hold each argument string as it reads it. <code>String</code> is the type for heap-allocated, owned string data, it carries the data with it and is responsible for freeing it when it goes out of scope. <code>&amp;str</code> cannot do this because it is just a pointer, and a pointer needs something to point to.</p> <p>So <code>Vec&lt;String&gt;</code> is the only option here. Each <code>String</code> in the vector owns its argument data, and the vector owns all the <code>String</code>s. When <code>args</code> goes out of scope, everything is cleaned up automatically.</p> <h3 id="validating-argument-count">Validating Argument Count</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">if</span><span> args</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &lt;</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Usage: rgrep [OPTIONS] &lt;pattern&gt; &lt;path&gt;&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> eprintln!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Options: -v -c -l&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">process</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">exit</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>args.len()</code> returns how many arguments we have. The minimum valid call is:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">rgrep</span><span style="color: #A6E3A1;"> &quot;pattern&quot; ./path</span></span></code></pre> <p>This gives us <code>["rgrep", "pattern", "./path"]</code> a total of 3 elements. If there are fewer than three, the user didn't provide enough and we print an error and exit.</p> <blockquote> <p><code>eprintln!</code> is like <code>println!</code> but writes to stderr instead of stdout. Errors and usage messages conventionally go to stderr so they don't pollute the output when piping.</p> </blockquote> <p>Finally, <code>std::process::exit(1)</code> terminates the program with exit code 1.</p> <h3 id="parsing-flags">Parsing Flags</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> invert</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> count_only</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> files_only</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> pattern_index</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span style="color: #CBA6F7;">for</span><span> i</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;">..</span><span>args</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> args</span><span style="color: #9399B2;">[</span><span>i</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">as_str</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;-v&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span> invert</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;-c&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span> count_only</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;-l&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span> files_only</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> pattern_index</span><span style="color: #94E2D5;"> =</span><span> i</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>We start with four mutable variables. The first three tracks which flags were passed. <code>pattern_index</code> tracks where in <code>args</code> the pattern is. This starts with <code>1</code> because <code>args[0]</code> is always the program name</p> <p>We are iterating over all the arguments and checking which flag is being passed by the user and then setting that to <code>true</code>. The <code>_</code> is the catch-all, if its none of the above that means we have hit the pattern and we are recording its index and then stop the loop with <code>break</code>.</p> <p>So, if the user runs <code>rgrep -v -c "hello" ./src</code>, after the loop: <code>invert</code> is true, <code>count_only</code> is true, <code>pattern_index</code> is 3 (pointing at "hello")</p> <h3 id="extracting-pattern-and-path">Extracting Pattern and Path</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">if</span><span> pattern_index</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;"> &gt;=</span><span> args</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> eprintln!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Error: missing pattern or path&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">process</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">exit</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> pattern</span><span style="color: #94E2D5;"> = &amp;</span><span>args</span><span style="color: #9399B2;">[</span><span>pattern_index</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> path</span><span style="color: #94E2D5;"> = &amp;</span><span>args</span><span style="color: #9399B2;">[</span><span>pattern_index</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">];</span></span></code></pre> <p>After the flag loop, <code>pattern_index</code> is pointing to the pattern. The paths comes right after it at <code>pattern_index + 1</code>. If that index is out of bounds, the user forgot to provide one of them.</p> <p><code>let pattern = &amp;args[pattern_index]</code> this is the borrowing concept. We don't need our own copy of the pattern, we just need to read it and act accordingly. So, <code>pattern</code> is a <code>&amp;String</code> type, a reference that borrows from <code>args</code>. Same thing happens for <code>path</code>.</p> <h3 id="compiling-the-regex">Compiling The Regex</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> regex</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #F9E2AF;font-style: italic;"> Regex</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>pattern</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>r</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> r</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> eprintln!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid pattern: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> e</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">process</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">exit</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">};</span></span></code></pre> <p><code>Regex::new(pattern)</code> takes the pattern string and compiles it into a <code>Regex</code> object. "Compiling" here means parsing the pattern syntax and building an internal state machine that can efficiently test strings against it.</p> <p><code>Regex::new</code> returns a <code>Result&lt;Regex, Error&gt;</code>, this is a enum with two variants: <code>Ok(value)</code> meaning success and <code>Err(error)</code> meaning failure. This is the way Rust handles operations that can fail.</p> <p><code>match</code> on a <code>Result</code> is the standard way to handle it:</p> <ul> <li><code>Ok(r)</code> - the pattern is compiled successfully, <code>r</code> is the <code>Regex</code> object</li> <li><code>Err(e)</code> - the pattern was invalid (malformed regex syntax). <code>e</code> is the error and we just print it and exit</li> </ul> <blockquote> <p>If you don't understand clearly, no worries, we will learn more about it in a later article, for now just follow and finish the project</p> </blockquote> <h3 id="walking-the-directory">Walking the Directory</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">for</span><span> entry</span><span style="color: #CBA6F7;"> in</span><span style="color: #F9E2AF;font-style: italic;"> WalkDir</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span>path</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into_iter</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> entry</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> entry</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>e</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> e</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> continue</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> !</span><span>entry</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">file_type</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_file</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> continue</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> file_path</span><span style="color: #94E2D5;"> =</span><span> entry</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">path</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>WalkDir::new(path).into_iter()</code> starts a recursive walk at path and gives us entries one at a time. Each entry is a <code>Result&lt;DirEntry&gt;</code> because reading a directory can fail may be due to permissions, broken symlinks, etc.</p> <p>We <code>match</code> on each entry. Success case gives us <code>DirEntry</code> and in case of failure, we continue to the next iteration</p> <p>If <code>!entry.file_type().is_file()</code> gives us both files and directories, we only care about files so we skip anything that is not a file with <code>continue</code></p> <p><code>entry.path()</code> gives us a <code>&amp;Path</code>, its a borrowed reference to the file's path. <code>Path</code> is Rust's type for filesystem paths.</p> <h3 id="reading-files">Reading Files</h3> <p>Once we get to know that we got a file and not a directory, we are keeping its file path and then we are now going to read that file's content:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> contents</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #F9E2AF;"> fs</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">read_to_string</span><span style="color: #9399B2;">(</span><span>file_path</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>c</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> c</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span>_</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> continue</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">};</span></span></code></pre> <p><code>fs::read_to_string(file_path)</code> reads the entire file and returns <code>Result&lt;String&gt;</code>. On success, <code>contents</code> has the file's text and on failure case (again may be due to permission or something else), we just continue to the next iteration.</p> <h3 id="the-search-function">The Search Function</h3> <p>We want to search through the content and get back the matching lines. The question we need to ask is what should the search function take and what should it return?</p> <p>It should take <code>contents</code> as a borrow that means <code>&amp;str</code> because it only needs to read the text, not own it.</p> <p>For the return value, each matching line is a slice of <code>contents</code>. This means a <code>&amp;str</code> pointing directly into file's text but returning those slices requires lifetime annotations, which we haven't covered yet. So instead we return an owned <code>String</code> copy of each matching line. It's of course less efficient but its correct and simple for now.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> search</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">contents</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> regex</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">Regex</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> invert</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> bool</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">usize</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> results</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">usize</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> String</span><span style="color: #9399B2;">)</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> line_number</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> line</span><span style="color: #CBA6F7;"> in</span><span> contents</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">lines</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> is_match</span><span style="color: #94E2D5;"> =</span><span> regex</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_match</span><span style="color: #9399B2;">(</span><span>line</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> should_include</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if</span><span> invert</span><span style="color: #9399B2;"> {</span><span style="color: #94E2D5;"> !</span><span>is_match</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span><span> is_match</span><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> should_include</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> results</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">((</span><span>line_number</span><span style="color: #9399B2;">,</span><span> line</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">()));</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> line_number</span><span style="color: #94E2D5;"> +=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> results</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>We are borrowing <code>contents</code>, <code>regex</code> as we only need to read them. The function is returning <code>Vec&lt;(uszie, String)&gt;</code>, this is a vector of tuples. Each tuple is a line number. <code>contents.lines()</code> gives each line as a <code>&amp;str</code> slice pointing into <code>contents</code>.</p> <p>Inside the loop, we are matching the regex with that line, then checking the <code>invert</code> flag and accordingly decides if we need to include the line and line number in the result or not.</p> <p><code>line.to_string()</code> converts the borrowed <code>&amp;str</code> slice into an owned <code>String</code>. This is the copy that we take so we don't need to worry about the slice outliving <code>contents</code>. Finally, we are just returning the <code>results</code></p> <h3 id="calling-the-search-function">Calling the Search Function</h3> <p>Now we have all the pieces. We have walked the directory, read the file content, and we have our <code>search</code> function. Now we just need to call it and handle the output based on the flags.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> matches</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> search</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>contents</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>regex</span><span style="color: #9399B2;">,</span><span> invert</span><span style="color: #9399B2;">);</span></span></code></pre> <p>We are passing <code>&amp;contents</code> and <code>&amp;regex</code> as borrows. The <code>search</code> function only needs to read them, not own them. <code>invert</code> is a <code>bool</code> which implements <code>Copy</code>, so it's just copied over directly.</p> <p><code>matches</code> is now a <code>Vec&lt;(usize, String)&gt;</code> holding every line that matched (or didn't match if <code>-v</code> was passed).</p> <h4 id="handling-l-files-only">Handling <code>-l</code> (files only)</h4> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">if</span><span> files_only</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> !</span><span>matches</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_empty</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> file_path</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">display</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> continue</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>If the user passed <code>-l</code>, we only care about whether the file had any matches at all, not what those lines are. <code>.is_empty()</code> checks if the vector has zero elements. If it does have matches, we print the file path and move on with <code>continue</code> to the next file.</p> <p><code>file_path.display()</code> converts the <code>Path</code> into something printable. <code>Path</code> doesn't implement <code>Display</code> directly but <code>.display()</code> returns a wrapper that does.</p> <h4 id="handling-c-count-only">Handling <code>-c</code> (count only)</h4> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">if</span><span> count_only</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> file_path</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">display</span><span style="color: #9399B2;">(),</span><span> matches</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> continue</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>If the user passed <code>-c</code>, we don't print the actual lines either. We just print the file path and the number of matches. <code>.len()</code> on a <code>Vec</code> returns the number of elements as a <code>usize</code>.</p> <h4 id="the-default-case">The Default Case</h4> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">for</span><span> i</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 0</span><span style="color: #94E2D5;">..</span><span>matches</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> line_num</span><span style="color: #94E2D5;"> =</span><span> matches</span><span style="color: #9399B2;">[</span><span>i</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> line</span><span style="color: #94E2D5;"> = &amp;</span><span>matches</span><span style="color: #9399B2;">[</span><span>i</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">:</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> file_path</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">display</span><span style="color: #9399B2;">(),</span><span> line_num</span><span style="color: #9399B2;">,</span><span> line</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>If no output flag was passed, we print every matching line with its filename and line number. <code>matches[i].0</code> accesses the first element of the tuple (the line number) and <code>matches[i].1</code> accesses the second (the line text).</p> <p><code>let line = &amp;matches[i].1</code> is a borrow again. We just need to read the string to print it, no reason to take ownership or clone it.</p> <p>The output format <code>filename:line_number: line</code> is the standard grep format that most editors understand. If you run this in a terminal that supports it, you can click those results and jump directly to the file and line.</p> <h2 id="run-the-project">Run The Project</h2> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> run -- &quot;fn&quot; ./src</span></span></code></pre> <p>You should get something like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">./src/main.rs:8:</span><span style="color: #A6E3A1;"> fn search</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">contents:</span><span style="color: #9399B2;"> &amp;</span><span style="color: #89B4FA;font-style: italic;">str,</span><span style="color: #A6E3A1;"> regex:</span><span style="color: #9399B2;"> &amp;</span><span style="color: #89B4FA;font-style: italic;">Regex,</span><span style="color: #A6E3A1;"> invert: bool</span><span style="color: #9399B2;">)</span><span> -</span><span style="color: #94E2D5;">&gt;</span><span style="color: #A6E3A1;"> Vec&lt;(</span><span style="color: #89B4FA;font-style: italic;">usize,</span><span style="color: #A6E3A1;"> String)</span><span style="color: #94E2D5;">&gt;</span><span style="color: #A6E3A1;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">./src/main.rs:27:</span><span style="color: #A6E3A1;"> fn main</span><span style="color: #9399B2;">()</span><span style="color: #A6E3A1;"> {</span></span></code></pre> <p>You can try using flags too like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> run -- -c &quot;fn&quot; ./src</span></span></code></pre> <p>you should get something like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">./src/main.rs:</span><span style="color: #FAB387;"> 2</span></span></code></pre><h2 id="conclusion">Conclusion</h2> <p>This was a long one too but I think now you have some practical knowledge on ownership and borrowing. I'm not going too much theoretical as that'll be just boring. We'll learn more about <code>Result</code> in a later article. In the next one, we will <strong>build a JSON Parser</strong> by learning about structs, enums and pattern matching. See you soon.</p> 2026-04-08T00:00:00+00:00 2026-04-08T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/wtf-is-claude-mythos/ <h1 id="wtf-is-claude-mythos">WTF is Claude Mythos</h1> <p>Anthropic didn't announce Mythos. It leaked. A misconfigured CMS left a draft blog post in a publicly searchable data store. Security researchers found it and Anthropic confirmed it shortly after.</p> <p>In this article you are going to learn what Mythos is, what it can actually do, and why Anthropic is scared of releasing it.</p> <h2 id="what-is-mythos">What is Mythos?</h2> <p>Mythos is Anthropic's next model. It sits in a new tier above Opus, both in capability and cost. Internally they called this tier Capybara.</p> <p>It is a general-purpose model. But it is strikingly capable at cybersecurity tasks specifically. Where prior Claude models respond to instructions one step at a time, Mythos plans and executes sequences of actions on its own, moving across systems and completing operations without waiting for human input at each stage.</p> <p>Here are the benchmark numbers from Anthropic's own evaluation on agentic coding:</p> <table><thead><tr><th>Benchmark</th><th>Mythos Preview</th><th>Opus 4.6</th></tr></thead><tbody> <tr><td>SWE-bench Pro</td><td>77.8%</td><td>53.4%</td></tr> <tr><td>Terminal-Bench 2.0</td><td>82.0%</td><td>65.4%</td></tr> <tr><td>SWE-bench Multimodal</td><td>59.0%</td><td>27.1%</td></tr> <tr><td>SWE-bench Multilingual</td><td>87.3%</td><td>77.8%</td></tr> <tr><td>SWE-bench Verified</td><td>93.9%</td><td>80.8%</td></tr> </tbody></table> <p>These are not small improvements.</p> <h2 id="what-can-it-actually-do">What Can It Actually Do</h2> <p>This is where it gets serious.</p> <p>During testing, Mythos Preview was capable of identifying and exploiting zero-day vulnerabilities in every major operating system and every major web browser. Many of the vulnerabilities it found are ten or twenty years old. The oldest being a 27-year-old bug in OpenBSD.</p> <p>In one case it wrote a browser exploit that chained together four vulnerabilities, writing a complex JIT heap spray that escaped both the renderer and OS sandboxes. It autonomously obtained local privilege escalation on Linux by exploiting subtle race conditions and KASLR bypasses. It also wrote a remote code execution exploit on FreeBSD's NFS server that granted full root access to unauthenticated users by splitting a 20-gadget ROP chain over multiple packets.</p> <p>The numbers make this concrete. Opus 4.6 turned Firefox 147 JavaScript engine vulnerabilities into working shell exploits only 2 times out of several hundred attempts. Mythos Preview developed working exploits 181 times on the same benchmark.</p> <p>These capabilities were not explicitly trained into Mythos Preview. They emerged as a downstream consequence of general improvements in code, reasoning, and autonomy. The same improvements that make it better at patching vulnerabilities also make it better at exploiting them.</p> <h2 id="why-it-is-not-public">Why It Is Not Public</h2> <p>Mythos Preview can find tens of thousands of vulnerabilities that even an advanced bug hunter would struggle to find, and it can write the exploits to go with them.</p> <p>It is also extremely compute-intensive and expensive to run at scale. Anthropic has stated it is working on efficiency improvements before any general release.</p> <p>So it is dangerous and expensive. Both problems they need to solve before shipping it broadly.</p> <h2 id="what-they-did-instead-project-glasswing">What They Did Instead: Project Glasswing</h2> <p>On April 7, Anthropic launched Project Glasswing. More than 40 partner organizations get access to Mythos Preview strictly for defensive security work, scanning their own code and open-source software for vulnerabilities. Partners include Amazon, Apple, Microsoft, Cisco, CrowdStrike, Palo Alto Networks, and the Linux Foundation. Findings will be shared across the industry.</p> <p>Anthropic is providing up to $100 million in usage credits to participating companies and $4 million to open-source security organizations including OpenSSF, Alpha-Omega, and the Apache Software Foundation.</p> <p>Over 99% of the vulnerabilities found have not yet been patched, so details cannot be disclosed publicly yet. For findings they cannot discuss, Anthropic is publishing SHA-3 cryptographic commitments as proof they hold the findings. These will be revealed once responsible disclosure is complete.</p> <p>There is no public release date.</p> <h2 id="conclusion">Conclusion</h2> <p>This was a big one. Mythos is real, it is the most capable model Anthropic has built, and it is deliberately locked away until they figure out how to release it safely. Project Glasswing is their attempt to use it for good in the meantime.</p> <h2 id="resources">Resources</h2> <ul> <li>Anthropic Red Team: <a rel="external" href="https://red.anthropic.com/2026/mythos-preview/">Assessing Claude Mythos Preview's cybersecurity capabilities</a></li> <li>Axios: <a rel="external" href="https://www.axios.com/2026/04/07/anthropic-mythos-preview-cybersecurity-risks">Anthropic withholds Mythos Preview over hacking concerns</a></li> <li>TechCrunch: <a rel="external" href="https://techcrunch.com/2026/04/07/anthropic-mythos-ai-model-preview-security/">Anthropic debuts Mythos preview in new cybersecurity initiative</a></li> <li>Fortune: <a rel="external" href="https://fortune.com/2026/03/26/anthropic-says-testing-mythos-powerful-new-ai-model-after-data-leak-reveals-its-existence-step-change-in-capabilities/">Anthropic confirms Mythos after data leak</a></li> <li>Bloomberg: <a rel="external" href="https://www.bloomberg.com/news/articles/2026-04-07/anthropic-lets-apple-amazon-test-more-powerful-mythos-ai-model">Anthropic lets Apple, Amazon test Mythos</a></li> </ul> 2026-04-05T00:00:00+00:00 2026-04-05T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/scalars-explained/ <p>In this series we are going to learn all the maths that is required to learn machine learning or deep learning. All the post, will explain the concept, will have geometric intuition or understanding and then python code implementation. We will start from linear algebra.</p> <h2 id="what-is-a-scalar">What is a Scalar?</h2> <p>Before going to vectors, lets first understand what is a scalar? A scalar is a single real number. That is the complete definition. When we write: $$s \in \mathbb{R} $$</p> <p>We are saying: $s$ is an element of the set of all real numbers.</p> <blockquote> <p>Scalar has only one piece of information: its <strong>value</strong>.</p> </blockquote> <p>Scalars live in $\mathbb{R}$ (the real number line). It includes every decimal, every fraction, every irrational number. Basically everything on a continuous number line.</p> <h2 id="what-can-you-do-with-scalars">What Can You Do With Scalars</h2> <p>The standard arithmetic operations all apply:</p> <table><thead><tr><th>Operation</th><th>Notation</th><th>Example</th></tr></thead><tbody> <tr><td>Addition</td><td>$a + b$</td><td>$3 + 5 = 8$</td></tr> <tr><td>Subtraction</td><td>$a-b$</td><td>$3-5=-2$</td></tr> <tr><td>Multiplication</td><td>$a.b$</td><td>$3.5=15$</td></tr> <tr><td>Division</td><td>$a/b$</td><td>$3/5=0.6$</td></tr> </tbody></table> <p>These operations always produce another scalar. The output stays in $\mathbb{R}$.</p> <h2 id="why-scalars-are-not-enough">Why Scalars Are Not Enough</h2> <p>Let's say you want to describe how an object is moving through 3D space. The object moves at 60 km/h. But 60 km/h where? Diagonally upward? A scalar cannot encode this. You need to know both how much (magnitude) and which way (direction)</p> <p>In ML, you have a house with features: area = 1200 sq ft, bedrooms = 3, age = 10 years, price = $250,000. These are four separate scalars. But a model needs to process them together as one object, not as four disconnected numbers. A scalar cannot represent structured, multi-dimensional data.</p> <p>This is the fundamental limitation of scalars:</p> <blockquote> <p>A scalar carries magnitude (size/value) only. It carries no directional or structural information.</p> </blockquote> <h2 id="the-two-things-we-need-that-scalars-cannot-provide">The Two Things We Need That Scalars Cannot Provide</h2> <ol> <li>Direction - When a quantity has both a size and direction like displacement, velocity, force. Here, a single number is insufficient. You need a mathematical object that encodes both simultaneously.</li> <li>Structure across multiple dimensions - When data has multiple features that belong together as one unit like a data point in ML, you need an object that holds all dimensions at once and supports operations across them.</li> </ol> <p>Both the things can be done with <strong>vectors</strong>, which is what we study from next article.</p> <h2 id="conclusion">Conclusion</h2> <p>This was a quick one. In the next one you'll learn about vectors and vector spaces. See you soon.</p> 2026-04-04T00:00:00+00:00 2026-04-04T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/learn-rust-basics-by-building-a-brainfuck-interpreter/ <p>Hi, In this series we are going to learn Rust programming language by building exciting projects per article. For every article, we will first learn some concepts and then build a mini project. I promise you these mini projects will be exciting. The only prerequisite is, you should know any one programming language like just basics of it as this series will focus on teaching rust and not programming from zero.</p> <p>My motive is to explain how to do a certain thing in Rust, so I won't explain how a loop works or how a function works. I'll just explain how to work with variables, functions, loops etc in Rust but I'll explain Rust specific concepts in detail.</p> <p>In this post, we are going to <strong>build a brainfuck language interpreter in Rust</strong>. But before that, we will learn about variables and mutability, scalar types, compound types, functions, basic string handling (we will dive deep in the next article), <code>println!</code> &amp; basic macros. We will also learn about cargo and control flow in rust like if and else blocks, loops, and match (this is interesting).</p> <p>You can get the source code from <strong><a rel="external" href="https://github.com/MrSheerluck/brainfuck-interpreter-in-rust">here</a></strong></p> <p>Let's start, I can't wait.</p> <h2 id="how-rust-works-and-cargo">How Rust Works and Cargo</h2> <h3 id="what-happens-when-you-write-a-rust-program">What happens when you write a Rust program?</h3> <p>Rust is a <strong>compiled language</strong>. This means before the program can run, it has to be translated from human readable Rust code into machine code that your CPU can directly execute. This translation is done by the <strong>Rust compiler</strong> called <code>rustc</code>.</p> <h3 id="cargo">Cargo</h3> <p>Cargo is Rust's official build system and package manager. It does multiple things:</p> <ul> <li>creates new projects with a standard folder structure</li> <li>compiles the rust code by invoking <code>rustc</code> under the hood</li> <li>downloads and manages external libraries(in rust world we call them <strong>crates</strong>)</li> <li>run tests, benchmarks and documentation generation</li> </ul> <p>When you'll install Rust (via <code>rustup</code>), Cargo comes with it automatically.</p> <p>Let me show you some of the common commands that you'll be using constantly:</p> <table><thead><tr><th>Command</th><th>What it does</th></tr></thead><tbody> <tr><td><code>cargo new project_name</code></td><td>creates a new project folder with boilerplate</td></tr> <tr><td><code>cargo run</code></td><td>compiles and immediately runs the binary</td></tr> <tr><td><code>cargo check</code></td><td>checks for errors without producing a binary</td></tr> <tr><td><code>cargo build</code></td><td>compiles your project, produces a binary</td></tr> </tbody></table> <h3 id="project-structure">Project Structure</h3> <p>Let's try to create a project with Cargo: Open up your terminal and run the following command:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> new hello</span></span></code></pre> <p>It'll create a new Rust project called <code>hello</code>. Now, open the project folder in your preferred editor and you'll see a folder structure like this:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">hello/</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">├──</span><span style="color: #A6E3A1;"> Cargo.toml</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">└──</span><span style="color: #A6E3A1;"> src/</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> └──</span><span style="color: #A6E3A1;"> main.rs</span></span></code></pre> <p>Let me explain what each of these files are:</p> <h4 id="cargo-toml"><code>Cargo.toml</code></h4> <p>This is the <strong>manifest file</strong> for your project. It's written in TOML format (a simple config format). It contains:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;">[</span><span>package</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>name</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;hello&quot;</span></span> <span class="giallo-l"><span>version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.1.0&quot;</span></span> <span class="giallo-l"><span>edition</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;2024&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;">[</span><span>dependencies</span><span style="color: #9399B2;">]</span></span></code></pre> <ul> <li><code>name</code> - the name of your project</li> <li><code>version</code> - your project's version</li> <li><code>edition</code> - which edition of Rust you are using</li> <li><code>[dependencies]</code> - this is where you list down the external crates your project needs. Initially its empty.</li> </ul> <h4 id="src-main-rs"><code>src/main.rs</code></h4> <p>This is the entry point of every Rust program. Cargo generates this for you:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Hello, world!&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>fn</code> is the keyword to define a function in Rust. <code>main</code> is the name of the function. The curly braces <code>{}</code> defines the body of the function.</p> <p><code>println!("Hello, world!");</code> - <code>println!</code> is a <code>macro</code>, not a regular function. Notice there is a <code>!</code> right before the parentheses <code>!()</code>. Macros are just code that generates other code at compile time. You don't need to understand how they work internally right now. Just keep in mind that <code>println!</code> prints a line of text to the terminal followed by a new line.</p> <p>The text inside the quotes is a <strong>string literal</strong>. if you want to print values inside the string, you use <code>{}</code> as a placeholder:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;The value is </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 42</span><span style="color: #9399B2;">);</span></span></code></pre><h2 id="variables-and-mutability">Variables and Mutability</h2> <h3 id="declaring-variables">Declaring Variables</h3> <p>In Rust, you declare a variable with <code>let</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">;</span></span></code></pre> <p>This creates a variable named <code>x</code> and binds the value 5 to it.</p> <h3 id="variables-are-immutable-by-default">Variables are Immutable by Default</h3> <p>This is one of Rust's core design decisions. Once you bind a value to a variable, you cannot change it unless you explicitly say you want to.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span>x</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 6</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // ERROR: cannot assign twice to immutable variable</span></span></code></pre> <p>To make a variable mutable, you need to add <code>mut</code> keyword:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span>x</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 6</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // OK this is fine</span></span></code></pre><h3 id="shadowing">Shadowing</h3> <p>Rust allows you to <strong>shadow</strong> a variable. This means you can declare a new variable with the same name which replaces the previous one:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;"> =</span><span> x</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // this is a new `x`, not mutating the old one</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;"> =</span><span> x</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> x</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // prints 12</span></span></code></pre> <p>You need to understand that shadowing is different than <code>mut</code>. With shadowing, you are creating a brand new variable (and can even change its type). But with <code>mut</code>, you're modifying the same variable in place.</p> <h2 id="data-type">Data Type</h2> <p>Rust is <strong>statically typed</strong>. This means every variable has a type known at compile time. Most of the time the compiler can infer the type from context, so you don't have to write it explicitly. But you can always annotate it:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">;</span></span></code></pre> <p>The <code>: i32</code> after the variable name is the <strong>type annotation</strong>.</p> <h3 id="integer-types">Integer Types</h3> <p>Rust has multiple integer types. They differ in size (how many bits they use) and whether they can hold negative numbers:</p> <table><thead><tr><th>Type</th><th>Size</th><th>Range</th></tr></thead><tbody> <tr><td>i8</td><td>8-bit signed</td><td>-128 to 127</td></tr> <tr><td>i16</td><td>16-bit signed</td><td>-32,768 to 32,767</td></tr> <tr><td>i32</td><td>32-bit signed</td><td>~-2 billion to ~2 billion</td></tr> <tr><td>i64</td><td>64-bit signed</td><td>very large range</td></tr> <tr><td>u8</td><td>8-bit unsigned</td><td>0 to 255</td></tr> <tr><td>u16</td><td>16-bit unsigned</td><td>0 to 65,535</td></tr> <tr><td>u32</td><td>32-bit unsigned</td><td>0 to ~4 billion</td></tr> <tr><td>u64</td><td>64-bit unsigned</td><td>ver large range</td></tr> <tr><td>usize</td><td>pointer-sized</td><td>depends on your OS (64-bit on 64-bit systems)</td></tr> </tbody></table> <p><code>i32</code> is the default integer type when Rust infers. <code>usize</code> is special because its used for indexing into collections (arrays, vectors etc) because its size matches memory address size of your machine.</p> <h3 id="boolean">Boolean</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> is_active</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> bool</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> is_done</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">;</span></span></code></pre> <p>Only two values are there for boolean type in Rust: <code>true</code> or <code>false</code></p> <h3 id="character">Character</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> c</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> char</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> &#39;</span><span style="color: #A6E3A1;">A</span><span style="color: #9399B2;">&#39;;</span></span></code></pre> <p>Rust's char type represents a single Unicode scalar value. It uses single quotes (double quotes are for strings). A char is 4 bytes in Rust, not 1, because it can hold any unicode character.</p> <h3 id="floating-point">Floating Point</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> f</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f64</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">14</span><span style="color: #9399B2;">;</span></span></code></pre> <p><code>f32</code> and <code>f64</code> are 32-bit and 64-bit floating point numbers. The default is <code>f64</code> because on modern hardware it's roughly as fast as <code>f32</code> but more precise.</p> <h2 id="compound-types">Compound Types</h2> <h3 id="tuples">Tuples</h3> <p>A tuple groups multiple values of potentially different types into one compound value. Let me show you an example:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> tup</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> (</span><span style="color: #CBA6F7;">i32</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> f64</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> bool</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span style="color: #FAB387;">500</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 6</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">4</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">);</span></span></code></pre> <p>One thing to note about tuples is that they have a fixed length. Once they are declared, then you cannot add or remove elements to the tuple.</p> <p>But you can access elements from tuple, to do that you can use the <strong>dot notation</strong> with the index:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;"> =</span><span> tup</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // 500</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> y</span><span style="color: #94E2D5;"> =</span><span> tup</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;font-style: italic;"> // 6.4</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;"> =</span><span> tup</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;font-style: italic;"> // true</span></span></code></pre> <p>You can also destructure a tuple. Destructuring means unpacking the tuple elements in individual variables:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span style="color: #9399B2;"> (</span><span>a</span><span style="color: #9399B2;">,</span><span>b</span><span style="color: #9399B2;">,</span><span>c</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> tup</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> a</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // 500</span></span></code></pre><h3 id="arrays">Arrays</h3> <p>An Array holds multiple values of the same type, with a fixed length.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> arr</span><span style="color: #94E2D5;">:</span><span style="color: #9399B2;"> [</span><span style="color: #CBA6F7;">i32</span><span style="color: #9399B2;">;</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> [</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;">4</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;">];</span></span></code></pre> <p>The type annotation <code>[i32; 5]</code> means its an array of <code>i32</code> with exactly 5 elements.</p> <p>To access elements in array, you can use these <code>[]</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> first</span><span style="color: #94E2D5;"> =</span><span> arr</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">];</span><span style="color: #9399B2;font-style: italic;"> // 1</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> second</span><span style="color: #94E2D5;"> =</span><span> arr</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">];</span><span style="color: #9399B2;font-style: italic;"> // 2</span></span></code></pre> <blockquote> <p>If you try to access an index that's out of bounds, then Rust will <strong>panic</strong> ( crash at runtime with an error message )</p> </blockquote> <p>You can also create an array where every element is the same value:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> zeros</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> [</span><span style="color: #FAB387;">0</span><span style="color: #CBA6F7;">u8</span><span style="color: #9399B2;">;</span><span style="color: #FAB387;"> 25</span><span style="color: #9399B2;">];</span><span style="color: #9399B2;font-style: italic;"> // 25 elements all set to 0</span></span></code></pre> <p>This means, create an array of type <code>u8</code> with 25 elements and intialize all the elements to 0.</p> <h2 id="functions">Functions</h2> <h3 id="defining-functions">Defining Functions</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> add</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">x</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> y</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> x</span><span style="color: #94E2D5;"> +</span><span> y</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>To define a function in rust you need to use the <code>fn</code> keyword. <code>add</code> is the function's name. <code>(x: i32, y: i32)</code> are the parameters. Parameter types are always required. <code>-&gt; i32</code> this means the function returns an <code>i32</code> type and the body is inside the <code>{}</code>.</p> <h3 id="return-values">Return Values</h3> <p>In Rust, the last expression is a function body is automatically returned, that's why we didn't have a return keyword in the above function.</p> <blockquote> <p><strong>Statements</strong> end with a semicolon <code>;</code> and do not produce a value but <strong>Expressions</strong> do not end with a semicolon and produce a value.</p> </blockquote> <p>If you add a semicolon to the last line, it becomes a statement, produces no value and the function now returns <code>()</code> (this is called a unit type, basically nothing) instead of <code>i32</code> and this would be a compilation error.</p> <p>You can also keep it simple and use the return keyword:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> check</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">x</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> i32</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> x</span><span style="color: #94E2D5;"> &lt;</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // explicit return</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> x</span><span style="color: #9399B2;font-style: italic;"> // implicit return</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="control-flow">Control Flow</h2> <h3 id="if-else">If/Else</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> number</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 7</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">if</span><span> number</span><span style="color: #94E2D5;"> &lt;</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;less than 5&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span><span style="color: #CBA6F7;"> else if</span><span> number</span><span style="color: #94E2D5;"> ==</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;exactly 5&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;greater than 5&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>In Rust, the condition doesn't need parentheses but the body must be inside the curly braces.</p> <h3 id="if-is-an-expression"><code>If</code> is an Expression</h3> <p>This is important to remember that in Rust, <code>if</code> is not just a statement, its an expression that produces a value:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> result</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if</span><span> number</span><span style="color: #94E2D5;"> %</span><span style="color: #FAB387;"> 2</span><span style="color: #94E2D5;"> ==</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;"> {</span><span style="color: #A6E3A1;"> &quot;even&quot;</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span><span style="color: #A6E3A1;"> &quot;odd&quot;</span><span style="color: #9399B2;"> };</span></span></code></pre> <p>Note that both the branches should produce the same type otherwise the compilation will fail.</p> <h3 id="loop">Loop</h3> <p><code>loop</code> runs a block of code forever until you explicitly break out of it:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> count</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">loop</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> count</span><span style="color: #94E2D5;"> +=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> count</span><span style="color: #94E2D5;"> ==</span><span style="color: #FAB387;"> 5</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>loop</code> can also return a value through <code>break</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> result</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> loop</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> count</span><span style="color: #94E2D5;"> +=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> count</span><span style="color: #94E2D5;"> ==</span><span style="color: #FAB387;"> 10</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> break</span><span> count</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // returns this value from the loop</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="while-loop">While Loop</h3> <p>While loop runs as longs as a condition is true:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> n</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">while</span><span> n</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> n</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> n</span><span style="color: #94E2D5;"> -=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="for-loop">For Loop</h3> <p>The most common loop in Rust. The <code>for</code> loop iterates over a collection or a range:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// iterating over an array</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> arr</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> [</span><span style="color: #FAB387;">10</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 20</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 30</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">for</span><span> element</span><span style="color: #CBA6F7;"> in</span><span> arr</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> element</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// iterating over a range</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">for</span><span> i</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 0</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> i</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // prints 0, 1, 2, 3, 4</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;">// 0..=5 includes 5 (inclusive on both ends)</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">for</span><span> i</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 0</span><span style="color: #94E2D5;">..=</span><span style="color: #FAB387;">5</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> i</span><span style="color: #9399B2;">);</span><span style="color: #9399B2;font-style: italic;"> // prints 0, 1, 2, 3, 4, 5</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>0..5</code> is a range, it starts from 0 and goes up to but not including 5. But <code>0..=5</code> is an inclusive range that includes 5.</p> <h2 id="match">Match</h2> <p><code>match</code> is Rust's pattern matching construct. It compares a value against a series of <strong>patterns</strong> and executes the code for the first pattern that matches:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> x</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 3</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> x</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;one&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 2</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;two&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 3</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;three&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 4</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;four&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;other&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Each line inside the <code>match</code> is called an <strong>arm</strong>: <code>pattern =&gt; code</code> <code>_</code> is the wildcard pattern, it matches anything. It's used as a catch all default case. One thing you need to remember is that <code>match</code> is exhaustive. This means you must cover all the possible values. If you don't the compiler will reject your code.</p> <p>Like <code>if</code>, <code>match</code> is also an expression and can return a value:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> name</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> x</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;one&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 2</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;two&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;other&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">};</span></span></code></pre> <p>you can also match multiple patterns with <code>|</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">match</span><span> x</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;"> |</span><span style="color: #FAB387;"> 2</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;one or two&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 3</span><span style="color: #94E2D5;">..=</span><span style="color: #FAB387;">9</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;three through nine&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;something else&quot;</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="vectors-brief-introduction">Vectors (Brief Introduction)</h2> <p>Arrays have a fixed size known at compile time but sometimes you need a collection that can grow. This is where you can use a <code>Vec&lt;T&gt;</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let mut</span><span> v</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vector</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">char</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span>v</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">a</span><span style="color: #9399B2;">&#39;);</span></span> <span class="giallo-l"><span>v</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">b</span><span style="color: #9399B2;">&#39;);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> v</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">());</span><span style="color: #9399B2;font-style: italic;"> // 2</span></span></code></pre> <ul> <li><code>Vec::new()</code> creates an empty vector</li> <li><code>.push(value)</code> adds an element to the end</li> <li><code>.pop()</code> removes and returns the last element</li> <li><code>.len()</code> returns the number of elements</li> </ul> <h2 id="basic-string-types">Basic String Types</h2> <p>Rust has two main string types:</p> <ul> <li><code>&amp;str</code> this is a string slice. It is an immutable reference to a sequence of UTF-8 bytes. String literals like <code>"hello"</code> have type <code>&amp;str</code>.</li> <li><code>String</code> this is a heap allocated growable string. We will dive deep into these in the next article but for now just understand that if you need to have string literals, just use <code>&amp;str</code>. If you need to build a string dynamically, then use the <code>String</code> type.</li> </ul> <p>To iterate over each character of a string, you can use <code>chars()</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> s</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;hello&quot;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">for</span><span> c</span><span style="color: #CBA6F7;"> in</span><span> s</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">chars</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> c</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This is great, now you know everything to build your project. We are going to build a <strong>Brainfuck Interpreter</strong> in Rust.</p> <h2 id="the-brainfuck-interpreter">The Brainfuck Interpreter</h2> <p>Before writing any code, lets fully understand what we've building.</p> <h3 id="what-is-brainfuck">What is Brainfuck?</h3> <p>Brainfuck is a programming language with only 8 instructions. The entire language fits in 8 characters. Despite that, it can compute anything a normal programming language can.</p> <p>A brainfuck program operates on:</p> <ul> <li>A memory tape - an array of cells, each holding a number (a <code>u8</code>, so values 0-255).</li> <li>A data pointer - an index that points to the current cell on the tape. It starts at 0 (the leftmost cell)</li> <li>A program - a string of characters, most of which are instructions</li> </ul> <h3 id="the-8-instructions">The 8 Instructions</h3> <table><thead><tr><th>Character</th><th>What it does</th></tr></thead><tbody> <tr><td>&gt;</td><td>Move the data pointer one cell to the right</td></tr> <tr><td>&lt;</td><td>Move the data pointer one cell to the left</td></tr> <tr><td>+</td><td>Increment the value at the current cell by 1</td></tr> <tr><td>-</td><td>Decrement the values at the current cell by 1</td></tr> <tr><td>.</td><td>Output the current cell's value as an ASCII character</td></tr> <tr><td>,</td><td>Read one byte of input and store it in the current cell</td></tr> <tr><td>[</td><td>If the current cell is 0, jump forward to the matching ]</td></tr> <tr><td>]</td><td>If the current cell is non-zero, jump back to the matching [</td></tr> </tbody></table> <p>Every other character in a Brainfuck program is a comment, these gets simply ignored.</p> <h3 id="how-loop-works">How Loop Works</h3> <p><code>[</code> and <code>]</code> together form a loop. Let me explain:</p> <ul> <li>When you hit <code>[:</code> check the current cell. If its <code>0</code>, skip everything until the matching <code>]</code>. If its non zero, enter the loop body.</li> <li>When you hit <code>]:</code> check the current cell. If its non-zero, jump back to the matching <code>[</code>. If its 0, exit the loop. This is basically a <code>while (cell != 0) {...}</code> loop.</li> </ul> <h2 id="what-we-need-to-build">What We Need to Build</h2> <ol> <li>A memory tape</li> <li>A data pointer</li> <li>A way to iterate through the program instruction by instruction basically a program counter (pc) as a <code>usize</code></li> <li>Bracket matching when we hit <code>[</code> or <code>]</code>, we need to find the matching counterpart. We will precompute this into a map before running.</li> </ol> <h3 id="create-the-project">Create the Project</h3> <p>Let's start build our brainfuck interpreter. Open up your terminal and create a new project:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> new brainfuck-interpreter</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> brainfuck-interpreter</span></span></code></pre> <p>Open the project in your preferred editor and open the <code>src/main.rs</code> file and delete all the code</p> <h3 id="the-memory-tape-and-pointers">The Memory Tape and Pointers</h3> <p>Type this into <code>src/main.rs</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> program</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;++++++++[&gt;++++[&gt;++&gt;+++&gt;+++&gt;+&lt;&lt;&lt;&lt;-]&gt;+&gt;+&gt;-&gt;&gt;+[&lt;]&lt;-]&gt;&gt;.&gt;---.+++++++..+++.&gt;&gt;.&lt;-.&lt;.+++.------.--------.&gt;&gt;+.&gt;++.&quot;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> tape</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> [</span><span style="color: #FAB387;">0</span><span style="color: #CBA6F7;">u8</span><span style="color: #9399B2;">;</span><span style="color: #FAB387;"> 30000</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> dp</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> pc</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did:</p> <ul> <li><code>let program = "..."</code> this is a brainfuck program that prints "Hello World!". It's just a <code>&amp;str</code>(string literal). Our interpreter will read through it character by character.</li> <li><code>let mut tape = [0u8; 30000]</code> this is our memory tape. This creates an array of 30,000 elements, each of them initialized to <code>0</code>, and each of them is of type <code>u8</code>(values 0-255). We need <code>mut</code> because instructions <code>+</code> and <code>-</code> will modify the cells.</li> <li><code>let mut dp: usize = 0</code> dp stands for <strong>data pointer</strong>. It's the index into tape that points to the current cell. It starts at 0. Its <code>usize</code> because array indices in Rust must be <code>usize</code>.</li> <li><code>let mut pc: usize = 0</code> pc stands for <strong>program counter</strong>. Its the index into program pointing at the current instruction. It starts at 0.</li> </ul> <h3 id="precomputing-bracket-matches">Precomputing Bracket Matches</h3> <p>Before we run the program, we'll precompute where every <code>[</code> matches with its <code>]</code> and vice versa. This way, when we need to jump, we just do a lookup instead of scanning through the program every time. We'll store this in a <code>Vec</code> where the index is the position of <code>[</code> or <code>]</code> and the value is the position of its matching counterpart.</p> <p>Add this before main, as a separate function:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> build_bracket_map</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">program</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">str</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">usize</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> bytes</span><span style="color: #94E2D5;"> =</span><span> program</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">as_bytes</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> len</span><span style="color: #94E2D5;"> =</span><span> bytes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> map</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> vec!</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">0</span><span style="color: #CBA6F7;">usize</span><span style="color: #9399B2;">;</span><span> len</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> stack</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">usize</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Vec</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> i</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 0</span><span style="color: #94E2D5;">..</span><span>len</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> bytes</span><span style="color: #9399B2;">[</span><span>i</span><span style="color: #9399B2;">] {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">[</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> stack</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>i</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">]</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> open</span><span style="color: #94E2D5;"> =</span><span> stack</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">pop</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">expect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Unmatched ]&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> map</span><span style="color: #9399B2;">[</span><span>open</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;"> =</span><span> i</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> map</span><span style="color: #9399B2;">[</span><span>i</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;"> =</span><span> open</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {}</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> !</span><span>stack</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_empty</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> panic!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Unmatched [&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> map</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain everything:</p> <ul> <li><code>fn build_bracket_map(program: &amp;str) -&gt; Vec&lt;usize&gt;</code> this function takes a <code>&amp;str</code>(the program text) and returns a <code>Vec&lt;usize&gt;</code>(the bracket map)</li> <li><code>let bytes = program.as_bytes()</code> here <code>as_bytes()</code> converts the <code>&amp;str</code> into a slice of raw bytes <code>&amp;[u8]</code>. This lets us compare characters as byte values using <code>b'['</code> syntax(a byte literal). Its slightly more efficient than working with <code>char</code> here and brainfuck only uses ASCII characters so its completely valid.</li> <li><code>let mut map = vec![0usize; len]</code> here <code>vec![value; len]</code> is a macro that creates a <code>Vec</code> with <code>count</code> elements all set to <code>value</code>. So this creates a vector of <code>len</code> zeroes. Here, every position starts as <code>0</code>.</li> <li><code>let mut stack: Vec&lt;usize&gt; = Vec::new()</code> this is our stack for tracking open brackets. When we see a <code>[</code>, we push its position. When we see a <code>]</code>, we pop the most recent <code>[</code> position because that is its matching opening bracket.</li> <li><code>for i in 0..len</code> loop here we iterate through every index of the program <ul> <li><code>match bytes[i]</code> we match on the byte at position <code>i</code> <ul> <li><code>b'[' =&gt; stack.push(i)</code> when we see an open bracket, we push its index onto the stack.</li> <li><code>b']'</code> when we see a close bracket <ul> <li><code>stack.pop()</code> removes and returns the last pushed index(the matching <code>[</code>)</li> <li><code>.expect("Unmatched ]")</code> if the stack is empty, there's no matching <code>[</code>, so we crash with this error message. <code>.expect()</code> is a method on <code>Option</code> that either unwraps the value or panics with your message. We'll cover <code>Option</code> deeply later, but for now <code>pop()</code> returns <code>None</code> if the stack is empty and <code>expect()</code> handles that.</li> <li><code>map[open] = i</code> this means at the <code>[</code> position, the jump target is <code>]</code></li> <li><code>map[i] = open</code> this means at the <code>]</code> position, the jump target is <code>[</code></li> </ul> </li> <li><code>_ =&gt; {}</code> for any other character, we will just ignore and do nothing</li> </ul> </li> </ul> </li> <li><code>if !stack.is_empty() {panic!(...)}</code> after processing the whole program, if the stack still has entries, that means there are unmatched <code>[</code>. <code>panic!</code> crashes the program with a message</li> </ul> <h3 id="the-main-execute-loop">The Main Execute Loop</h3> <p>Now back inside <code>main</code> function, after the variable declarations, call <code>build_bracket_map</code> and then write the execution loop:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> program</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;++++++++[&gt;++++[&gt;++&gt;+++&gt;+++&gt;+&lt;&lt;&lt;&lt;-]&gt;+&gt;+&gt;-&gt;&gt;+[&lt;]&lt;-]&gt;&gt;.&gt;---.+++++++..+++.&gt;&gt;.&lt;-.&lt;.+++.------.--------.&gt;&gt;+.&gt;++.&quot;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> tape</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> [</span><span style="color: #FAB387;">0</span><span style="color: #CBA6F7;">u8</span><span style="color: #9399B2;">;</span><span style="color: #FAB387;"> 30000</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> dp</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> pc</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> bracket_map</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> build_bracket_map</span><span style="color: #9399B2;">(</span><span>program</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> bytes</span><span style="color: #94E2D5;"> =</span><span> program</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">as_bytes</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> while</span><span> pc</span><span style="color: #94E2D5;"> &lt;</span><span> bytes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> bytes</span><span style="color: #9399B2;">[</span><span>pc</span><span style="color: #9399B2;">] {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">&gt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;"> =&gt;</span><span> dp</span><span style="color: #94E2D5;"> +=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;"> =&gt;</span><span> dp</span><span style="color: #94E2D5;"> -=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">+</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;"> =&gt;</span><span> tape</span><span style="color: #9399B2;">[</span><span>dp</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;"> =</span><span> tape</span><span style="color: #9399B2;">[</span><span>dp</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">wrapping_add</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">-</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;"> =&gt;</span><span> tape</span><span style="color: #9399B2;">[</span><span>dp</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;"> =</span><span> tape</span><span style="color: #9399B2;">[</span><span>dp</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">wrapping_sub</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">1</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">.</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> print!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> tape</span><span style="color: #9399B2;">[</span><span>dp</span><span style="color: #9399B2;">]</span><span style="color: #CBA6F7;"> as</span><span style="color: #F9E2AF;font-style: italic;"> char</span><span style="color: #9399B2;">),</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">,</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span><span style="color: #9399B2;font-style: italic;"> /* input not needed for Hello World */</span><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">[</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> tape</span><span style="color: #9399B2;">[</span><span>dp</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;"> ==</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> pc</span><span style="color: #94E2D5;"> =</span><span> bracket_map</span><span style="color: #9399B2;">[</span><span>pc</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> b</span><span style="color: #9399B2;">&#39;</span><span style="color: #A6E3A1;">]</span><span style="color: #9399B2;">&#39;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> tape</span><span style="color: #9399B2;">[</span><span>dp</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;"> !=</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> pc</span><span style="color: #94E2D5;"> =</span><span> bracket_map</span><span style="color: #9399B2;">[</span><span>pc</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {}</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span> pc</span><span style="color: #94E2D5;"> +=</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain this:</p> <ul> <li><code>while pc &lt; bytes.len()</code> this keep executing as long as the program counter hasn't gone past the end of the program.</li> <li><code>b'&gt;' =&gt; dp += 1</code> moves the data pointer right, just incrementing the index</li> <li><code>b'&lt;' =&gt; dp -= 1</code> moves the data pointer left, just decrementing the index</li> <li><code>b'+' =&gt; tape[dp].wrapping_add(1)</code> this increments the current cell. We use <code>.wrapping_add(1)</code> instead of <code>tape[dp] += 1</code> because our cells are <code>u8</code>(0-255). If the value is 255 and you add 1, a normal += would panic in debug mode due to integer overflow. The <code>.wrapping_add</code> instead wraps around to 0. This is standard brainfuck behaviour.</li> <li><code>b'-' =? tape[dp].wrapping_sub(1)</code> this decrements the current cell. Same idea as add operation.</li> <li><code>b'.' =&gt; print!("{}", tape[dp] as char)</code> this prints the current cell as an ASCII character. <code>tape[dp] as char</code> is a type cast from <code>u8</code> to <code>char</code> type. For example, the value <code>72</code> becomes <code>H</code>. <code>print!</code>(without <code>ln</code>) prints without creating a newline.</li> <li><code>b','</code> we leave it as an empty block as we are not taking input dynamically.</li> <li><code>b'['</code> if the current cell is <code>0</code>, then jump to the matching <code>]</code> by setting <code>pc = bracket_map[pc]</code>. The <code>pc += 1</code> at the bottom of the loop then moves us past the <code>]</code>.</li> <li><code>b']'</code> if the current cell is non-zero, then jump back to the matching <code>[</code></li> <li><code>_ =&gt; {}</code> we are using this again to ignore any non instruction character</li> <li><code>pc += 1</code> after processing each instruction, move the program counter to the next character</li> <li><code>println!()</code> after the program finishes, it prints a newline so your terminal prompt appears on a fresh line.</li> </ul> <p>Finally, we covered a bunch of stuff and also built our project. Now lets try running it and see it in action. In your terminal, type:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> run</span></span></code></pre> <p>You should see an output like:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Compiling</span><span style="color: #A6E3A1;"> brainfuck-interpreter v0.1.0</span><span> (/Users/.../.../.../brainfuck-interpreter)</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Finished</span><span style="color: #94E2D5;"> `</span><span style="color: #89B4FA;font-style: italic;">dev</span><span style="color: #94E2D5;">`</span><span style="color: #89B4FA;font-style: italic;"> profile</span><span> [unoptimized</span><span style="color: #A6E3A1;"> + debuginfo] target</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">s</span><span style="color: #9399B2;">)</span><span style="color: #A6E3A1;"> in 0.10s</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Running</span><span style="color: #94E2D5;"> `</span><span style="color: #89B4FA;font-style: italic;">target/debug/brainfuck-interpreter</span><span style="color: #94E2D5;">`</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Hello</span><span style="color: #A6E3A1;"> World!</span></span></code></pre><h2 id="conclusion">Conclusion</h2> <p>In this post, you understood most of basic common things in Rust and build a simple brainfuck interpreter in Rust. In the next one, you are going to learn about ownership, borrowing and slices and build a <strong>mini grep clone</strong> that's gonna be fun. I hope to see you soon. Till then, goodbye!</p> 2026-03-31T00:00:00+00:00 2026-03-31T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/wtf-is-a-supply-chain-attack/ <p><img src="/images/axios-issue.webp" alt="Axios supply chain issue screenshot" /></p> <p>Two major open source libraries LiteLLM and axios(still developing story) were compromised within a week of each other. In this article, you are going to learn what supply chain attacks are, why they keep working and what you need to know right now.</p> <h2 id="what-is-a-supply-chain-attack">What is a Supply Chain Attack?</h2> <p>When you write software, you pull packages written by other people like pulling packages from PyPI, npm or elsewhere. Those packages might pull in more packages of their own. That entire web of external code is your software supply chain.</p> <p>A supply chain attack targets something your code actually trusts. If an attacker get malicious code into a library you install. Then, its game over. It'll have access to your files, secrets, infra.</p> <h2 id="axios-march-31-2026-issue-still-developing">Axios (March 31, 2026) Issue (Still Developing)</h2> <p>Axios is one of the most used HTTP client library in JavaScript. This story just broke today (31st March 2026) and details are still coming, but lets just take this as a case study to understand supply chain attack clearly.</p> <p>An attacker compromised the npm account of a lead axios maintainer, changed the account email id to an anon address and published two poisoned versions manually.</p> <p>The attacker added a dependency called <code>plain-crypto-js</code>. This package is never actually used by axios. It was not there previously. It's only purpose is to run a <code>postinstall</code> script that drops a Remote Access Trojan (RAT) targeting macOS, Windows and Linux. The RAT contacts a command and control server, downloads platform specific payloads, then deletes its own traces.</p> <h2 id="what-to-check-right-now">What to Check Right Now</h2> <p>If you have installed <code>axios@1.14.1</code> or <code>axios@0.30.4</code> please remove them or revert back to a safer version. You can revert back these to <code>axios@1.14.0</code> and <code>axios@0.30.3</code></p> <blockquote> <p>Update 1: The axios version has been rolled back to a safer version. <img src="/images/axios-rolled-back.png" alt="axios-rolled-back-to-safer-version" /></p> </blockquote> <p>I'll update the story as new confirmed details come in.</p> 2026-03-20T00:00:00+00:00 2026-03-20T00:00:00+00:00 Unknown https://blog.sheerluck.dev/posts/welcome-to-mrsheerluck-blog/

<p>Hi,</p>