https://blog.sheerluck.dev Personal notes on engineering, systems, and software. Zola en Wed, 15 Jul 2026 00:00:00 +0000 Wed, 15 Jul 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-axum-persistence-and-transaction-by-building-a-bookmark-manager/ https://blog.sheerluck.dev/posts/learn-axum-persistence-and-transaction-by-building-a-bookmark-manager/ <p>In Part 1 and Part 2, we built a URL shortener and a Pastebin API. Both had the same limitation: data lived in a <code>HashMap</code> wrapped in <code>Arc&lt;RwLock&lt;...&gt;&gt;</code>. Restart the server, everything disappears. That was intentional. We were learning routing, extractors, and error handling, persistence would have been a distraction.</p> <p><img src="/images/axum-bookmark-manager.png" alt="Axum Bookmark Manager" /></p> <p>In this post, we are going to fix that. We will replace the <code>HashMap</code> with PostgreSQL and SQLx. Adding a real database introduces connection pooling, schema design, migrations, compile-time-checked queries, joins, pagination, the N+1 query trap, explicit transactions, and isolation levels. Every one of these concepts matters in production, and every one of them is easier to learn in a single-service project than under the pressure of a distributed system.</p> <p>Let's start, I can't wait.</p> <p>Get the source code from <a rel="external" href="https://github.com/MrSheerluck/rust-bookmark-manager-api">here</a></p> <h2 id="the-problem-with-in-memory-storage">The Problem with In-Memory Storage</h2> <p>The <code>HashMap</code> we used in Parts 1 and 2 has three problems. First, data is lost on restart. Second, capacity is bounded by available RAM. Third, and most subtly, there is no transactional safety. In Part 2, we created a paste by inserting it into a map. That operation is atomic only because <code>HashMap::insert</code> is a single method call. The moment you have a multi-step operation like "create a bookmark and attach three tags" and the third tag insertion fails, you have a bookmark in the map with two orphaned tags and no way to undo the first two inserts.</p> <p>Real persistence solves all three: durability (survives restarts), scalability (data lives on disk, not in RAM), and atomicity (all-or-nothing multi-step operations via transactions).</p> <h2 id="what-is-sqlx">What is SQLx?</h2> <p>SQLx is a Rust crate for talking to SQL databases. It is async-native (built on Tokio), supports PostgreSQL, MySQL, and SQLite, and provides connection pooling. But its defining feature, the one that matters to this article is <strong>compile-time checking of SQL queries</strong>.</p> <p>In most ORMs and query builders, a typo in a column name or a type mismatch between a Rust struct and a SQL column is a runtime error. You write <code>SELECT tite FROM bookmarks</code>, deploy to production, and find out when the first request hits that endpoint and panics. SQLx validates those queries during compilation. It parses every SQL string in <code>query!</code> and <code>query_as!</code> and verifies it against either a live database schema or the cached metadata in the <code>.sqlx/</code> directory. If a column is missing, the types don't match, or the SQL is invalid, compilation fails before the application ever runs.</p> <p><code>cargo sqlx prepare</code> connects to your database and generates query metadata in the <code>.sqlx/</code> directory. During offline compilation, the macros read this metadata instead of connecting to a live database. This allows SQL queries to remain compile-time checked even in CI environments without database access. If a column is missing, <code>cargo build</code> fails with a clear message pointing to the exact query and the exact mismatch. For queries written with SQLx's checked macros, typos and schema mismatches are caught before the application is built.</p> <blockquote> <p><strong>Why not an ORM like Diesel?</strong> SQLx is deliberately <em>not</em> an ORM. It does not generate SQL from Rust structs. You write raw SQL in macros, and SQLx checks it for you. This gives you full control over the SQL joins, window functions, CTEs while still catching mistakes at compile time. If you prefer ORMs, Diesel is the go-to in Rust. This series uses SQLx because the goal is to learn backend engineering, and I want you to understand the SQL that your application is actually running.</p> </blockquote> <h2 id="connection-pooling">Connection Pooling</h2> <p>A connection pool is a cache of open database connections. Creating a new TCP connection to Postgres for every request is slow, TLS handshakes, authentication, and session setup take milliseconds. A pool keeps a set of connections open and ready, handing one to each request that needs it and returning it when the request is done.</p> <p>SQLx provides <code>PgPool</code> for 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> pool</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> PgPoolOptions</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;">max_connections</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: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">connect</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>database_url</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span></code></pre> <p><code>max_connections(10)</code> limits the pool to 10 simultaneous connections. Every request handler can call <code>pool.acquire()</code> to get a connection from the pool. If all 10 are in use, the 11th request waits until one is returned. Acquiring a connection from the pool is much cheaper than establishing a new database connection because the TCP connection, authentication, and session setup have already been completed.</p> <p>The pool itself is cheap to clone. <code>PgPool</code> wraps an <code>Arc&lt;PoolInner&gt;</code>, so cloning it just increments a reference count exactly like cloning an <code>Arc</code>. This means you can put the pool directly in your <code>AppState</code> and use <code>#[derive(Clone)]</code> on the state struct without wrapping the pool in an extra <code>Arc</code>:</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> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> AppState</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> pool</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> PgPool</span><span style="color: #9399B2;">,</span><span style="color: #9399B2;font-style: italic;"> // no Arc needed, PgPool is already Arc inside</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h2 id="database-migrations">Database Migrations</h2> <p>A schema changes over time. You add a <code>description</code> column to <code>bookmarks</code>, or an index on <code>created_at</code>. These changes are called migrations. SQLx provides a CLI for managing them:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo install sqlx-cli --no-default-features --features postgres</span></span> <span class="giallo-l"><span>sqlx migrate add initial_schema</span></span></code></pre> <p>This creates a file in <code>migrations/</code> with a timestamp prefix. You write your SQL in that file, and then:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>sqlx migrate run</span></span></code></pre> <p>This applies any unapplied migrations to your database. SQLx tracks which migrations have been run in a <code>_sqlx_migrations</code> table, so it never applies the same migration twice.</p> <p>Our application also runs migrations at startup via <code>sqlx::migrate!("./migrations").run(&amp;pool)</code>. This keeps the schema synchronized with the application during development. Some production deployments instead run migrations as a separate deployment step before starting the application.</p> <h2 id="project-setup">Project Setup</h2> <p>We need PostgreSQL. The simplest way is Docker:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>docker compose up -d</span></span></code></pre> <p>Create a <code>docker-compose.yml</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="yaml"><span class="giallo-l"><span style="color: #89B4FA;">services</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> postgres</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> image</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> postgres:16-alpine</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> container_name</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> bookmark_db</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> restart</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> unless-stopped</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> ports</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #9399B2;"> -</span><span style="color: #A6E3A1;"> &quot;5432:5432&quot;</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> environment</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> POSTGRES_USER</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> bookmark</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> POSTGRES_PASSWORD</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> bookmark</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> POSTGRES_DB</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> bookmark</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> volumes</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #9399B2;"> -</span><span style="color: #A6E3A1;"> pgdata:/var/lib/postgresql/data</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #89B4FA;">volumes</span><span style="color: #94E2D5;">:</span></span> <span class="giallo-l"><span style="color: #89B4FA;"> pgdata</span><span style="color: #94E2D5;">:</span></span></code></pre> <p>This gives us Postgres 16 on port 5432, with a <code>bookmark</code> database, user, and password. The <code>pgdata</code> volume persists data across container restarts.</p> <p>Create a <code>.env</code> file for SQLx:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>DATABASE_URL=postgres://bookmark:bookmark@localhost:5432/bookmark</span></span></code></pre> <p>Create the project:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo new bookmark_manager</span></span> <span class="giallo-l"><span>cd bookmark_manager</span></span></code></pre> <p>Open <code>Cargo.toml</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;bookmark_manager&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>axum</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.8&quot;</span></span> <span class="giallo-l"><span>tokio</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&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;full&quot;</span><span style="color: #9399B2;">] }</span></span> <span class="giallo-l"><span>serde</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&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;derive&quot;</span><span style="color: #9399B2;">] }</span></span> <span class="giallo-l"><span>serde_json</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&quot;</span></span> <span class="giallo-l"><span>sqlx</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.8&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;runtime-tokio&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;tls-rustls&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;postgres&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;migrate&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;chrono&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;uuid&quot;</span><span style="color: #9399B2;">] }</span></span> <span class="giallo-l"><span>uuid</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&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;v4&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;serde&quot;</span><span style="color: #9399B2;">] }</span></span> <span class="giallo-l"><span>chrono</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.4&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;serde&quot;</span><span style="color: #9399B2;">] }</span></span> <span class="giallo-l"><span>dotenvy</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.15&quot;</span></span></code></pre> <p>The new dependencies worth explaining:</p> <ul> <li><code>sqlx</code> with five features: <code>runtime-tokio</code> (async runtime), <code>tls-rustls</code> (TLS for secure connections), <code>postgres</code> (database driver), <code>migrate</code> (run migrations from code), and <code>chrono</code> + <code>uuid</code> (type support for <code>DateTime&lt;Utc&gt;</code> and <code>Uuid</code> columns). Without the <code>chrono</code> feature, SQLx wouldn't know how to read a <code>TIMESTAMPTZ</code> column into Rust's <code>DateTime&lt;Utc&gt;</code>.</li> <li><code>dotenvy</code> loads the <code>.env</code> file at startup so <code>DATABASE_URL</code> is available as an environment variable.</li> <li><code>uuid</code> now has the <code>serde</code> feature in addition to <code>v4</code> for serializing/deserializing UUIDs in JSON.</li> </ul> <p>Install <code>sqlx-cli</code> and prepare the offline query cache:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo install sqlx-cli --no-default-features --features postgres</span></span> <span class="giallo-l"><span>cargo sqlx prepare</span></span></code></pre> <p>The <code>prepare</code> command connects to your database, extracts the current schema, and generates a <code>.sqlx/</code> directory with cached query metadata. This is what the compiler uses to check your SQL. You should commit the <code>.sqlx/</code> directory to version control. It contains the metadata SQLx uses to verify queries during offline compilation, allowing CI to build the project without requiring a running database.</p> <h2 id="the-schema">The Schema</h2> <p>Create <code>migrations/20260712000000_initial_schema.sql</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">CREATE</span><span> EXTENSION </span><span style="color: #CBA6F7;">IF NOT EXISTS</span><span style="color: #A6E3A1;"> &quot;uuid-ossp&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">CREATE TABLE</span><span style="color: #89B4FA;font-style: italic;"> bookmarks</span><span> (</span></span> <span class="giallo-l"><span> id UUID </span><span style="color: #CBA6F7;">PRIMARY KEY DEFAULT</span><span> uuid_generate_v4</span><span style="color: #9399B2;">()</span><span>,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> url TEXT NOT NULL</span><span>,</span></span> <span class="giallo-l"><span> title </span><span style="color: #CBA6F7;">TEXT NOT NULL</span><span>,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> description TEXT</span><span>,</span></span> <span class="giallo-l"><span> created_at </span><span style="color: #CBA6F7;">TIMESTAMPTZ NOT NULL DEFAULT NOW</span><span style="color: #9399B2;">()</span><span>,</span></span> <span class="giallo-l"><span> updated_at </span><span style="color: #CBA6F7;">TIMESTAMPTZ NOT NULL DEFAULT NOW</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">CREATE TABLE</span><span style="color: #89B4FA;font-style: italic;"> tags</span><span> (</span></span> <span class="giallo-l"><span> id UUID </span><span style="color: #CBA6F7;">PRIMARY KEY DEFAULT</span><span> uuid_generate_v4</span><span style="color: #9399B2;">()</span><span>,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> name TEXT NOT NULL UNIQUE</span></span> <span class="giallo-l"><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">CREATE TABLE</span><span style="color: #89B4FA;font-style: italic;"> bookmark_tags</span><span> (</span></span> <span class="giallo-l"><span> bookmark_id UUID </span><span style="color: #CBA6F7;">NOT NULL REFERENCES</span><span> bookmarks(id) </span><span style="color: #CBA6F7;">ON DELETE CASCADE</span><span>,</span></span> <span class="giallo-l"><span> tag_id UUID </span><span style="color: #CBA6F7;">NOT NULL REFERENCES</span><span> tags(id) </span><span style="color: #CBA6F7;">ON DELETE CASCADE</span><span>,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> PRIMARY KEY</span><span> (bookmark_id, tag_id)</span></span> <span class="giallo-l"><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">CREATE INDEX</span><span style="color: #89B4FA;font-style: italic;"> idx_bookmarks_created_at</span><span style="color: #CBA6F7;"> ON</span><span> bookmarks(created_at </span><span style="color: #CBA6F7;">DESC</span><span>);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">CREATE INDEX</span><span style="color: #89B4FA;font-style: italic;"> idx_bookmark_tags_bookmark_id</span><span style="color: #CBA6F7;"> ON</span><span> bookmark_tags(bookmark_id);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">CREATE INDEX</span><span style="color: #89B4FA;font-style: italic;"> idx_bookmark_tags_tag_id</span><span style="color: #CBA6F7;"> ON</span><span> bookmark_tags(tag_id);</span></span></code></pre> <p>Now, let me explain each table and the design decisions.</p> <h3 id="bookmarks">bookmarks</h3> <p>The core entity. Each row has a UUID primary key, a URL (the thing we are bookmarking), a title, an optional description, and two timestamps. <code>UUID</code> primary keys have two advantages over auto-incrementing integers in an API: they are unguessable (no sequential IDs to enumerate), and they can be generated client-side or server-side without coordination.</p> <p><code>uuid_generate_v4()</code> generates a random (v4) UUID. This requires the <code>uuid-ossp</code> extension, enabled at the top of the migration. Random UUIDs are slightly slower to insert than sequential identifiers because they fragment B-tree indexes. For many web applications this overhead is acceptable, while write-heavy systems often prefer sequential identifiers or newer UUID variants such as UUIDv7.</p> <h3 id="tags">tags</h3> <p>Tags are shared across bookmarks. A tag like <code>rust</code> can be attached to many bookmarks. The <code>name</code> column has a <code>UNIQUE</code> constraint, you cannot insert the same tag name twice. This constraint is essential because without it, two concurrent requests could create duplicate <code>rust</code> rows in the <code>tags</code> table, and the <code>bookmark_tags</code> junction table would then reference two different rows for what should be the same tag.</p> <h3 id="bookmark-tags">bookmark_tags</h3> <p>This is the <strong>junction table</strong> (also called a join table, association table, or linking table). It models the many-to-many relationship between bookmarks and tags. One bookmark can have many tags. One tag can be attached to many bookmarks. A relational database cannot represent this directly with a foreign key in either table, you need a third table that pairs them.</p> <p>Each row in <code>bookmark_tags</code> is a pair of foreign keys: <code>bookmark_id</code> references <code>bookmarks(id)</code>, and <code>tag_id</code> references <code>tags(id)</code>. The composite primary key <code>(bookmark_id, tag_id)</code> ensures you can never attach the same tag to the same bookmark twice. <code>ON DELETE CASCADE</code> on both foreign keys means deleting a bookmark automatically removes all its tag associations, and deleting a tag removes all its associations.</p> <h3 id="indexes">Indexes</h3> <p>Three indexes, designed for our access patterns:</p> <ul> <li><code>idx_bookmarks_created_at</code> supports the <code>ORDER BY created_at DESC</code> used in the list endpoint. Without this index, Postgres would sort the entire <code>bookmarks</code> table on every request.</li> <li><code>idx_bookmark_tags_bookmark_id</code> supports the <code>WHERE bt.bookmark_id = $1</code> join used to fetch tags for a bookmark.</li> <li><code>idx_bookmark_tags_tag_id</code> supports the <code>WHERE t.name = $1</code> join used to filter bookmarks by tag.</li> </ul> <p>Indexes are a trade-off: they speed up reads at the cost of slower writes (every insert must also update the index) and additional disk usage. For this application, reads are far more common than writes, users browse their bookmarks more often than they create new ones so the indexes are worth it.</p> <h2 id="the-project-bookmark-manager">The Project: Bookmark Manager</h2> <p>Our program will:</p> <ul> <li>Accept <code>POST /bookmarks</code> with a JSON body containing a URL, title, optional description, and optional tags</li> <li>Create the bookmark and attach any tags in a single transaction</li> <li>Accept <code>GET /bookmarks</code> with optional <code>?page=</code>, <code>?per_page=</code>, and <code>?tag=</code> query parameters for paginated listing</li> <li>Accept <code>GET /bookmarks/{id}</code> that returns a single bookmark with its tags</li> <li>Accept <code>PUT /bookmarks/{id}</code> to update a bookmark's fields</li> <li>Accept <code>DELETE /bookmarks/{id}</code> to delete a bookmark (tags are cascade-deleted)</li> <li>Accept <code>POST /bookmarks/{id}/tags</code> to attach new tags to an existing bookmark</li> <li>Accept <code>DELETE /bookmarks/{id}/tags/{tag_id}</code> to detach a single tag</li> </ul> <h3 id="data-model">Data Model</h3> <p>The internal <code>Bookmark</code> struct maps directly to the <code>bookmarks</code> table:</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;"> Serialize</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">FromRow</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Bookmark</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Uuid</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> url</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> title</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> description</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;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> created_at</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> DateTime</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Utc</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> updated_at</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> DateTime</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Utc</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><code>#[derive(sqlx::FromRow)]</code> is what makes <code>query_as!(Bookmark, ...)</code> work. It generates code that reads each column from a database row and constructs a <code>Bookmark</code>. The field names in the struct must match the column names in the database, and the types must be compatible <code>Uuid</code> ↔ <code>UUID</code>, <code>String</code> ↔ <code>TEXT</code>, <code>Option&lt;String&gt;</code> ↔ nullable <code>TEXT</code>, <code>DateTime&lt;Utc&gt;</code> ↔ <code>TIMESTAMPTZ</code>. If any field is missing or has the wrong type, <code>cargo build</code> catches it.</p> <p><code>Tag</code> follows the same pattern:</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;"> Serialize</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">FromRow</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Tag</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Uuid</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><code>BookmarkResponse</code> is the external representation. It includes tags alongside the bookmark fields. This is a separate type from <code>Bookmark</code> , the internal <code>Bookmark</code> struct is a direct row mapping, while <code>BookmarkResponse</code> includes computed data (the joined tags):</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;"> Serialize</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> BookmarkResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Uuid</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> url</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> title</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> description</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;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> created_at</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> DateTime</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Utc</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> updated_at</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> DateTime</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Utc</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tags</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;">Tag</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>Why separate <code>BookmarkResponse</code> from <code>Bookmark</code>? <code>Bookmark</code> represents a single row in the <code>bookmarks</code> table. <code>BookmarkResponse</code> represents the JSON the client sees, which includes tags fetched from a separate query. The response type is a view, it combines data from multiple sources into one shape. The internal type is a model, it maps directly to storage. Keeping them separate lets you change the database schema without changing the API response shape, and vice versa.</p> <h3 id="the-full-code">The Full Code</h3> <p>Replace everything in <code>src/main.rs</code> 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;"> axum</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> extract</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">Path</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Query</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #9399B2;">},</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> http</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> response</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #9399B2;">},</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> routing</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span>delete</span><span style="color: #9399B2;">,</span><span> get</span><span style="color: #9399B2;">,</span><span> post</span><span style="color: #9399B2;">,</span><span> put</span><span style="color: #9399B2;">},</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Json</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Router</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;">use</span><span style="color: #F9E2AF;"> chrono</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">DateTime</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Utc</span><span style="color: #9399B2;">};</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> serde</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">Deserialize</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Serialize</span><span style="color: #9399B2;">};</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">postgres</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">PgPoolOptions</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">PgPool</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> uuid</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Uuid</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;">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;"> AppState</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> pool</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> PgPool</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;"> Serialize</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">FromRow</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Bookmark</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Uuid</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> url</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> title</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> description</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;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> created_at</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> DateTime</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Utc</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> updated_at</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> DateTime</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Utc</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: #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;"> Serialize</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">FromRow</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Tag</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Uuid</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> <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;"> Deserialize</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> CreateBookmarkRequest</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> url</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> title</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> description</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;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tags</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;">Vec</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">String</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> <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;"> Deserialize</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> UpdateBookmarkRequest</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> url</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;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> title</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;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> description</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;">String</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: #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;"> Serialize</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> BookmarkResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Uuid</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> url</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> title</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> description</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;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> created_at</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> DateTime</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Utc</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> updated_at</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> DateTime</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Utc</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tags</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;">Tag</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: #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;"> Deserialize</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> PaginationParams</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> page</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> per_page</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> tag</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;">String</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: #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;"> Serialize</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> PaginatedBookmarks</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> bookmarks</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;">BookmarkResponse</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> page</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> per_page</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> total</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> <span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> ValidationError</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;"> NotFound</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;"> InternalError</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> <span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> AppError</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_response</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;"> Response</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span style="color: #9399B2;"> (</span><span>status</span><span style="color: #9399B2;">,</span><span> message</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</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: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</span><span style="color: #9399B2;">(</span><span>msg</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">BAD_REQUEST</span><span style="color: #9399B2;">,</span><span> msg</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;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</span><span>msg</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">NOT_FOUND</span><span style="color: #9399B2;">,</span><span> msg</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;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">InternalError</span><span style="color: #9399B2;">(</span><span>msg</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;internal error: </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 style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">INTERNAL_SERVER_ERROR</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;internal server error&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> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> body</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">serde_json</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">json!</span><span style="color: #9399B2;">({</span><span style="color: #A6E3A1;"> &quot;error&quot;</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>status</span><span style="color: #9399B2;">,</span><span> body</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into_response</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;"> From</span><span style="color: #89DCEB;">&lt;</span><span>sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Error</span><span style="color: #89DCEB;">&gt;</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> AppError</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</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">err</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Error</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;"> match</span><span> err</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Error</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RowNotFound</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;resource not found&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: #9399B2;"> }</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">InternalError</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;database 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 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;">tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">main</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">async 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;"> dotenvy</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">dotenv</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> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> database_url</span><span style="color: #94E2D5;"> =</span></span> <span class="giallo-l"><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;">var</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;DATABASE_URL&quot;</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;DATABASE_URL must be set&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></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;"> PgPoolOptions</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;">max_connections</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: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">connect</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>database_url</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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 connect to database&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">migrate!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;./migrations&quot;</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 style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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 run migrations&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> state</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> AppState</span><span style="color: #9399B2;"> {</span><span> pool</span><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> app</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Router</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;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/bookmarks&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> post</span><span style="color: #9399B2;">(</span><span>create_bookmark</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/bookmarks&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> get</span><span style="color: #9399B2;">(</span><span>list_bookmarks</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/bookmarks/</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">id</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> get</span><span style="color: #9399B2;">(</span><span>get_bookmark</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/bookmarks/</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">id</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> put</span><span style="color: #9399B2;">(</span><span>update_bookmark</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/bookmarks/</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">id</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> delete</span><span style="color: #9399B2;">(</span><span>delete_bookmark</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/bookmarks/</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">id</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">/tags&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> post</span><span style="color: #9399B2;">(</span><span>attach_tags</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/bookmarks/</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">id</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">/tags/</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">tag_id</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> delete</span><span style="color: #9399B2;">(</span><span>detach_tag</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/healthz&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> get</span><span style="color: #9399B2;">(</span><span>healthz</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">with_state</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> listener</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">net</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">TcpListener</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">bind</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;127.0.0.1:3000&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span></span> <span class="giallo-l"><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;Listening on http://127.0.0.1:3000&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;"> axum</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">serve</span><span style="color: #9399B2;">(</span><span>listener</span><span style="color: #9399B2;">,</span><span> app</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> healthz</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">OK</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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> create_bookmark</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span>payload</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Json</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">CreateBookmarkRequest</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;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> payload</span><span style="color: #94E2D5;">.</span><span>url</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;">is_empty</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> ||</span><span> payload</span><span style="color: #94E2D5;">.</span><span>title</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;">is_empty</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;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;url and title must not be empty&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: #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> tx</span><span style="color: #94E2D5;"> =</span><span> state</span><span style="color: #94E2D5;">.</span><span>pool</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">begin</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;"> let</span><span> bookmark</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Bookmark</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;INSERT INTO bookmarks (url, title, description)</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> VALUES ($1, $2, $3)</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> RETURNING id, url, title, description, created_at, updated_at&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> payload</span><span style="color: #94E2D5;">.</span><span>url</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> payload</span><span style="color: #94E2D5;">.</span><span>title</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> payload</span><span style="color: #94E2D5;">.</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: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">fetch_one</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #94E2D5;"> *</span><span>tx</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> let mut</span><span> tags</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;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">ref</span><span> tag_names</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> payload</span><span style="color: #94E2D5;">.</span><span>tags </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> name</span><span style="color: #CBA6F7;"> in</span><span> tag_names</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> tag</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Tag</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;INSERT INTO tags (name) VALUES ($1)</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> ON CONFLICT (name) DO UPDATE SET name = EXCLUDED.name</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> RETURNING id, name&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> name</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_lowercase</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;">fetch_one</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #94E2D5;"> *</span><span>tx</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;INSERT INTO bookmark_tags (bookmark_id, tag_id) VALUES ($1, $2)&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> bookmark</span><span style="color: #94E2D5;">.</span><span>id</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tag</span><span style="color: #94E2D5;">.</span><span>id</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;">execute</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #94E2D5;"> *</span><span>tx</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> tags</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>tag</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> tx</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">commit</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><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: #F9E2AF;font-style: italic;"> StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">CREATED</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">BookmarkResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">id</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> url</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">url</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> title</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">title</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> description</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">description</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> created_at</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">created_at</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> updated_at</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">updated_at</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tags</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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> get_bookmark</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Path</span><span style="color: #9399B2;">(</span><span>id</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Path</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Uuid</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;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> bookmark</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Bookmark</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;SELECT id, url, title, description, created_at, updated_at FROM bookmarks WHERE id = $1&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> id</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;">fetch_optional</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">ok_or_else</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">||</span><span style="color: #F9E2AF;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;bookmark with id &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39; not found&quot;</span><span style="color: #9399B2;">,</span><span> id</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: #CBA6F7;"> let</span><span> tags</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Tag</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;SELECT t.id, t.name</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> FROM tags t</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> INNER JOIN bookmark_tags bt ON bt.tag_id = t.id</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> WHERE bt.bookmark_id = $1&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> bookmark</span><span style="color: #94E2D5;">.</span><span>id</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;">fetch_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><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 style="color: #89B4FA;font-style: italic;">Json</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">BookmarkResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">id</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> url</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">url</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> title</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">title</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> description</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">description</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> created_at</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">created_at</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> updated_at</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">updated_at</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tags</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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> list_bookmarks</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Query</span><span style="color: #9399B2;">(</span><span>params</span><span style="color: #9399B2;">)</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;">PaginationParams</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;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> page</span><span style="color: #94E2D5;"> =</span><span> params</span><span style="color: #94E2D5;">.</span><span>page</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;">1</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 style="color: #FAB387;">1</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> per_page</span><span style="color: #94E2D5;"> =</span><span> params</span><span style="color: #94E2D5;">.</span><span>per_page</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;">20</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clamp</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">1</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: #CBA6F7;"> let</span><span> offset</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span>page</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> *</span><span> per_page</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>bookmarks</span><span style="color: #9399B2;">,</span><span> total</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</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;">Bookmark</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> i64</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">ref</span><span> tag_name</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> params</span><span style="color: #94E2D5;">.</span><span>tag </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> total</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_scalar!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;SELECT COUNT(DISTINCT b.id)::bigint</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> FROM bookmarks b</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> INNER JOIN bookmark_tags bt ON bt.bookmark_id = b.id</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> INNER JOIN tags t ON t.id = bt.tag_id</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> WHERE t.name = $1&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tag_name</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_lowercase</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;">fetch_one</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span></span> <span class="giallo-l"><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> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> bookmarks</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Bookmark</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;SELECT DISTINCT b.id, b.url, b.title, b.description, b.created_at, b.updated_at</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> FROM bookmarks b</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> INNER JOIN bookmark_tags bt ON bt.bookmark_id = b.id</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> INNER JOIN tags t ON t.id = bt.tag_id</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> WHERE t.name = $1</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> ORDER BY b.created_at DESC</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> LIMIT $2 OFFSET $3&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tag_name</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_lowercase</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> per_page</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> offset</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;">fetch_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span>bookmarks</span><span style="color: #9399B2;">,</span><span> total</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> total</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_scalar!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;SELECT COUNT(*)::bigint FROM bookmarks&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">fetch_one</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span></span> <span class="giallo-l"><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> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> bookmarks</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Bookmark</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;SELECT id, url, title, description, created_at, updated_at</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> FROM bookmarks</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> ORDER BY created_at DESC</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> LIMIT $1 OFFSET $2&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> per_page</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> offset</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;">fetch_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span>bookmarks</span><span style="color: #9399B2;">,</span><span> total</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> bookmark_ids</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;">Uuid</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> bookmarks</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>b</span><span style="color: #94E2D5;">|</span><span> b</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">id</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: #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;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">FromRow</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> struct</span><span style="color: #F9E2AF;font-style: italic;"> TagWithBookmark</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Uuid</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> bookmark_id</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Uuid</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> all_tags</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;">TagWithBookmark</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if</span><span> bookmark_ids</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;"> 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 style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TagWithBookmark</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;SELECT t.id, t.name, bt.bookmark_id</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> FROM tags t</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> INNER JOIN bookmark_tags bt ON bt.tag_id = t.id</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> WHERE bt.bookmark_id = ANY($1)&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &amp;</span><span>bookmark_ids</span><span style="color: #CBA6F7;"> as</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">Uuid</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;">fetch_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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;"> 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;"> let mut</span><span> tags_by_bookmark</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;">Uuid</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;">Tag</span><span style="color: #89DCEB;">&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 style="color: #CBA6F7;"> for</span><span> row</span><span style="color: #CBA6F7;"> in</span><span> all_tags</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> tags_by_bookmark</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">entry</span><span style="color: #9399B2;">(</span><span>row</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">bookmark_id</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">or_default</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;font-style: italic;">Tag</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span> row</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">id</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> name</span><span style="color: #94E2D5;">:</span><span> row</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 style="color: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> bookmark_responses</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;">BookmarkResponse</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> bookmarks</span></span> <span class="giallo-l"><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;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>bookmark</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> tags</span><span style="color: #94E2D5;"> =</span><span> tags_by_bookmark</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 style="color: #94E2D5;">&amp;</span><span>bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">id</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">cloned</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 style="color: #F9E2AF;font-style: italic;"> BookmarkResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">id</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> url</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">url</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> title</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">title</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> description</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">description</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> created_at</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">created_at</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> updated_at</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">updated_at</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tags</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> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">Json</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">PaginatedBookmarks</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> bookmarks</span><span style="color: #94E2D5;">:</span><span> bookmark_responses</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> page</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> per_page</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> total</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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> update_bookmark</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Path</span><span style="color: #9399B2;">(</span><span>id</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Path</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Uuid</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span>payload</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Json</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">UpdateBookmarkRequest</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;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> existing</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Bookmark</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;SELECT id, url, title, description, created_at, updated_at FROM bookmarks WHERE id = $1&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> id</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;">fetch_optional</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">ok_or_else</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">||</span><span style="color: #F9E2AF;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;bookmark with id &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39; not found&quot;</span><span style="color: #9399B2;">,</span><span> id</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: #CBA6F7;"> let</span><span> url</span><span style="color: #94E2D5;"> =</span><span> payload</span><span style="color: #94E2D5;">.</span><span>url</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap_or</span><span style="color: #9399B2;">(</span><span>existing</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">url</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> title</span><span style="color: #94E2D5;"> =</span><span> payload</span><span style="color: #94E2D5;">.</span><span>title</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap_or</span><span style="color: #9399B2;">(</span><span>existing</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">title</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> description</span><span style="color: #94E2D5;"> =</span><span> payload</span><span style="color: #94E2D5;">.</span><span>description</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">or</span><span style="color: #9399B2;">(</span><span>existing</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">description</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> bookmark</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Bookmark</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;UPDATE bookmarks</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> SET url = $1, title = $2, description = $3, updated_at = NOW()</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> WHERE id = $4</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> RETURNING id, url, title, description, created_at, updated_at&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> url</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> title</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> description</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> id</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;">fetch_one</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> let</span><span> tags</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Tag</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;SELECT t.id, t.name</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> FROM tags t</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> INNER JOIN bookmark_tags bt ON bt.tag_id = t.id</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> WHERE bt.bookmark_id = $1&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> bookmark</span><span style="color: #94E2D5;">.</span><span>id</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;">fetch_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><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 style="color: #89B4FA;font-style: italic;">Json</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">BookmarkResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">id</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> url</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">url</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> title</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">title</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> description</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">description</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> created_at</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">created_at</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> updated_at</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">updated_at</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tags</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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> delete_bookmark</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Path</span><span style="color: #9399B2;">(</span><span>id</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Path</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Uuid</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;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</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;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;DELETE FROM bookmarks WHERE id = $1&quot;</span><span style="color: #9399B2;">,</span><span> id</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">execute</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> if</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">rows_affected</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;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</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;bookmark with id &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39; not found&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> id</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 style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">NO_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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> attach_tags</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Path</span><span style="color: #9399B2;">(</span><span>id</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Path</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Uuid</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span>payload</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Json</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;">String</span><span style="color: #89DCEB;">&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;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> exists</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_scalar!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;SELECT COUNT(*)::bigint FROM bookmarks WHERE id = $1&quot;</span><span style="color: #9399B2;">,</span><span> id</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">fetch_one</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span></span> <span class="giallo-l"><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: #89DCEB;"> &gt;</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;"> if</span><span style="color: #94E2D5;"> !</span><span>exists</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;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</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;bookmark with id &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39; not found&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> id</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 mut</span><span> tx</span><span style="color: #94E2D5;"> =</span><span> state</span><span style="color: #94E2D5;">.</span><span>pool</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">begin</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> tags</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> name</span><span style="color: #CBA6F7;"> in</span><span> payload</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> tag</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Tag</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;INSERT INTO tags (name) VALUES ($1)</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> ON CONFLICT (name) DO UPDATE SET name = EXCLUDED.name</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> RETURNING id, name&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> name</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_lowercase</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;">fetch_one</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #94E2D5;"> *</span><span>tx</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;INSERT INTO bookmark_tags (bookmark_id, tag_id) VALUES ($1, $2) ON CONFLICT DO NOTHING&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> id</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tag</span><span style="color: #94E2D5;">.</span><span>id</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;">execute</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #94E2D5;"> *</span><span>tx</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> tags</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>tag</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;">commit</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><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 style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">CREATED</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span>tags</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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> detach_tag</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Path</span><span style="color: #9399B2;">((</span><span>bookmark_id</span><span style="color: #9399B2;">,</span><span> tag_id</span><span style="color: #9399B2;">))</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Path</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Uuid</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Uuid</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 style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</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;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;DELETE FROM bookmark_tags WHERE bookmark_id = $1 AND tag_id = $2&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> bookmark_id</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tag_id</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;">execute</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> if</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">rows_affected</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;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;tag not attached to this bookmark&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: #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 style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">NO_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 each handler. Pay attention to the SQL, the queries are where the learning happens in this article.</p> <h3 id="the-state">The State</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;">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;"> AppState</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> pool</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> PgPool</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Notice what changed from Part 2. Previously, <code>AppState</code> held <code>Arc&lt;RwLock&lt;HashMap&lt;String, Paste&gt;&gt;&gt;</code>. Now it holds a <code>PgPool</code>. No <code>Arc</code>, no <code>RwLock</code>, no <code>HashMap</code>. The pool is inherently thread-safe (it uses <code>Arc</code> internally) and the database handles all concurrency.</p> <h3 id="the-from-impl-for-sqlx-error">The From Impl for sqlx::Error</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;"> From</span><span style="color: #89DCEB;">&lt;</span><span>sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Error</span><span style="color: #89DCEB;">&gt;</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> AppError</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</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">err</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Error</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;"> match</span><span> err</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Error</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RowNotFound</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;resource not found&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: #9399B2;"> }</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">InternalError</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;database 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 style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This is new. In Parts 1 and 2, we had <code>From</code> impls for <code>PoisonError</code> on lock guards. Here we have one for <code>sqlx::Error</code>. This is what lets us use <code>?</code> after every database call, the error auto-converts into an <code>AppError</code>.</p> <p><code>sqlx::Error::RowNotFound</code> is the specific error returned when <code>fetch_one</code> finds zero rows. Notice we check for it explicitly and return a 404 instead of a 500. All other SQLx errors, connection failures, constraint violations, serialization failures map to <code>InternalError</code> with the full error string logged to stderr. In production, you would log this with <code>tracing</code> and discard the raw error string from the client response for security.</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: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">main</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">async 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;"> dotenvy</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">dotenv</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> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> database_url</span><span style="color: #94E2D5;"> =</span></span> <span class="giallo-l"><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;">var</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;DATABASE_URL&quot;</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;DATABASE_URL must be set&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></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;"> PgPoolOptions</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;">max_connections</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: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">connect</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>database_url</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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 connect to database&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">migrate!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;./migrations&quot;</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 style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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 run migrations&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> state</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> AppState</span><span style="color: #9399B2;"> {</span><span> pool</span><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> app</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Router</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;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/bookmarks&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> post</span><span style="color: #9399B2;">(</span><span>create_bookmark</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/bookmarks&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> get</span><span style="color: #9399B2;">(</span><span>list_bookmarks</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/bookmarks/</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">id</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> get</span><span style="color: #9399B2;">(</span><span>get_bookmark</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/bookmarks/</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">id</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> put</span><span style="color: #9399B2;">(</span><span>update_bookmark</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/bookmarks/</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">id</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> delete</span><span style="color: #9399B2;">(</span><span>delete_bookmark</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/bookmarks/</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">id</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">/tags&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> post</span><span style="color: #9399B2;">(</span><span>attach_tags</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/bookmarks/</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">id</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">/tags/</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">tag_id</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> delete</span><span style="color: #9399B2;">(</span><span>detach_tag</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/healthz&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> get</span><span style="color: #9399B2;">(</span><span>healthz</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">with_state</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> listener</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">net</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">TcpListener</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">bind</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;127.0.0.1:3000&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span></span> <span class="giallo-l"><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;Listening on http://127.0.0.1:3000&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;"> axum</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">serve</span><span style="color: #9399B2;">(</span><span>listener</span><span style="color: #9399B2;">,</span><span> app</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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><code>dotenvy::dotenv().ok()</code> loads the <code>.env</code> file into the process environment. The <code>.ok()</code> swallows the error if the file doesn't exist, which is fine for development.</p> <p><code>sqlx::migrate!("./migrations").run(&amp;pool)</code> compiles the migration SQL into the binary at build time and runs any unapplied migrations at startup. This means you can deploy a new version of your application with a new migration, and the schema updates automatically. No separate migration step in your deployment pipeline.</p> <p>The <code>Pool</code> is moved into <code>AppState</code>. After this, any handler can extract <code>State&lt;AppState&gt;</code> and call <code>state.pool.begin()</code> or use <code>&amp;state.pool</code> directly for single queries.</p> <h3 id="the-create-bookmark-handler-transactions">The Create Bookmark Handler - Transactions</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> create_bookmark</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span>payload</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Json</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">CreateBookmarkRequest</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;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> payload</span><span style="color: #94E2D5;">.</span><span>url</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;">is_empty</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> ||</span><span> payload</span><span style="color: #94E2D5;">.</span><span>title</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;">is_empty</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;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;url and title must not be empty&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: #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> tx</span><span style="color: #94E2D5;"> =</span><span> state</span><span style="color: #94E2D5;">.</span><span>pool</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">begin</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;"> let</span><span> bookmark</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Bookmark</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;INSERT INTO bookmarks (url, title, description)</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> VALUES ($1, $2, $3)</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> RETURNING id, url, title, description, created_at, updated_at&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> payload</span><span style="color: #94E2D5;">.</span><span>url</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> payload</span><span style="color: #94E2D5;">.</span><span>title</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> payload</span><span style="color: #94E2D5;">.</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: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">fetch_one</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #94E2D5;"> *</span><span>tx</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> let mut</span><span> tags</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;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">ref</span><span> tag_names</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> payload</span><span style="color: #94E2D5;">.</span><span>tags </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> name</span><span style="color: #CBA6F7;"> in</span><span> tag_names</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> tag</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Tag</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;INSERT INTO tags (name) VALUES ($1)</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> ON CONFLICT (name) DO UPDATE SET name = EXCLUDED.name</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> RETURNING id, name&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> name</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_lowercase</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;">fetch_one</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #94E2D5;"> *</span><span>tx</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;INSERT INTO bookmark_tags (bookmark_id, tag_id) VALUES ($1, $2)&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> bookmark</span><span style="color: #94E2D5;">.</span><span>id</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tag</span><span style="color: #94E2D5;">.</span><span>id</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;">execute</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #94E2D5;"> *</span><span>tx</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> tags</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">push</span><span style="color: #9399B2;">(</span><span>tag</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> tx</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">commit</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><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: #F9E2AF;font-style: italic;"> StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">CREATED</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">BookmarkResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">id</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> url</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">url</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> title</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">title</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> description</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">description</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> created_at</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">created_at</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> updated_at</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">updated_at</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tags</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 most important handler in the project. It demonstrates a <strong>transaction</strong>, a multi-step write that must either succeed entirely or leave the database unchanged.</p> <p><code>state.pool.begin().await?</code> starts a new transaction. This sends a <code>BEGIN</code> to Postgres. Everything executed on <code>tx</code> from this point until <code>tx.commit().await?</code> (which sends a <code>COMMIT</code>) is part of one atomic unit.</p> <p>If any query inside the transaction fails for example, the tag insertion fails because of a constraint violation, the <code>?</code> operator returns an error from the handler. <code>tx</code> is dropped. When a <code>Transaction</code> is dropped without being committed, SQLx sends a <code>ROLLBACK</code> to Postgres, which undoes everything the transaction did. The bookmark that was inserted on line 164 is undone. The tags that were already inserted are undone. The database returns to the state it was in before <code>tx.begin()</code>.</p> <p>This is the answer to the problem from the beginning of this article. Without transactions, a failure halfway through "create bookmark and attach three tags" leaves an orphaned bookmark in the database with some tags attached and others not. With transactions, it's all or nothing.</p> <p>Let's trace the tag insertion logic step by step:</p> <ol> <li> <p><strong><code>INSERT INTO tags ... ON CONFLICT (name) DO UPDATE SET name = EXCLUDED.name RETURNING id, name</code></strong> - This is an upsert. If a tag with this name already exists, Postgres returns the existing row. If it doesn't exist, Postgres inserts it and returns the new row. The <code>RETURNING</code> clause gives us the <code>id</code> and <code>name</code> of the row (whether it was newly inserted or already existed), so we know which <code>tag_id</code> to use in the junction table. The <code>ON CONFLICT DO UPDATE SET name = EXCLUDED.name</code> is a no-op update, it writes the existing value back to the row. We use it because we always need the tag's <code>id</code>. <code>ON CONFLICT DO NOTHING RETURNING ...</code> returns the inserted row only when a new row is created. If the conflict path is taken, it returns zero rows. Using <code>DO UPDATE ... RETURNING</code> guarantees that we receive the existing row in both cases.</p> </li> <li> <p><strong><code>INSERT INTO bookmark_tags ...</code></strong> - Creates the association between the bookmark and the tag in the junction table. No <code>ON CONFLICT</code> here, if the association already exists (because the client sent duplicate tags), the primary key constraint will reject it and the transaction rolls back. In production, you might handle this more gracefully with <code>ON CONFLICT DO NOTHING</code>.</p> </li> <li> <p><strong><code>tx.commit().await?</code></strong> - Commits the transaction. After this point, the bookmark and all its tags are durably stored. If the server crashes immediately after <code>commit()</code> returns, the data survives.</p> </li> </ol> <p>Every query in the transaction uses <code>&amp;mut *tx</code> (a mutable reference to the transaction) instead of <code>&amp;state.pool</code>. This is critical, queries on the pool use separate connections, which are not part of the transaction. If you accidentally used <code>&amp;state.pool</code> for one of the tag insertions, that tag would be inserted outside the transaction and would survive a rollback.</p> <blockquote> <p><strong>What happens if the server crashes between two queries in the transaction?</strong> The TCP connection to Postgres drops. Postgres detects the lost connection and automatically rolls back the transaction. The partial state is never persisted.</p> </blockquote> <h3 id="the-get-bookmark-handler-two-queries-two-tables">The Get Bookmark Handler - Two Queries, Two Tables</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> get_bookmark</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Path</span><span style="color: #9399B2;">(</span><span>id</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Path</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Uuid</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;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> bookmark</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Bookmark</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;SELECT id, url, title, description, created_at, updated_at FROM bookmarks WHERE id = $1&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> id</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;">fetch_optional</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">ok_or_else</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">||</span><span style="color: #F9E2AF;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;bookmark with id &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39; not found&quot;</span><span style="color: #9399B2;">,</span><span> id</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: #CBA6F7;"> let</span><span> tags</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Tag</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;SELECT t.id, t.name</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> FROM tags t</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> INNER JOIN bookmark_tags bt ON bt.tag_id = t.id</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> WHERE bt.bookmark_id = $1&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> bookmark</span><span style="color: #94E2D5;">.</span><span>id</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;">fetch_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><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 style="color: #89B4FA;font-style: italic;">Json</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">BookmarkResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">id</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> url</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">url</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> title</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">title</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> description</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">description</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> created_at</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">created_at</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> updated_at</span><span style="color: #94E2D5;">:</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">updated_at</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tags</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 queries on two separate connections from the pool. First, fetch the bookmark by its <code>Path(id)</code>, notice <code>Path&lt;Uuid&gt;</code> deserializes the path segment directly into a <code>Uuid</code>, which is more type-safe than <code>Path&lt;String&gt;</code>. Second, fetch all tags associated with that bookmark via the junction table.</p> <p><code>fetch_optional</code> returns <code>Option&lt;Bookmark&gt;</code>. If the row exists, we get <code>Some</code>. If it doesn't, we get <code>None</code>. The <code>.ok_or_else(|| ...)</code> converts <code>None</code> into an <code>AppError::NotFound</code>. If <code>fetch_optional</code> itself fails (network error, connection timeout), the <code>?</code> converts the <code>sqlx::Error</code> into <code>AppError::InternalError</code> via the <code>From</code> impl.</p> <p>The tag query joins <code>tags</code> with <code>bookmark_tags</code> to find all tags attached to this bookmark. <code>INNER JOIN</code> means only tags that actually have an association are returned. If the bookmark has no tags, <code>fetch_all</code> returns an empty <code>Vec</code>, no error, just an empty tags list in the response.</p> <h3 id="the-list-bookmarks-handler-pagination-tag-filtering-and-the-n-1-trap">The List Bookmarks Handler - Pagination, Tag Filtering, and the N+1 Trap</h3> <p>This is the longest handler. Let's break it into three parts: pagination, the conditional query, and tag fetching.</p> <p><strong>Pagination:</strong></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> page</span><span style="color: #94E2D5;"> =</span><span> params</span><span style="color: #94E2D5;">.</span><span>page</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;">1</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 style="color: #FAB387;">1</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> per_page</span><span style="color: #94E2D5;"> =</span><span> params</span><span style="color: #94E2D5;">.</span><span>per_page</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;">20</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">clamp</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">1</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: #CBA6F7;">let</span><span> offset</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span>page</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> *</span><span> per_page</span><span style="color: #9399B2;">;</span></span></code></pre> <p><code>.max(1)</code> prevents negative or zero page numbers. <code>.clamp(1, 100)</code> caps the page size between 1 and 100 - requesting 1000 items per page is either a bug or an abuse vector. <code>offset</code> is calculated from <code>(page - 1) * per_page</code>. Page 1, 20 per page gives offset 0. Page 2 gives offset 20. This is standard cursor-less pagination.</p> <p><strong>The conditional query - tagged vs untagged:</strong></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>bookmarks</span><span style="color: #9399B2;">,</span><span> total</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</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;">Bookmark</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span><span style="color: #CBA6F7;"> i64</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">ref</span><span> tag_name</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> params</span><span style="color: #94E2D5;">.</span><span>tag </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Tagged: count and fetch bookmarks with a specific tag</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> total</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_scalar!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;SELECT COUNT(DISTINCT b.id)::bigint</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> FROM bookmarks b</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> INNER JOIN bookmark_tags bt ON bt.bookmark_id = b.id</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> INNER JOIN tags t ON t.id = bt.tag_id</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> WHERE t.name = $1&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tag_name</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_lowercase</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;">fetch_one</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span></span> <span class="giallo-l"><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> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> bookmarks</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Bookmark</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;SELECT DISTINCT b.id, b.url, b.title, b.description, b.created_at, b.updated_at</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> FROM bookmarks b</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> INNER JOIN bookmark_tags bt ON bt.bookmark_id = b.id</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> INNER JOIN tags t ON t.id = bt.tag_id</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> WHERE t.name = $1</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> ORDER BY b.created_at DESC</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> LIMIT $2 OFFSET $3&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tag_name</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_lowercase</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> per_page</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> offset</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;">fetch_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span>bookmarks</span><span style="color: #9399B2;">,</span><span> total</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;font-style: italic;"> // Untagged: count and fetch all bookmarks</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> total</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_scalar!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;SELECT COUNT(*)::bigint FROM bookmarks&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">fetch_one</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span></span> <span class="giallo-l"><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> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> bookmarks</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Bookmark</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;SELECT id, url, title, description, created_at, updated_at</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> FROM bookmarks</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> ORDER BY created_at DESC</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> LIMIT $1 OFFSET $2&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> per_page</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> offset</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;">fetch_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span>bookmarks</span><span style="color: #9399B2;">,</span><span> total</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;">};</span></span></code></pre> <p>Two separate query blocks, one with tag filtering, one without. Conditionally branching on <code>params.tag</code> is simpler than building a dynamic query string, and it avoids SQL injection entirely.</p> <p>In the tagged path, the query joins <code>bookmarks</code> → <code>bookmark_tags</code> → <code>tags</code> and filters by tag name. <code>DISTINCT</code> prevents duplicate bookmarks if a bookmark has multiple tags (the join would otherwise produce one row per tag per bookmark). The count query counts distinct bookmark IDs for the same reason, without <code>DISTINCT</code>, the count would include duplicates.</p> <p><code>query_scalar!</code> is a new macro. It's for queries that return a single column, like <code>COUNT(*)</code> or <code>SELECT name FROM ... WHERE id = $1</code>. It deserializes directly into a Rust scalar type (<code>i64</code>, <code>String</code>, etc.) instead of a struct.</p> <p><strong>The tag fetching - avoiding the N+1 trap:</strong></p> <p>Here is where this handler differs from a naive approach. A naive approach would be:</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;">// DON&#39;T DO THIS - the N+1 trap</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">for</span><span> bookmark</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>bookmarks</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> tags</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Tag</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;... WHERE bt.bookmark_id = $1&quot;</span><span style="color: #9399B2;">,</span><span> bookmark</span><span style="color: #94E2D5;">.</span><span>id</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">fetch_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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: #9399B2;">}</span></span></code></pre> <p>This is the <strong>N+1 query problem</strong>. If the page has 20 bookmarks, you make 1 query for the bookmarks themselves, then 20 more queries for the tags (one per bookmark). That's 21 queries total. On the next page, another 21. At scale, this multiplies your database load by the page size and it's easy to write by accident because each lookup feels natural in a loop.</p> <p>The fix: <strong>fetch all tags for all bookmarks on the current page in a single query</strong>, then group them in application 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> bookmark_ids</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;">Uuid</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> bookmarks</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>b</span><span style="color: #94E2D5;">|</span><span> b</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">id</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: #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;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">FromRow</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> TagWithBookmark</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Uuid</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> bookmark_id</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Uuid</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> all_tags</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;">TagWithBookmark</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if</span><span> bookmark_ids</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;"> 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 style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> TagWithBookmark</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;SELECT t.id, t.name, bt.bookmark_id</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> FROM tags t</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> INNER JOIN bookmark_tags bt ON bt.tag_id = t.id</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> WHERE bt.bookmark_id = ANY($1)&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> &amp;</span><span>bookmark_ids</span><span style="color: #CBA6F7;"> as</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">Uuid</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;">fetch_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span></span> <span class="giallo-l"><span style="color: #9399B2;">};</span></span></code></pre> <p><code>WHERE bt.bookmark_id = ANY($1)</code> with the slice <code>&amp;bookmark_ids as &amp;[Uuid]</code> tells Postgres "give me all tag associations for any of these bookmark IDs." Postgres uses the <code>idx_bookmark_tags_bookmark_id</code> index for each ID in the list and returns all matching rows in a single result set.</p> <p><code>TagWithBookmark</code> is a helper struct used only inside this handler. It includes <code>bookmark_id</code> so we know which bookmark each tag belongs to when grouping.</p> <p>The <code>if bookmark_ids.is_empty()</code> check simply avoids making an unnecessary database query. <code>ANY()</code> works correctly with an empty array, but since we already know there are no bookmark IDs, we can return an empty vector immediately.</p> <p>Then we group by bookmark ID:</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> tags_by_bookmark</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;">Uuid</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;">Tag</span><span style="color: #89DCEB;">&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 style="color: #CBA6F7;">for</span><span> row</span><span style="color: #CBA6F7;"> in</span><span> all_tags</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> tags_by_bookmark</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">entry</span><span style="color: #9399B2;">(</span><span>row</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">bookmark_id</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">or_default</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;font-style: italic;">Tag</span><span style="color: #9399B2;"> {</span><span> id</span><span style="color: #94E2D5;">:</span><span> row</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">id</span><span style="color: #9399B2;">,</span><span> name</span><span style="color: #94E2D5;">:</span><span> row</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></code></pre> <p>And finally map each bookmark to its response, looking up tags from the HashMap:</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> bookmark_responses</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;">BookmarkResponse</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> bookmarks</span></span> <span class="giallo-l"><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;">map</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>bookmark</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> tags</span><span style="color: #94E2D5;"> =</span><span> tags_by_bookmark</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 style="color: #94E2D5;">&amp;</span><span>bookmark</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">id</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">cloned</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 style="color: #F9E2AF;font-style: italic;"> BookmarkResponse</span><span style="color: #9399B2;"> {</span><span style="color: #9399B2;font-style: italic;"> /* ... */</span><span> tags</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;">collect</span><span style="color: #9399B2;">();</span></span></code></pre> <p>The total number of queries is now 3 (bookmarks, count, tags), regardless of page size. This is the difference between an API that handles 1000 concurrent users and one that falls over at 10.</p> <h3 id="the-update-bookmark-handler">The Update Bookmark Handler</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> update_bookmark</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Path</span><span style="color: #9399B2;">(</span><span>id</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Path</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Uuid</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span>payload</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Json</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">UpdateBookmarkRequest</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;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> existing</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Bookmark</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;SELECT id, url, title, description, created_at, updated_at FROM bookmarks WHERE id = $1&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> id</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;">fetch_optional</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">ok_or_else</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">||</span><span style="color: #F9E2AF;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;bookmark with id &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39; not found&quot;</span><span style="color: #9399B2;">,</span><span> id</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: #CBA6F7;"> let</span><span> url</span><span style="color: #94E2D5;"> =</span><span> payload</span><span style="color: #94E2D5;">.</span><span>url</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap_or</span><span style="color: #9399B2;">(</span><span>existing</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">url</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> title</span><span style="color: #94E2D5;"> =</span><span> payload</span><span style="color: #94E2D5;">.</span><span>title</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">unwrap_or</span><span style="color: #9399B2;">(</span><span>existing</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">title</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> description</span><span style="color: #94E2D5;"> =</span><span> payload</span><span style="color: #94E2D5;">.</span><span>description</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">or</span><span style="color: #9399B2;">(</span><span>existing</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">description</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> bookmark</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Bookmark</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> r#&quot;UPDATE bookmarks</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> SET url = $1, title = $2, description = $3, updated_at = NOW()</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> WHERE id = $4</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> RETURNING id, url, title, description, created_at, updated_at&quot;#</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> url</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> title</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> description</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> id</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;">fetch_one</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // ... fetch tags and return</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>A partial update pattern. The client sends only the fields it wants to change. Fields not present in the request default to their existing values from the database.</p> <p><code>payload.url.unwrap_or(existing.url)</code> takes the client-supplied value if present, otherwise falls back to the existing value. <code>payload.description.or(existing.description)</code> does the same for <code>Option&lt;String&gt;</code> , notice <code>or()</code> instead of <code>unwrap_or()</code>, since both are <code>Option</code> types.</p> <p><code>updated_at = NOW()</code> sets the timestamp to the current server time. This is done in SQL rather than Rust because the database clock is the single source of truth for when a row was last modified. If you set it in Rust, clock skew between application servers could cause inconsistent timestamps.</p> <h3 id="the-delete-bookmark-handler-cascade">The Delete Bookmark Handler - Cascade</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> delete_bookmark</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Path</span><span style="color: #9399B2;">(</span><span>id</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Path</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Uuid</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;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</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;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;DELETE FROM bookmarks WHERE id = $1&quot;</span><span style="color: #9399B2;">,</span><span> id</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">execute</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> if</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">rows_affected</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;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</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;bookmark with id &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39; not found&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> id</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 style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">NO_CONTENT</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>A single <code>DELETE</code> statement. The <code>ON DELETE CASCADE</code> foreign key on <code>bookmark_tags.bookmark_id</code> ensures that deleting a bookmark also deletes all rows in the junction table. Without <code>CASCADE</code>, you would need to delete from <code>bookmark_tags</code> first two queries, or a transaction. <code>CASCADE</code> handles it in one.</p> <p><code>rows_affected()</code> returns the number of rows that were modified. If it's 0, the bookmark didn't exist and we return 404.</p> <h3 id="the-attach-tags-handler-transactional-tag-creation">The Attach Tags Handler - Transactional Tag Creation</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> attach_tags</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Path</span><span style="color: #9399B2;">(</span><span>id</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Path</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Uuid</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span>payload</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Json</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;">String</span><span style="color: #89DCEB;">&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;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Check bookmark exists</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> exists</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_scalar!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;SELECT COUNT(*)::bigint FROM bookmarks WHERE id = $1&quot;</span><span style="color: #9399B2;">,</span><span> id</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">fetch_one</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span></span> <span class="giallo-l"><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: #89DCEB;"> &gt;</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;"> if</span><span style="color: #94E2D5;"> !</span><span>exists</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;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</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> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> tx</span><span style="color: #94E2D5;"> =</span><span> state</span><span style="color: #94E2D5;">.</span><span>pool</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">begin</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> tags</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> name</span><span style="color: #CBA6F7;"> in</span><span> payload</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Upsert tag, insert into bookmark_tags</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> <span class="giallo-l"></span> <span class="giallo-l"><span> tx</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">commit</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><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 style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">CREATED</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span>tags</span><span style="color: #9399B2;">)))</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Similar tag creation logic to <code>create_bookmark</code>, but for an existing bookmark. The existence check happens before the transaction starts, no point opening a transaction if the bookmark doesn't exist.</p> <p>The <code>ON CONFLICT DO NOTHING</code> on the <code>bookmark_tags</code> insert is important here: if the client sends a tag that's already attached, the insert is silently skipped instead of failing with a unique constraint violation. Without <code>DO NOTHING</code>, attaching <code>["rust", "rust"]</code> would cause the second insert to fail and roll back the entire transaction, losing the first tag.</p> <h3 id="the-detach-tag-handler-tuple-path-parameters">The Detach Tag Handler - Tuple Path Parameters</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> detach_tag</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Path</span><span style="color: #9399B2;">((</span><span>bookmark_id</span><span style="color: #9399B2;">,</span><span> tag_id</span><span style="color: #9399B2;">))</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Path</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Uuid</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Uuid</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 style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</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;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;DELETE FROM bookmark_tags WHERE bookmark_id = $1 AND tag_id = $2&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> bookmark_id</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> tag_id</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;">execute</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>state</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> if</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">rows_affected</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;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;tag not attached to this bookmark&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: #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 style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">NO_CONTENT</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>Path&lt;(Uuid, Uuid)&gt;</code> is a new Axum trick. The route is <code>/bookmarks/{id}/tags/{tag_id}</code>. Axum deserializes the two path segments <code>{id}</code> and <code>{tag_id}</code> into a tuple <code>(Uuid, Uuid)</code>. This is cleaner than writing <code>Path(id): Path&lt;Uuid&gt;, Path(tag_id): Path&lt;Uuid&gt;</code> as separate extractor parameters, though both work. The tuple pattern works for up to 16 segments and saves a line of function signature.</p> <blockquote> <p><strong>Why not use <code>Path</code> for both?</strong> You can <code>async fn detach_tag(Path(bookmark_id): Path&lt;Uuid&gt;, Path(tag_id): Path&lt;Uuid&gt;)</code> but Axum's <code>Path</code> extractor can only appear once per handler since it's a <code>FromRequestParts</code> extractor limited to capturing a single path pattern. The tuple syntax <code>Path((a, b))</code> captures both in one extractor.</p> </blockquote> <h2 id="understanding-transactions">Understanding Transactions</h2> <p>Transactions are the single most important database concept beyond basic CRUD. Here is the exact lifecycle of the <code>create_bookmark</code> transaction:</p> <ol> <li> <p><strong><code>state.pool.begin().await?</code></strong> - SQLx acquires a connection from the pool and sends <code>BEGIN</code> to Postgres. Postgres marks this connection as "in a transaction." All subsequent queries on this connection are part of the transaction.</p> </li> <li> <p><strong><code>INSERT INTO bookmarks ...</code></strong> - The bookmark is inserted, but it is not visible to any other connection. Other users querying <code>bookmarks</code> will not see this row until the transaction commits. This is Postgres's default isolation level, <code>READ COMMITTED</code>, at work.</p> </li> <li> <p><strong><code>INSERT INTO tags ... RETURNING ...</code></strong> - Each tag is upserted. The <code>RETURNING</code> clause returns the tag's <code>id</code> and <code>name</code>, which we need for the junction table insert. The upsert uses the transaction's snapshot of the database — if another concurrent transaction creates a tag with the same name at the same moment, Postgres would block one of them (because of the <code>UNIQUE</code> constraint) and the second would see the first's row.</p> </li> <li> <p><strong><code>INSERT INTO bookmark_tags ...</code></strong> - The junction table row is inserted, linking the bookmark and the tag.</p> </li> <li> <p><strong><code>tx.commit().await?</code></strong> - SQLx sends <code>COMMIT</code> to Postgres. Postgres writes all the transaction's changes to the write-ahead log (WAL), making them durable. At this moment, the changes become visible to all other connections. The pooled connection is returned to the pool.</p> </li> </ol> <p>If any step fails, the <code>?</code> operator returns an <code>Err</code>, <code>tx</code> is dropped. SQLx's <code>Transaction</code> destructor sends <code>ROLLBACK</code> to Postgres. Postgres undoes all changes made during the transaction as if they never happened. No orphaned bookmarks. No partial tag attachments.</p> <h3 id="what-if-two-transactions-run-at-the-same-time">What If Two Transactions Run at the Same Time?</h3> <p>The <code>name TEXT NOT NULL UNIQUE</code> constraint on <code>tags</code> is the key. If two concurrent requests both try to create a tag called <code>rust</code>:</p> <ol> <li>Transaction A inserts <code>rust</code> into <code>tags</code>. Postgres acquires an exclusive lock on the new row.</li> <li>Transaction B also tries to insert <code>rust</code>. Because of the <code>UNIQUE</code> constraint, Postgres blocks B until A commits or rolls back.</li> <li>If A commits, B's insert fails with a unique violation but our query uses <code>ON CONFLICT (name) DO UPDATE</code>, so instead of failing, it returns the existing <code>rust</code> row that A inserted. B proceeds with A's tag ID.</li> <li>If A rolls back, B's insert succeeds because the conflicting row no longer exists.</li> </ol> <p>Without <code>ON CONFLICT</code>, B's insert would fail, the <code>?</code> would propagate the error, and B's entire transaction would roll back. The bookmark B was creating would be lost. The upsert pattern is a concurrency-safe way to "get or create" a shared resource like a tag.</p> <h2 id="isolation-levels-a-brief-look">Isolation Levels - A Brief Look</h2> <p>Postgres's default isolation level is <code>READ COMMITTED</code>. You can see it if you run <code>SHOW default_transaction_isolation;</code> in <code>psql</code>. Here is what it means, and what the alternatives are:</p> <h3 id="read-committed-the-default">READ COMMITTED (the default)</h3> <p>Each statement in a transaction sees only data that was committed before the statement began, not before the transaction began. This means:</p> <ul> <li><strong>No dirty reads:</strong> You never see uncommitted data from another transaction.</li> <li><strong>Non-repeatable reads are possible:</strong> If transaction A reads a row, transaction B updates and commits that row, then A reads it again, A sees B's update. The row changed between reads within A's transaction.</li> </ul> <p>This is sufficient for most applications. In our bookmark manager, the only write that involves multiple tables is <code>create_bookmark</code> (bookmark + tags), and that's wrapped in a transaction. Since the bookmark, tags, and their associations are all created inside a single transaction, other transactions do not observe any of those changes until the transaction commits.</p> <h3 id="repeatable-read">REPEATABLE READ</h3> <p>Each statement in a transaction sees only data that was committed before the <strong>transaction</strong> began. The snapshot is frozen at transaction start. Non-repeatable reads cannot happen. This is stronger isolation, but it can lead to serialization failures, if two transactions modify the same row, one must be retried.</p> <h3 id="serializable">SERIALIZABLE</h3> <p>The strongest level. Transactions run as if they were executed one after another, even though they actually run concurrently. Postgres detects conflicts and forces one transaction to fail with a serialization failure, which the application must retry. This is the safest level, but it has the highest overhead and requires retry logic in your application code.</p> <p>For a bookmark manager, <code>READ COMMITTED</code> (the default) is correct. For a banking application, you want <code>SERIALIZABLE</code> or at least <code>REPEATABLE READ</code>. The isolation level is set per transaction:</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> tx</span><span style="color: #94E2D5;"> =</span><span> pool</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">begin</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #F9E2AF;">sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;SET TRANSACTION ISOLATION LEVEL SERIALIZABLE&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">execute</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #94E2D5;"> *</span><span>tx</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span></code></pre> <p>You probably won't need this in practice, but knowing what the options mean and why Postgres defaults to <code>READ COMMITTED</code> is table stakes for backend engineering.</p> <h2 id="running-the-project">Running the Project</h2> <p>Make sure Docker is running, then:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>docker compose up -d</span></span> <span class="giallo-l"><span>cargo sqlx prepare</span></span> <span class="giallo-l"><span>cargo run</span></span></code></pre> <p>You should see:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>Listening on http://127.0.0.1:3000</span></span></code></pre><h3 id="create-a-bookmark">Create a Bookmark</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -X POST http://localhost:3000/bookmarks \</span></span> <span class="giallo-l"><span> -H &quot;Content-Type: application/json&quot; \</span></span> <span class="giallo-l"><span> -d &#39;{</span></span> <span class="giallo-l"><span> &quot;url&quot;: &quot;https://www.rust-lang.org&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;Rust Programming Language&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;The official Rust website&quot;,</span></span> <span class="giallo-l"><span> &quot;tags&quot;: [&quot;rust&quot;, &quot;programming&quot;]</span></span> <span class="giallo-l"><span> }&#39;</span></span></code></pre> <p>Response:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="json"><span class="giallo-l"><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">id</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;a1b2c3d4-e5f6-7890-abcd-ef1234567890&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">url</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;https://www.rust-lang.org&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">title</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;Rust Programming Language&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">description</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;The official Rust website&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">created_at</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;2026-07-12T17:00:00.000000Z&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">updated_at</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;2026-07-12T17:00:00.000000Z&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">tags</span><span style="color: #9399B2;">&quot;: [</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {&quot;</span><span style="color: #89B4FA;">id</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;b2c3d4e5-f6a7-8901-bcde-f12345678901&quot;</span><span style="color: #9399B2;">, &quot;</span><span style="color: #89B4FA;">name</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;rust&quot;</span><span style="color: #9399B2;">},</span></span> <span class="giallo-l"><span style="color: #9399B2;"> {&quot;</span><span style="color: #89B4FA;">id</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;c3d4e5f6-a7b8-9012-cdef-123456789012&quot;</span><span style="color: #9399B2;">, &quot;</span><span style="color: #89B4FA;">name</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;programming&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>The bookmark and both tags were created in a single transaction. If the server crashed after inserting the bookmark but before inserting the <code>programming</code> tag, the entire operation rolls back, no orphaned bookmark.</p> <h3 id="get-a-bookmark">Get a Bookmark</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl http://localhost:3000/bookmarks/a1b2c3d4-e5f6-7890-abcd-ef1234567890</span></span></code></pre><h3 id="list-all-bookmarks">List All Bookmarks</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl http://localhost:3000/bookmarks</span></span></code></pre> <p>Response includes pagination metadata:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="json"><span class="giallo-l"><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">bookmarks</span><span style="color: #9399B2;">&quot;: [</span><span>...</span><span style="color: #9399B2;">],</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">page</span><span style="color: #9399B2;">&quot;:</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">per_page</span><span style="color: #9399B2;">&quot;:</span><span style="color: #FAB387;"> 20</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">total</span><span style="color: #9399B2;">&quot;:</span><span style="color: #FAB387;"> 1</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="list-bookmarks-with-pagination">List Bookmarks with Pagination</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl &quot;http://localhost:3000/bookmarks?page=2&amp;per_page=10&quot;</span></span></code></pre><h3 id="filter-by-tag">Filter by Tag</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl &quot;http://localhost:3000/bookmarks?tag=rust&quot;</span></span></code></pre> <p>This returns only bookmarks that have the <code>rust</code> tag.</p> <h3 id="update-a-bookmark">Update a Bookmark</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -X PUT http://localhost:3000/bookmarks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \</span></span> <span class="giallo-l"><span> -H &quot;Content-Type: application/json&quot; \</span></span> <span class="giallo-l"><span> -d &#39;{&quot;title&quot;: &quot;Rust Lang (Updated)&quot;}&#39;</span></span></code></pre> <p>Only the <code>title</code> field is updated. <code>url</code> and <code>description</code> retain their existing values. <code>updated_at</code> is set to <code>NOW()</code> by the database.</p> <h3 id="attach-tags-to-an-existing-bookmark">Attach Tags to an Existing Bookmark</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -X POST http://localhost:3000/bookmarks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/tags \</span></span> <span class="giallo-l"><span> -H &quot;Content-Type: application/json&quot; \</span></span> <span class="giallo-l"><span> -d &#39;[&quot;web&quot;, &quot;systems&quot;]&#39;</span></span></code></pre> <p>Upserts the tags if they don't exist, inserts the associations, returns the full tag objects. If a tag is already attached, <code>ON CONFLICT DO NOTHING</code> skips it silently.</p> <h3 id="detach-a-tag">Detach a Tag</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -X DELETE http://localhost:3000/bookmarks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/tags/b2c3d4e5-f6a7-8901-bcde-f12345678901</span></span></code></pre> <p>Returns 204 No Content on success, 404 if the tag wasn't attached.</p> <h3 id="delete-a-bookmark">Delete a Bookmark</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -X DELETE http://localhost:3000/bookmarks/a1b2c3d4-e5f6-7890-abcd-ef1234567890</span></span></code></pre> <p>Returns 204. The bookmark and all its tag associations are removed. <code>ON DELETE CASCADE</code> handles the junction table rows.</p> <h3 id="test-validation">Test Validation</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -X POST http://localhost:3000/bookmarks \</span></span> <span class="giallo-l"><span> -H &quot;Content-Type: application/json&quot; \</span></span> <span class="giallo-l"><span> -d &#39;{&quot;url&quot;: &quot;&quot;, &quot;title&quot;: &quot;&quot;}&#39;</span></span></code></pre> <p>Response:</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;">error</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;url and title must not be empty&quot;</span><span style="color: #9399B2;">}</span></span></code></pre> <p>Status code: 400.</p> <h3 id="test-not-found">Test Not Found</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl http://localhost:3000/bookmarks/00000000-0000-0000-0000-000000000000</span></span></code></pre> <p>Response:</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;">error</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;bookmark with id &#39;00000000-0000-0000-0000-000000000000&#39; not found&quot;</span><span style="color: #9399B2;">}</span></span></code></pre> <p>Status code: 404.</p> <h2 id="what-we-skipped">What We Skipped</h2> <ul> <li><strong>The <code>thiserror</code> crate</strong>: We wrote <code>From</code> impls manually to show the mechanism. In practice, <code>thiserror</code> derives these for you compactly. Use it in your own projects.</li> <li><strong>Compile-time query checking without a running database</strong>: The <code>.sqlx/</code> directory generated by <code>cargo sqlx prepare</code> is the offline query cache. Commit it. CI builds won't need a database. We covered this in the setup.</li> <li><strong>Full-text search</strong>: Searching bookmarks by URL or title substring would require a <code>tsvector</code> and GIN index. That's a different problem from tag-based filtering.</li> <li><strong>User accounts</strong>: Bookmarks belong to everyone. Part 6 adds authentication and user-scoped data.</li> <li><strong>Orphaned tags</strong>: If all bookmarks with a given tag are deleted, the tag row remains in the <code>tags</code> table with no associations. This is harmless (takes negligible space) but a production system might periodically clean up unused tags with a background job (Part 9).</li> <li><strong>Soft deletes</strong>: <code>DELETE</code> is permanent. A real application might use a <code>deleted_at</code> column and a <code>WHERE deleted_at IS NULL</code> filter on all queries. This is an application-level decision, not a database one.</li> </ul> <h2 id="conclusion">Conclusion</h2> <p>You now have a solid foundation for building data-driven Axum applications. In the next article, we'll build on it by introducing caching and idempotency, two techniques that make APIs faster, more resilient, and safer to retry. See you soon</p> Wed, 08 Jul 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-axum-error-handling-by-building-pastebin-api-in-rust/ https://blog.sheerluck.dev/posts/learn-axum-error-handling-by-building-pastebin-api-in-rust/ <p>In Part 1, we built a URL shortener and learned the Axum request lifecycle: <code>Router</code>, handlers, <code>State&lt;T&gt;</code>, <code>Path&lt;T&gt;</code>, and <code>IntoResponse</code>. But we left two things unfinished. Our error handling was <code>.unwrap()</code> on every lock acquisition, and our response for a missing URL was an ad-hoc <code>(StatusCode, &amp;str)</code> tuple dropped directly into the handler.</p> <p><img src="/images/axum-error-handling.png" alt="Axum Error Handling" /></p> <p>In this post, we are going to build a <strong>Pastebin API with proper error handling</strong>. We will learn the <code>Json&lt;T&gt;</code> extractor in depth, the <code>Query</code> extractor for optional parameters, request validation, and most importantly how to build a single <code>AppError</code> enum that converts every possible failure into the right HTTP status code. Along the way, we will see why Axum deliberately has no hidden error-handling behavior, and why that is a feature, not a missing feature.</p> <p>Let's start, I can't wait.</p> <p>Get the source code from <a rel="external" href="https://github.com/MrSheerluck/pastebin-api-in-axum">here</a></p> <h2 id="the-problem-with-ad-hoc-error-handling">The Problem with Ad-Hoc Error Handling</h2> <p>In Part 1, when a short code was not found, we wrote:</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> urls</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>code</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>long_url</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Redirect</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">to</span><span style="color: #9399B2;">(</span><span>long_url</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into_response</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: #F9E2AF;font-style: italic;"> StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">NOT_FOUND</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;404 Not Found: No URL for this code&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: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">into_response</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This works for one handler. Now imagine a real application with twenty handlers. Every handler that does a lookup has its own 404 logic. Every handler that deals with validation has its own 400 logic. The status codes and error messages are scattered across the codebase, and there is no single place to change how errors are formatted.</p> <p>The alternative that some frameworks choose is "hidden behavior": the framework catches your errors, guesses which HTTP status code to return, and sends a response for you. A missing database row becomes a 404. A failed deserialization becomes a 400. This sounds convenient, until it guesses wrong and your API returns a 500 for something that should be a 400, or worse, a 200 for something that should be a 500.</p> <p>In Axum, you define your own error type. You implement <code>IntoResponse</code> on it exactly once. You decide every status code. The framework does not make application-specific decisions for you. This is what we are going to build.</p> <h2 id="the-json-extractor-deeper-than-you-think">The Json Extractor - Deeper Than You Think</h2> <p>In Part 1, we used <code>Json&lt;ShortenRequest&gt;</code> without much explanation. Now let's understand what it actually does.</p> <p><code>Json&lt;T&gt;</code> implements <code>FromRequest</code> for any <code>T: DeserializeOwned</code>. When a handler declares <code>Json(payload): Json&lt;SomeType&gt;</code>, Axum does three things:</p> <ol> <li> <p><strong>Buffers the entire request body.</strong> The request body arrives as a stream of bytes from the client. <code>Json</code> first reads the entire stream into memory before attempting deserialization. This is why a handler can have at most one body extractor: once the body has been consumed, there is nothing left for another body extractor to read.</p> </li> <li> <p><strong>Checks the Content-Type header.</strong> If the request is not sent with a JSON media type (such as <code>application/json</code> or <code>application/*+json</code>), Axum rejects it with a <code>415 Unsupported Media Type</code>. This happens before deserialization, so the client gets a clear signal that it sent the wrong content type.</p> </li> <li> <p><strong>Deserializes the JSON.</strong> If the body contains valid JSON but it cannot be deserialized into your type (for example, because a required field is missing, a field has the wrong type, or <code>#[serde(deny_unknown_fields)]</code> rejects an unknown field), Axum rejects the request with an appropriate deserialization error, typically <code>422 Unprocessable Entity</code>. Invalid JSON syntax is rejected earlier with <code>400 Bad Request</code>.</p> </li> </ol> <p>All three steps happen before your handler runs. If any step fails, the handler is never called. The request is rejected with the appropriate status code automatically. Your handler only runs when the body is present, correctly typed as JSON, and valid against your struct.</p> <p>This is the first half of Axum's explicit error-handling model. The framework handles malformed requests such as unsupported content types, invalid JSON syntax, and deserialization failures, so you do not have to. But semantic errors like empty content, invalid values, expired resources are yours to handle. The line is drawn at <code>serde</code> deserialization. Everything beyond that is your responsibility.</p> <h2 id="the-query-extractor">The Query Extractor</h2> <p>Some parameters are not part of the request body. They are part of the URL itself. Axum provides <code>Query&lt;T&gt;</code> for 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;"> axum</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">extract</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Query</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> serde</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Deserialize</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;">Deserialize</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> ListParams</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> language</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;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> page</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;">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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> list_pastes</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">Query</span><span style="color: #9399B2;">(</span><span>params</span><span style="color: #9399B2;">)</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;">ListParams</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // params.language is Some(&quot;rust&quot;) or None</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // params.page is Some(1) or None</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></code></pre> <p>A request to <code>GET /pastes?language=rust&amp;page=2</code> deserializes into <code>ListParams { language: Some("rust".into()), page: Some(2) }</code>. A request to <code>GET /pastes</code> with no query string gives <code>ListParams { language: None, page: None }</code>.</p> <p>Unlike <code>Json</code>, which deserializes a JSON request body, <code>Query</code> uses the <code>serde_urlencoded</code> crate together with Serde to deserialize URL query parameters into your type. The same <code>serde</code> infrastructure handles both. The difference is where the data comes from: <code>Json</code> reads the request body, <code>Query</code> reads the URL query string.</p> <blockquote> <p><strong>When to use Query vs Json:</strong> <code>Query</code> is most commonly used with <code>GET</code> requests (and sometimes <code>DELETE</code>). <code>Json</code> is most commonly used with <code>POST</code>, <code>PUT</code>, and <code>PATCH</code> requests. This is a widely followed REST convention rather than a rule enforced by HTTP, and some APIs legitimately use query parameters on other methods as well.</p> </blockquote> <h2 id="request-validation-semantic-checks">Request Validation - Semantic Checks</h2> <p>Deserialization checks structure. Validation checks meaning. <code>serde</code> can tell you that <code>content</code> is missing, but it cannot tell you that <code>content</code> is an empty string. It can tell you that <code>expires_in_seconds</code> is an integer, but it cannot tell you that <code>-5</code> is nonsensical for an expiry duration.</p> <p>In this project, we perform validation in the handler immediately after deserialization and before any business logic. Here is the 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;"> validate_create_request</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">req</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">CreatePasteRequest</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;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> req</span><span style="color: #94E2D5;">.</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;">is_empty</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;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;content must not be empty&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: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> req</span><span style="color: #94E2D5;">.</span><span>content</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;"> MAX_CONTENT_LENGTH</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;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</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;content exceeds maximum length of </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> bytes&quot;</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> MAX_CONTENT_LENGTH</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 let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">ref</span><span> lang</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> req</span><span style="color: #94E2D5;">.</span><span>language </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: #FAB387;">SUPPORTED_LANGUAGES</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>lang</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;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</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;unsupported language: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> lang</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: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>seconds</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> req</span><span style="color: #94E2D5;">.</span><span>expires_in_seconds </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> seconds</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: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;expires_in_seconds must be positive&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: #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> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Every validation failure returns the same error variant: <code>AppError::ValidationError</code>. Every failure produces a 400 Bad Request. The difference is the message, which tells the client specifically what was wrong like is it empty content, too long, bad language, negative expiry.</p> <h2 id="apperror-the-single-error-enum">AppError - The Single Error Enum</h2> <p>Now we arrive at the core pattern of this article. An <code>AppError</code> enum that:</p> <ul> <li>Has one variant per category of error</li> <li>Implements <code>IntoResponse</code> once, mapping each variant to the right status code</li> <li>Has <code>From</code> impls so domain-level errors (like a failed lock acquisition) convert automatically</li> </ul> <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;"> AppError</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> ValidationError</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;"> NotFound</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;"> InternalError</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></code></pre> <p>Three variants and that's it. A real application might have more like <code>Unauthorized</code>, <code>Forbidden</code>, <code>Conflict</code> but three is enough to cover everything a simple API can encounter.</p> <h3 id="validationerror-400">ValidationError → 400</h3> <p>The client sent something wrong. The error is theirs to fix. Return a 400 with a message explaining what to fix.</p> <h3 id="notfound-404">NotFound → 404</h3> <p>The requested resource does not exist. This covers both "never existed" and "existed but expired." From the client's perspective, an expired paste is the same as a paste that was never created: you cannot read it.</p> <h3 id="internalerror-500">InternalError → 500</h3> <p>Something went wrong on the server. The client cannot fix it. In a real application, you log the full error internally but send a generic message to the client. Leaking internal details like file paths, stack traces, database error strings is a security risk and a bad user experience.</p> <p>Now the <code>IntoResponse</code> 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;"> IntoResponse</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> AppError</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_response</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;"> Response</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span style="color: #9399B2;"> (</span><span>status</span><span style="color: #9399B2;">,</span><span> message</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</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: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</span><span style="color: #9399B2;">(</span><span>msg</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">BAD_REQUEST</span><span style="color: #9399B2;">,</span><span> msg</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;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</span><span>msg</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">NOT_FOUND</span><span style="color: #9399B2;">,</span><span> msg</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;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">InternalError</span><span style="color: #9399B2;">(</span><span>msg</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;internal error: </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: #F9E2AF;font-style: italic;"> StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">INTERNAL_SERVER_ERROR</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;internal server error&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;"> let</span><span> body</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">serde_json</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">json!</span><span style="color: #9399B2;">({</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;error&quot;</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> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span>status</span><span style="color: #9399B2;">,</span><span> body</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into_response</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>Every error response is a JSON object with an <code>"error"</code> field. Validation errors include the specific message. Not-found errors include the resource name. Internal errors log the actual error to stderr via <code>eprintln!</code> but send a generic message to the client, the client sees <code>{"error": "internal server error"}</code> regardless of whether the database is down, the filesystem is full, or the lock is poisoned. We will replace <code>eprintln!</code> with structured logging via <code>tracing</code> in Part 16, but the principle is the same: the internal details are for the server operator, not the client.</p> <h3 id="from-impls-automatic-error-conversion">From Impls - Automatic Error Conversion</h3> <p>The <code>?</code> operator is the backbone of Rust error handling. It converts one error type into another via <code>From</code>. If we want to use <code>?</code> in our handlers, we need <code>From</code> impls that convert standard library and framework errors into <code>AppError</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;"> From</span><span style="color: #89DCEB;">&lt;</span><span>std</span><span style="color: #94E2D5;">::</span><span>sync</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">PoisonError</span><span style="color: #89DCEB;">&lt;</span><span>std</span><span style="color: #94E2D5;">::</span><span>sync</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RwLockWriteGuard</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">_</span><span style="color: #9399B2;">,</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;"> Paste</span><span style="color: #89DCEB;">&gt;&gt;&gt;&gt;</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> AppError</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</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">_</span><span style="color: #94E2D5;">:</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;">PoisonError</span><span style="color: #89DCEB;">&lt;</span><span style="color: #EBA0AC;">std</span><span style="color: #94E2D5;">::</span><span style="color: #EBA0AC;">sync</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">RwLockWriteGuard</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">_</span><span style="color: #9399B2;">,</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;"> Paste</span><span style="color: #89DCEB;">&gt;&gt;&gt;</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;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">InternalError</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;lock poisoned&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: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>That type signature is... a lot. It is for <code>RwLockWriteGuard</code> specifically. We would need similar impls for <code>RwLockReadGuard</code>. Fortunately, in practice you rarely write these by hand. Many projects use <code>thiserror</code> to derive conversions for their own error types, while specific errors like <code>PoisonError</code> are often handled explicitly with <code>.map_err()</code> or wrapped in another error type.</p> <p>In practice, many projects use <code>thiserror</code> to reduce boilerplate for their own error types. Since our goal here is to understand what <code>From</code> is doing under the hood, we'll write the conversion manually instead.</p> <h2 id="project-setup">Project Setup</h2> <p>Create a new project:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo new pastebin_api</span></span> <span class="giallo-l"><span>cd pastebin_api</span></span></code></pre> <p>Open <code>Cargo.toml</code> 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;pastebin_api&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>axum</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.8&quot;</span></span> <span class="giallo-l"><span>tokio</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&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;full&quot;</span><span style="color: #9399B2;">] }</span></span> <span class="giallo-l"><span>serde</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&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;derive&quot;</span><span style="color: #9399B2;">] }</span></span> <span class="giallo-l"><span>serde_json</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&quot;</span></span> <span class="giallo-l"><span>uuid</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&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;v4&quot;</span><span style="color: #9399B2;">] }</span></span> <span class="giallo-l"><span>chrono</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.4&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;serde&quot;</span><span style="color: #9399B2;">] }</span></span></code></pre> <p>We have two new dependencies compared to Part 1:</p> <ul> <li><code>chrono</code> handles timestamps and expiry calculations. The <code>serde</code> feature lets us serialize and deserialize <code>DateTime&lt;Utc&gt;</code> as ISO 8601 strings, which is the standard JSON representation for dates.</li> <li><code>uuid</code> for generating unique paste IDs, same as Part 1.</li> </ul> <h2 id="the-project-pastebin-api">The Project: Pastebin API</h2> <p>Our program will:</p> <ul> <li>Accept <code>POST /paste</code> with a JSON body containing content, an optional language, and an optional expiry duration</li> <li>Validate the input like reject empty content, oversized content, unsupported languages, and negative expiry</li> <li>Generate a unique ID and store the paste in memory with a creation timestamp</li> <li>Accept <code>GET /paste/{id}</code> that returns the paste as JSON</li> <li>Return 404 if the paste does not exist or has expired</li> <li>Return 400 for any validation failure with a specific message</li> <li>Return 500 for any internal failure with a generic message</li> </ul> <h3 id="data-model">Data Model</h3> <p>A paste is defined by six fields:</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;"> Paste</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</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> content</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> language</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;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> created_at</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> DateTime</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Utc</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> expires_at</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;">DateTime</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Utc</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>language</code> is optional, not all pastes are code. <code>expires_at</code> is optional as pastes can live forever. <code>created_at</code> is always set, using the server's clock at creation time.</p> <h3 id="supported-languages">Supported Languages</h3> <p>We limit language hints to a known set. This prevents typos like <code>"javscript"</code> and gives the client a clear error message:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">const</span><span style="color: #FAB387;"> SUPPORTED_LANGUAGES</span><span style="color: #94E2D5;">: &amp;</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> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;rust&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;python&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;javascript&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;typescript&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;go&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;java&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;c&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;cpp&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;ruby&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;php&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;swift&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;kotlin&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;scala&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;elixir&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;haskell&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;bash&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;sql&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;html&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;css&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;json&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;yaml&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;toml&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;markdown&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;plaintext&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">];</span></span></code></pre><h3 id="maximum-content-length">Maximum Content Length</h3> <p>We cap content at 500 KiB (500 × 1024 bytes). Larger pastes should be stored differently as object storage, not an in-memory API:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">const</span><span style="color: #FAB387;"> MAX_CONTENT_LENGTH</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 500</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> 1024</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // 500 KiB</span></span></code></pre><h3 id="the-full-code">The Full Code</h3> <p>Replace everything in <code>src/main.rs</code> 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;"> axum</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> extract</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">Path</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #9399B2;">},</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> http</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> response</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #9399B2;">},</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> routing</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span>get</span><span style="color: #9399B2;">,</span><span> post</span><span style="color: #9399B2;">},</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Json</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Router</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;">use</span><span style="color: #F9E2AF;"> chrono</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">DateTime</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Duration</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Utc</span><span style="color: #9399B2;">};</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> serde</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">Deserialize</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Serialize</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 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;"> RwLock</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> RwLockReadGuard</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> RwLockWriteGuard</span><span style="color: #9399B2;">};</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">net</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">TcpListener</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> uuid</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Uuid</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;"> SUPPORTED_LANGUAGES</span><span style="color: #94E2D5;">: &amp;</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> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;rust&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;python&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;javascript&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;typescript&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;go&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;java&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;c&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;cpp&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;ruby&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;php&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;swift&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;kotlin&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;scala&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;elixir&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;haskell&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;bash&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;sql&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;html&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;css&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;json&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;yaml&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;toml&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;markdown&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;plaintext&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;">const</span><span style="color: #FAB387;"> MAX_CONTENT_LENGTH</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> usize</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 500</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> 1024</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;">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;"> AppState</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> pastes</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;">RwLock</span><span style="color: #89DCEB;">&lt;</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;"> Paste</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: #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;"> Serialize</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Paste</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</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> content</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> language</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;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> created_at</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> DateTime</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Utc</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> expires_at</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;">DateTime</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Utc</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> <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;">Deserialize</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> CreatePasteRequest</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> content</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> language</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;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> expires_in_seconds</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: #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;">Serialize</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> CreatePasteResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</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: #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;">Serialize</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> GetPasteResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</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> content</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> language</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;">String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> created_at</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> DateTime</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Utc</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> expires_at</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;">DateTime</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Utc</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> <span class="giallo-l"><span style="color: #CBA6F7;">enum</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> ValidationError</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;"> NotFound</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;"> InternalError</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> <span class="giallo-l"><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> AppError</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_response</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;"> Response</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span style="color: #9399B2;"> (</span><span>status</span><span style="color: #9399B2;">,</span><span> message</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</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: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</span><span style="color: #9399B2;">(</span><span>msg</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">BAD_REQUEST</span><span style="color: #9399B2;">,</span><span> msg</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;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</span><span>msg</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">NOT_FOUND</span><span style="color: #9399B2;">,</span><span> msg</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;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">InternalError</span><span style="color: #9399B2;">(</span><span>msg</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;internal error: </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: #F9E2AF;font-style: italic;"> StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">INTERNAL_SERVER_ERROR</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;internal server error&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;"> let</span><span> body</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">serde_json</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">json!</span><span style="color: #9399B2;">({</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;error&quot;</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> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span>status</span><span style="color: #9399B2;">,</span><span> body</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into_response</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: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #F9E2AF;font-style: italic;"> From</span><span style="color: #89DCEB;">&lt;</span><span>std</span><span style="color: #94E2D5;">::</span><span>sync</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">PoisonError</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RwLockReadGuard</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">_</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #89DCEB;">&gt;&gt;&gt;</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> AppError</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</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">_</span><span style="color: #94E2D5;">:</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;">PoisonError</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RwLockReadGuard</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">_</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #89DCEB;">&gt;&gt;</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;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">InternalError</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;lock poisoned&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: #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: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #F9E2AF;font-style: italic;"> From</span><span style="color: #89DCEB;">&lt;</span><span>std</span><span style="color: #94E2D5;">::</span><span>sync</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">PoisonError</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RwLockWriteGuard</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">_</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #89DCEB;">&gt;&gt;&gt;</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> AppError</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</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">_</span><span style="color: #94E2D5;">:</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;">PoisonError</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RwLockWriteGuard</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">_</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #89DCEB;">&gt;&gt;</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;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">InternalError</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;lock poisoned&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: #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;">tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">main</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">async 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> state</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> AppState</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> pastes</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;">RwLock</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">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: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> app</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Router</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;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/paste&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> post</span><span style="color: #9399B2;">(</span><span>create_paste</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/paste/</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">id</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> get</span><span style="color: #9399B2;">(</span><span>get_paste</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">with_state</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> listener</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> TcpListener</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">bind</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;127.0.0.1:3000&quot;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;Listening on http://127.0.0.1:3000&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;"> axum</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">serve</span><span style="color: #9399B2;">(</span><span>listener</span><span style="color: #9399B2;">,</span><span> app</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> create_paste</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span>payload</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Json</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">CreatePasteRequest</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;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> validate_create_request</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>payload</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: #CBA6F7;"> let</span><span> id</span><span style="color: #94E2D5;"> = &amp;</span><span style="color: #F9E2AF;font-style: italic;">Uuid</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new_v4</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 style="color: #94E2D5;">..</span><span style="color: #FAB387;">8</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> expires_at</span><span style="color: #94E2D5;"> =</span><span> payload</span><span style="color: #94E2D5;">.</span><span>expires_in_seconds</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>seconds</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Utc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">now</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> +</span><span style="color: #F9E2AF;"> Duration</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">seconds</span><span style="color: #9399B2;">(</span><span>seconds</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> paste</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Paste</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span> id</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> content</span><span style="color: #94E2D5;">:</span><span> payload</span><span style="color: #94E2D5;">.</span><span>content</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> language</span><span style="color: #94E2D5;">:</span><span> payload</span><span style="color: #94E2D5;">.</span><span>language</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> created_at</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Utc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">now</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> expires_at</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> state</span><span style="color: #94E2D5;">.</span><span>pastes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">write</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">?.</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span>id</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span><span> paste</span><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: #F9E2AF;font-style: italic;"> StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">CREATED</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">CreatePasteResponse</span><span style="color: #9399B2;"> {</span><span> id</span><span style="color: #94E2D5;">:</span><span> id</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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> get_paste</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Path</span><span style="color: #9399B2;">(</span><span>id</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Path</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: #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;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> pastes</span><span style="color: #94E2D5;"> =</span><span> state</span><span style="color: #94E2D5;">.</span><span>pastes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">read</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: #CBA6F7;"> let</span><span> paste</span><span style="color: #94E2D5;"> =</span><span> pastes</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 style="color: #94E2D5;">&amp;</span><span>id</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">ok_or_else</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">||</span><span style="color: #F9E2AF;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;paste with id &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39; not found&quot;</span><span style="color: #9399B2;">,</span><span> id</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: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>expires_at</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> paste</span><span style="color: #94E2D5;">.</span><span>expires_at </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #F9E2AF;font-style: italic;"> Utc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">now</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &gt;</span><span> expires_at</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;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</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;paste with id &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39; has expired&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> id</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> response</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> GetPasteResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span> paste</span><span style="color: #94E2D5;">.</span><span>id</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> content</span><span style="color: #94E2D5;">:</span><span> paste</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> language</span><span style="color: #94E2D5;">:</span><span> paste</span><span style="color: #94E2D5;">.</span><span>language</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> created_at</span><span style="color: #94E2D5;">:</span><span> paste</span><span style="color: #94E2D5;">.</span><span>created_at</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> expires_at</span><span style="color: #94E2D5;">:</span><span> paste</span><span style="color: #94E2D5;">.</span><span>expires_at</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 style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">OK</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span>response</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;"> validate_create_request</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">req</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">CreatePasteRequest</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;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> req</span><span style="color: #94E2D5;">.</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;">is_empty</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;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;content must not be empty&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: #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> req</span><span style="color: #94E2D5;">.</span><span>content</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;"> MAX_CONTENT_LENGTH</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;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</span><span style="color: #9399B2;">(</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;content exceeds maximum length of </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> bytes (got </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> bytes)&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #FAB387;"> MAX_CONTENT_LENGTH</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> req</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">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: #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 style="color: #CBA6F7;">ref</span><span> lang</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> req</span><span style="color: #94E2D5;">.</span><span>language </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: #FAB387;">SUPPORTED_LANGUAGES</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>lang</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;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</span><span style="color: #9399B2;">(</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;unsupported language &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39;. supported languages: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> lang</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #FAB387;"> SUPPORTED_LANGUAGES</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;, &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: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>seconds</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> req</span><span style="color: #94E2D5;">.</span><span>expires_in_seconds </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> seconds</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: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;expires_in_seconds must be greater than 0&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: #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> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did.</p> <h3 id="the-state">The State</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;">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;"> AppState</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> pastes</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;">RwLock</span><span style="color: #89DCEB;">&lt;</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;"> Paste</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></code></pre> <p>Same pattern as Part 1. <code>HashMap</code> mapping paste IDs to <code>Paste</code> structs, wrapped in <code>Arc&lt;RwLock&lt;...&gt;&gt;</code> for shared concurrent access. The difference is the value type, <code>Paste</code> is a struct with six fields, not just a <code>String</code>.</p> <p><code>Paste</code> derives <code>Clone</code> and <code>Serialize</code>. <code>Clone</code> is necessary because <code>HashMap::get</code> returns a reference, and we need to clone some fields when building the response. <code>Serialize</code> is for the <code>DateTime&lt;Utc&gt;</code> fields to serialize as ISO 8601 strings.</p> <h3 id="the-request-and-response-types">The Request and Response Types</h3> <p>Three request/response types, designed for three concerns:</p> <p><code>CreatePasteRequest</code> - what the client sends. <code>content</code> is required. <code>language</code> and <code>expires_in_seconds</code> are optional. All validation logic references these fields.</p> <p><code>CreatePasteResponse</code> - what the server returns after creating a paste. Just the ID. The client can use that ID to fetch the full paste.</p> <p><code>GetPasteResponse</code> - the full paste returned on read. Includes the ID, content, language, timestamps, and expiry. This is the external representation. Notice it is a separate type from <code>Paste</code>, the internal <code>Paste</code> struct stores data, the response type formats it for the client.</p> <blockquote> <p><strong>Why separate request/response types from domain types?</strong> The Paste struct is our internal representation. It has an <code>id</code> field that the client never sends on creation (we generate it). The <code>CreatePasteRequest</code> does not have an <code>id</code> field. Separating these types prevents the client from setting <code>id</code> and prevents us from accidentally returning internal fields. This is a pattern you will see in every well-structured Rust API.</p> </blockquote> <h3 id="the-apperror-enum-and-intoresponse">The AppError Enum and IntoResponse</h3> <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;"> AppError</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> ValidationError</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;"> NotFound</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;"> InternalError</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></code></pre> <p>Three variants, one per HTTP error category. The <code>IntoResponse</code> implementation is the single place where errors become HTTP responses:</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;"> IntoResponse</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> AppError</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_response</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;"> Response</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span style="color: #9399B2;"> (</span><span>status</span><span style="color: #9399B2;">,</span><span> message</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</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: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</span><span style="color: #9399B2;">(</span><span>msg</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">BAD_REQUEST</span><span style="color: #9399B2;">,</span><span> msg</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;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</span><span>msg</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">NOT_FOUND</span><span style="color: #9399B2;">,</span><span> msg</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;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">InternalError</span><span style="color: #9399B2;">(</span><span>msg</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;internal error: </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: #F9E2AF;font-style: italic;"> StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">INTERNAL_SERVER_ERROR</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;internal server error&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;"> let</span><span> body</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">serde_json</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">json!</span><span style="color: #9399B2;">({</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;error&quot;</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> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span>status</span><span style="color: #9399B2;">,</span><span> body</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into_response</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>Every error response is <code>{"error": "..."}</code> with the appropriate status code. The client always gets a consistent JSON structure, regardless of which handler produced the error. If you later decide to add a <code>request_id</code> field to every error response, you change one function, not twenty handlers.</p> <p>The <code>InternalError</code> variant logs the actual error to stderr via <code>eprintln!</code> but sends a generic message to the client: <code>{"error": "internal server error"}</code>. We will replace <code>eprintln!</code> with structured logging via <code>tracing</code> in Part 16, but the principle is the same, internal details are for the server operator, never for the client.</p> <h3 id="from-impls-for-lock-poisoning">From Impls for Lock Poisoning</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: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #F9E2AF;font-style: italic;"> From</span><span style="color: #89DCEB;">&lt;</span><span>std</span><span style="color: #94E2D5;">::</span><span>sync</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">PoisonError</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RwLockReadGuard</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">_</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #89DCEB;">&gt;&gt;&gt;</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> AppError</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</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">_</span><span style="color: #94E2D5;">:</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;">PoisonError</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RwLockReadGuard</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">_</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #89DCEB;">&gt;&gt;</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;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">InternalError</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;lock poisoned&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: #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: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">T</span><span style="color: #89DCEB;">&gt;</span><span style="color: #F9E2AF;font-style: italic;"> From</span><span style="color: #89DCEB;">&lt;</span><span>std</span><span style="color: #94E2D5;">::</span><span>sync</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">PoisonError</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RwLockWriteGuard</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">_</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #89DCEB;">&gt;&gt;&gt;</span><span style="color: #CBA6F7;"> for</span><span style="color: #F9E2AF;font-style: italic;"> AppError</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</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">_</span><span style="color: #94E2D5;">:</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;">PoisonError</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">RwLockWriteGuard</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">&#39;</span><span style="color: #89B4FA;font-style: italic;">_</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> T</span><span style="color: #89DCEB;">&gt;&gt;</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;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">InternalError</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;lock poisoned&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: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>These impls let us use <code>?</code> with lock acquisition. Instead of <code>.unwrap()</code>, we 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> pastes</span><span style="color: #94E2D5;"> =</span><span> state</span><span style="color: #94E2D5;">.</span><span>pastes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">read</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span></code></pre> <p>The <code>?</code> converts <code>PoisonError&lt;RwLockReadGuard&lt;HashMap&lt;...&gt;&gt;&gt;</code> into <code>AppError::InternalError</code>, which <code>IntoResponse</code> converts into a 500 response. The handler never panics on a poisoned lock.</p> <blockquote> <p><strong>What is a poisoned lock?</strong> When a thread panics while holding a <code>Mutex</code> or <code>RwLock</code>, the lock is "poisoned", subsequent attempts to acquire it return an error. This prevents other threads from reading data that might be in an inconsistent state (the panicking thread might have been halfway through an update). In our case, the data is a <code>HashMap</code> of pastes. Rust does allow recovering from a poisoned lock, but this example intentionally treats it as an internal server error and returns a <code>500</code> instead.</p> </blockquote> <h3 id="the-create-paste-handler">The Create Paste Handler</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> create_paste</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span>payload</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Json</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">CreatePasteRequest</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;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> validate_create_request</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>payload</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: #CBA6F7;"> let</span><span> id</span><span style="color: #94E2D5;"> = &amp;</span><span style="color: #F9E2AF;font-style: italic;">Uuid</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new_v4</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 style="color: #94E2D5;">..</span><span style="color: #FAB387;">8</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> expires_at</span><span style="color: #94E2D5;"> =</span><span> payload</span><span style="color: #94E2D5;">.</span><span>expires_in_seconds</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>seconds</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> Utc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">now</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> +</span><span style="color: #F9E2AF;"> Duration</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">seconds</span><span style="color: #9399B2;">(</span><span>seconds</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> paste</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Paste</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span> id</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> content</span><span style="color: #94E2D5;">:</span><span> payload</span><span style="color: #94E2D5;">.</span><span>content</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> language</span><span style="color: #94E2D5;">:</span><span> payload</span><span style="color: #94E2D5;">.</span><span>language</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> created_at</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Utc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">now</span><span style="color: #9399B2;">(),</span></span> <span class="giallo-l"><span> expires_at</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> state</span><span style="color: #94E2D5;">.</span><span>pastes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">write</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">?.</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span>id</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span><span> paste</span><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: #F9E2AF;font-style: italic;"> StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">CREATED</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">CreatePasteResponse</span><span style="color: #9399B2;"> {</span><span> id</span><span style="color: #94E2D5;">:</span><span> id</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>Notice the return type: <code>Result&lt;impl IntoResponse, AppError&gt;</code>. This is the key pattern. The <code>Ok</code> branch returns a success response, a 201 with a JSON body. The <code>Err</code> branch is an <code>AppError</code>, which Axum converts via <code>IntoResponse</code>. The <code>?</code> operator on <code>validate_create_request</code> and <code>state.pastes.write()</code> converts failures into <code>AppError</code> automatically.</p> <p><code>validate_create_request(&amp;payload)?</code> runs all four validation checks before any work is done. If any check fails, the error is returned immediately. This is "fail fast", do not start creating a paste if the input is invalid.</p> <p><code>payload.expires_in_seconds.map(|seconds| { ... })</code> converts the optional expiry duration into an absolute timestamp. If <code>expires_in_seconds</code> is <code>None</code>, <code>expires_at</code> is <code>None</code>, the paste lives forever. If it is <code>Some(3600)</code>, <code>expires_at</code> is <code>Utc::now() + 1 hour</code>.</p> <blockquote> <p>For simplicity, we shorten the UUID to eight hexadecimal characters. Production systems typically use the full UUID or another identifier with collision guarantees appropriate for their scale.</p> </blockquote> <h3 id="the-get-paste-handler">The Get Paste Handler</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> get_paste</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Path</span><span style="color: #9399B2;">(</span><span>id</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Path</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: #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;">impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> pastes</span><span style="color: #94E2D5;"> =</span><span> state</span><span style="color: #94E2D5;">.</span><span>pastes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">read</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: #CBA6F7;"> let</span><span> paste</span><span style="color: #94E2D5;"> =</span><span> pastes</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 style="color: #94E2D5;">&amp;</span><span>id</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">ok_or_else</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">||</span><span style="color: #F9E2AF;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;paste with id &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39; not found&quot;</span><span style="color: #9399B2;">,</span><span> id</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: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>expires_at</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> paste</span><span style="color: #94E2D5;">.</span><span>expires_at </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #F9E2AF;font-style: italic;"> Utc</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">now</span><span style="color: #9399B2;">()</span><span style="color: #89DCEB;"> &gt;</span><span> expires_at</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;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">NotFound</span><span style="color: #9399B2;">(</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;paste with id &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39; has expired&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> id</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> response</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> GetPasteResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span> paste</span><span style="color: #94E2D5;">.</span><span>id</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> content</span><span style="color: #94E2D5;">:</span><span> paste</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> language</span><span style="color: #94E2D5;">:</span><span> paste</span><span style="color: #94E2D5;">.</span><span>language</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> created_at</span><span style="color: #94E2D5;">:</span><span> paste</span><span style="color: #94E2D5;">.</span><span>created_at</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> expires_at</span><span style="color: #94E2D5;">:</span><span> paste</span><span style="color: #94E2D5;">.</span><span>expires_at</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 style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">OK</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span>response</span><span style="color: #9399B2;">)))</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p><code>pastes.get(&amp;id)</code> returns <code>Option&lt;&amp;Paste&gt;</code>. <code>.ok_or_else(|| ...)</code> converts <code>None</code> into an <code>AppError::NotFound</code>. The <code>?</code> propagates that error if the paste does not exist.</p> <p>The expiry check happens after the lookup. If the paste exists but has expired, we return the same <code>NotFound</code> error. From the client's perspective, an expired paste and a non-existent paste are identical, you cannot access either one. A real application might delete expired pastes from the map periodically (a background cleanup task), but for this in-memory implementation, we check at read time.</p> <p>The response construction clones the fields that are <code>String</code> or <code>Option&lt;String&gt;</code>. <code>DateTime&lt;Utc&gt;</code> implements <code>Copy</code>, so we can pass it directly. Cloning strings is not free, and cloning the paste content is the most expensive part of this handler. Production systems often avoid unnecessary copies by using shared ownership types such as <code>Arc&lt;str&gt;</code> or other ownership strategies, depending on the application's requirements.</p> <h3 id="the-validation-function">The Validation 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;"> validate_create_request</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">req</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">CreatePasteRequest</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;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> req</span><span style="color: #94E2D5;">.</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;">is_empty</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;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;content must not be empty&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: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> req</span><span style="color: #94E2D5;">.</span><span>content</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;"> MAX_CONTENT_LENGTH</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;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</span><span style="color: #9399B2;">(</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;content exceeds maximum length of </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> bytes (got </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> bytes)&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #FAB387;"> MAX_CONTENT_LENGTH</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> req</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">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: #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 style="color: #CBA6F7;">ref</span><span> lang</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> req</span><span style="color: #94E2D5;">.</span><span>language </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: #FAB387;">SUPPORTED_LANGUAGES</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>lang</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;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</span><span style="color: #9399B2;">(</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;unsupported language &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39;. supported languages: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> lang</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #FAB387;"> SUPPORTED_LANGUAGES</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;, &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: #CBA6F7;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>seconds</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> req</span><span style="color: #94E2D5;">.</span><span>expires_in_seconds </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> seconds</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: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">ValidationError</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;expires_in_seconds must be greater than 0&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: #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> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>A standalone function, not a method on the handler. This keeps the handler clean and makes the validation logic testable independently, you can call <code>validate_create_request</code> in a unit test without setting up an entire Axum router.</p> <p>Four checks, each returning a specific error message:</p> <ol> <li> <p><strong>Content must not be empty</strong> - <code>"".trim()</code> is empty, <code>" ".trim()</code> is empty, <code>"hi".trim()</code> is not empty. Trimming prevents pastes that look empty but contain only whitespace.</p> </li> <li> <p><strong>Content must not exceed 500 KiB</strong> - includes the actual byte count in the error message so the client knows how much to trim.</p> </li> <li> <p><strong>Language must be supported</strong> - lists all supported languages in the error message. This is a self-documenting API: the error response tells the client what valid values look like.</p> </li> <li> <p><strong>Expiry must be positive</strong> - rejects zero and negative values. Zero-second expiry is nonsensical. Negative expiry is almost certainly a bug.</p> </li> </ol> <h2 id="running-the-project">Running the Project</h2> <p>Start the server:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run</span></span></code></pre> <p>You should see:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>Listening on http://127.0.0.1:3000</span></span></code></pre><h3 id="create-a-paste">Create a Paste</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -X POST http://localhost:3000/paste \</span></span> <span class="giallo-l"><span> -H &quot;Content-Type: application/json&quot; \</span></span> <span class="giallo-l"><span> -d &#39;{&quot;content&quot;: &quot;fn main() {\n println!(\&quot;hello world\&quot;);\n}&quot;, &quot;language&quot;: &quot;rust&quot;}&#39;</span></span></code></pre> <p>Response:</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;">id</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;">&quot;a1b2c3d4&quot;</span><span style="color: #9399B2;">}</span></span></code></pre><h3 id="read-the-paste">Read the Paste</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl http://localhost:3000/paste/a1b2c3d4</span></span></code></pre> <p>Response:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="json"><span class="giallo-l"><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">id</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;a1b2c3d4&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">content</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;fn main() {</span><span style="color: #F5C2E7;">\n</span><span style="color: #A6E3A1;"> println!(</span><span style="color: #F5C2E7;">\&quot;</span><span style="color: #A6E3A1;">hello world</span><span style="color: #F5C2E7;">\&quot;</span><span style="color: #A6E3A1;">);</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: #9399B2;"> &quot;</span><span style="color: #89B4FA;">language</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;rust&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">created_at</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;"> &quot;2026-07-06T12:00:00Z&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;"> &quot;</span><span style="color: #89B4FA;">expires_at</span><span style="color: #9399B2;">&quot;:</span><span style="color: #FAB387;"> null</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="create-a-paste-with-expiry">Create a Paste with Expiry</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -X POST http://localhost:3000/paste \</span></span> <span class="giallo-l"><span> -H &quot;Content-Type: application/json&quot; \</span></span> <span class="giallo-l"><span> -d &#39;{&quot;content&quot;: &quot;this will expire soon&quot;, &quot;expires_in_seconds&quot;: 5}&#39;</span></span></code></pre> <p>Wait 6 seconds, then read it:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl http://localhost:3000/paste/b2c3d4e5</span></span></code></pre> <p>Response:</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;">error</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;">&quot;paste with id &#39;b2c3d4e5&#39; has expired&quot;</span><span style="color: #9399B2;">}</span></span></code></pre> <p>Status code: 404.</p> <h3 id="test-validation-empty-content">Test Validation - Empty Content</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -X POST http://localhost:3000/paste \</span></span> <span class="giallo-l"><span> -H &quot;Content-Type: application/json&quot; \</span></span> <span class="giallo-l"><span> -d &#39;{&quot;content&quot;: &quot;&quot;}&#39;</span></span></code></pre> <p>Response:</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;">error</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;">&quot;content must not be empty&quot;</span><span style="color: #9399B2;">}</span></span></code></pre> <p>Status code: 400.</p> <h3 id="test-validation-unsupported-language">Test Validation - Unsupported Language</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -X POST http://localhost:3000/paste \</span></span> <span class="giallo-l"><span> -H &quot;Content-Type: application/json&quot; \</span></span> <span class="giallo-l"><span> -d &#39;{&quot;content&quot;: &quot;some code&quot;, &quot;language&quot;: &quot;brainfuck&quot;}&#39;</span></span></code></pre> <p>Response:</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;">error</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;">&quot;unsupported language &#39;brainfuck&#39;. supported languages: rust, python, ...&quot;</span><span style="color: #9399B2;">}</span></span></code></pre> <p>Status code: 400.</p> <h3 id="test-validation-negative-expiry">Test Validation - Negative Expiry</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -X POST http://localhost:3000/paste \</span></span> <span class="giallo-l"><span> -H &quot;Content-Type: application/json&quot; \</span></span> <span class="giallo-l"><span> -d &#39;{&quot;content&quot;: &quot;some code&quot;, &quot;expires_in_seconds&quot;: -10}&#39;</span></span></code></pre> <p>Response:</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;">error</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;">&quot;expires_in_seconds must be greater than 0&quot;</span><span style="color: #9399B2;">}</span></span></code></pre> <p>Status code: 400.</p> <h3 id="test-structural-error-missing-content">Test Structural Error - Missing Content</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -X POST http://localhost:3000/paste \</span></span> <span class="giallo-l"><span> -H &quot;Content-Type: application/json&quot; \</span></span> <span class="giallo-l"><span> -d &#39;{&quot;language&quot;: &quot;rust&quot;}&#39;</span></span></code></pre> <p>Response: <code>422 Unprocessable Entity</code>. Axum generates this response before our handler runs because deserializing the request into <code>CreatePasteRequest</code> fails when the required <code>content</code> field is missing.</p> <h3 id="test-structural-error-wrong-content-type">Test Structural Error - Wrong Content-Type</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -X POST http://localhost:3000/paste \</span></span> <span class="giallo-l"><span> -H &quot;Content-Type: text/plain&quot; \</span></span> <span class="giallo-l"><span> -d &#39;{&quot;content&quot;: &quot;hello&quot;}&#39;</span></span></code></pre> <p>Response: 415 Unsupported Media Type. Axum rejects this because the request is not using a JSON media type.</p> <h3 id="test-not-found">Test Not Found</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl http://localhost:3000/paste/nonexistent</span></span></code></pre> <p>Response:</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;">error</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;">&quot;paste with id &#39;nonexistent&#39; not found&quot;</span><span style="color: #9399B2;">}</span></span></code></pre> <p>Status code: 404.</p> <h2 id="the-boundary-between-framework-and-application">The Boundary Between Framework and Application</h2> <p>Look at the curl examples again. There are three categories of failure:</p> <ol> <li> <p><strong>Structural errors</strong> (422, 415) - handled by Axum automatically. Wrong content types, malformed JSON, and deserialization failures. You never write code for these.</p> </li> <li> <p><strong>Semantic errors</strong> (400) - handled by your validation function. Empty content, unsupported language, negative expiry. You write explicit checks and return <code>AppError::ValidationError</code>.</p> </li> <li> <p><strong>Resource errors</strong> (404) - handled by your handler logic. Missing paste, expired paste. You check the lookup result and return <code>AppError::NotFound</code>.</p> </li> </ol> <p>This is the boundary Axum draws. The framework handles everything it can detect from the structure of the request. You handle everything that requires understanding the meaning of the data. There is no overlap, no ambiguity, no framework guessing what status code your error should be.</p> <p>This is the opposite of "convention over configuration." Axum says: "I will handle the HTTP plumbing - parsing, routing, serialization. You handle every business decision, including what status code means what. There is no hidden application-level error handling."</p> <h2 id="how-an-error-flows-through">How an Error Flows Through</h2> <p>Let us trace a single <code>GET /paste/nonexistent</code> request to see how the <code>AppError</code> pattern works end-to-end:</p> <ol> <li> <p>The router matches <code>/paste/{id}</code> with <code>id = "nonexistent"</code> and selects <code>get_paste</code> as the handler.</p> </li> <li> <p><code>State&lt;AppState&gt;</code> extracts the state (clones the <code>Arc</code>, cheap).</p> </li> <li> <p><code>Path&lt;String&gt;</code> extracts <code>"nonexistent"</code> from the path.</p> </li> <li> <p>The handler runs. <code>state.pastes.read()?</code> succeeds (the lock is not poisoned). <code>pastes.get(&amp;id)</code> returns <code>None</code>. <code>.ok_or_else(|| AppError::NotFound(...))</code> converts <code>None</code> into <code>Err(AppError::NotFound("paste with id 'nonexistent' not found"))</code>. The <code>?</code> operator propagates the error out of the handler.</p> </li> <li> <p>The handler returns <code>Err(AppError::NotFound(...))</code>. Because the return type is <code>Result&lt;impl IntoResponse, AppError&gt;</code>, Axum calls <code>AppError::into_response()</code> on the error.</p> </li> <li> <p><code>AppError::into_response()</code> matches <code>NotFound</code>, sets the status to 404, formats the error message as <code>{"error": "paste with id 'nonexistent' not found"}</code>, and returns an <code>http::Response</code>.</p> </li> <li> <p>The response travels back through Hyper and Tokio, same as a success response.</p> </li> </ol> <p>Compare this to the Part 1 error handling: an ad-hoc <code>(StatusCode::NOT_FOUND, &amp;str)</code> in the handler. The new pattern separates error construction (in the handler) from error formatting (in <code>IntoResponse</code>). The handler says <em>what</em> went wrong. The <code>IntoResponse</code> implementation decides <em>how</em> to represent that to the client.</p> <h2 id="what-we-skipped">What We Skipped</h2> <ul> <li><strong>Persistence</strong>: Pastes live in memory and disappear on restart. Part 3 replaces the <code>HashMap</code> with PostgreSQL via SQLx.</li> <li><strong>Pagination</strong>: We return a single paste by ID. A real API would have <code>GET /pastes?language=rust&amp;page=1</code> for listing. We touched on <code>Query</code> parameters, but full pagination with SQL joins comes in Part 3.</li> <li><strong>Content type validation on read</strong>: A paste with <code>language: "markdown"</code> would ideally return <code>Content-Type: text/markdown</code>. For simplicity, we always return JSON.</li> <li><strong>Expired paste cleanup</strong>: Expired pastes stay in the <code>HashMap</code> forever, only rejected at read time. A background task that periodically removes expired entries would be the production pattern. Background tasks are Part 9.</li> <li><strong>The thiserror crate</strong>: We wrote <code>From</code> impls manually to show the mechanism. In practice, <code>thiserror</code> derives these for you. The manual impls are educational; the derive macro is what you use at work.</li> </ul> <h2 id="conclusion">Conclusion</h2> <p>In this post, you built a Pastebin API while learning Axum's extractors, validation, and centralized error handling. Next, we'll replace the in-memory <code>HashMap</code> with PostgreSQL and SQLx.</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> Thu, 02 Jul 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-axum-basics-and-routing-by-building-a-url-shortener/ https://blog.sheerluck.dev/posts/learn-axum-basics-and-routing-by-building-a-url-shortener/ <p>Welcome to the backend engineering series. If you followed the learning-rust series, you now understand ownership, borrowing, structs, enums, error handling, generics, lifetimes, closures, smart pointers, concurrency, and async/await. You built a thread pool and a raw HTTP/1.1 server from scratch over TCP. That was the foundation. Now we move up a layer.</p> <p><img src="/images/axum-basics-cover.png" alt="Axum Basics Cover Image" /></p> <p>In this series, we are going to learn backend engineering as practiced in Rust today, routing, persistence, authentication, caching, middleware, background jobs, WebSockets, API contracts, security hardening, testing, and deployment. Every article introduces a concept and then builds a standalone project around it. No shared codebase across articles. No capstone. Just a deliberate sequence where each concept is easiest to absorb once the previous one is in place.</p> <p>The only prerequisite is that you have completed the learning-rust series or are comfortable with async Rust and Tokio. I will assume you know how <code>Arc</code>, <code>tokio::spawn</code>, and <code>.await</code> work.</p> <p>In this post, we are going to <strong>build a URL shortener with Axum</strong>. But before that, we will learn what Axum actually is, how a request flows through it, from the TCP socket all the way to your handler function and why it's designed the way it is. We will learn about <code>Router</code>, <code>route()</code>, the <code>Handler</code> trait, path parameters, <code>State&lt;T&gt;</code>, and the <code>IntoResponse</code> trait. I promise you by the end of this article, Axum won't feel like a black box.</p> <p>Let's start, I can't wait.</p> <p>Get the source code from <a rel="external" href="https://github.com/MrSheerluck/url-shortener-in-axum">here</a></p> <h2 id="from-raw-tcp-to-axum">From Raw TCP to Axum</h2> <p>In the async/Tokio article, we built an HTTP server by hand. We called <code>TcpListener::bind</code>, accepted connections in a loop, read raw bytes from each socket, split the bytes on <code>\r\n</code> to find the request line, parsed headers manually, matched on the HTTP method, and wrote raw response bytes back with <code>socket.write_all</code>. It worked. It taught us what HTTP actually is under the hood.</p> <p>But that approach has a problem: every new endpoint means more manual byte-parsing logic. Every new feature like path parameters, query strings, JSON bodies, middleware is something you have to build yourself. And the result, even for a simple server, is hundreds of lines of infrastructure code before you write a single line of actual business logic.</p> <p>Axum solves exactly this. It sits on top of <code>hyper</code> (Rust's low-level HTTP library) and <code>tower</code> (a middleware and service abstraction), and gives you a clean set of abstractions: routes, extractors, responses, and state. You write a function. Axum calls it when a matching request arrives. You return something. Axum converts it into an HTTP response using the <code>IntoResponse</code> trait and writes it to the socket. Everything in between like parsing headers, routing, serialization, error conversion is handled by the framework.</p> <p>Here is the mental model to hold onto: Axum is a layer cake.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>Your handler function</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span>Axum (Router, extractors, IntoResponse)</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span>Tower (Service, Layer middleware)</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span>Hyper (HTTP/1.1 and HTTP/2 protocol handling)</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span>Tokio (async runtime, TCP sockets, I/O multiplexing)</span></span></code></pre> <p>Every request that arrives on a TCP socket bubbles up through Tokio (which handles the async I/O), through Hyper (which parses the raw bytes into an HTTP request representation), through Tower (which runs middleware), through Axum's routing layer (which matches the path and method to your handler), and finally into your function. The response travels back down the same stack in reverse.</p> <p>If you built the raw HTTP/1.1 server from the async article, you have already built the bottom two layers by hand. Axum gives you the top three.</p> <h3 id="what-is-hyper">What is Hyper?</h3> <p>Hyper is a low-level HTTP implementation. It parses the raw bytes received over a TCP connection into HTTP request values, manages connection lifecycles, implements HTTP/1.1 and HTTP/2, handles features like chunked transfer encoding, and encodes HTTP responses into bytes before writing them to the socket. Axum builds on top of Hyper rather than talking to TCP sockets directly.</p> <h3 id="what-is-tower">What is Tower?</h3> <p>Tower provides the <code>Service</code> trait:</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;"> Service</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Request</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> type</span><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> type</span><span style="color: #F9E2AF;font-style: italic;"> Error</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> type</span><span style="color: #F9E2AF;font-style: italic;"> Future</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Future</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Output</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Result</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;">Response</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> Self</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Error</span><span style="color: #89DCEB;">&gt;&gt;</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;"> poll_ready</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;"> cx</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Context</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;font-style: italic;"> Poll</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(),</span><span style="color: #F38BA8;"> Self</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Error</span><span style="color: #89DCEB;">&gt;&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;"> call</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;"> req</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Request</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: #F9E2AF;font-style: italic;">Future</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>A <code>Service</code> is anything that takes a request and returns a future that resolves to a response. That is it. An Axum <code>Router</code> implements <code>Service</code>. A rate-limiting middleware is a <code>Service</code> that wraps another <code>Service</code>. Everything in the request pipeline is eventually represented as a Tower <code>Service</code>: routers implement <code>Service</code>, middleware wraps <code>Service</code>s, and Axum adapts your handler functions into <code>Service</code>s behind the scenes.</p> <p>The <code>poll_ready</code> method lets a service indicate whether it is currently ready to receive another request. Tower uses this for backpressure. Most application code never interacts with it directly, so we'll ignore it in this series.</p> <p>A <code>Layer</code> produces a new <code>Service</code> by wrapping an existing <code>Service</code>. When you call <code>.layer(some_middleware)</code> on a router, you are wrapping the router's <code>Service</code> inside the middleware's <code>Service</code>. Every request passes through the outer layer first, then the inner layer, then eventually reaches your handler.</p> <p>We will go deep on Tower and middleware in Part 5. For now, just know it's there.</p> <h2 id="project-setup">Project Setup</h2> <p>Create a new project:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo new url_shortener</span></span> <span class="giallo-l"><span>cd url_shortener</span></span></code></pre> <p>Open <code>Cargo.toml</code> 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;url_shortener&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>axum</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;0.8&quot;</span></span> <span class="giallo-l"><span>tokio</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&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;full&quot;</span><span style="color: #9399B2;">] }</span></span> <span class="giallo-l"><span>serde</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&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;derive&quot;</span><span style="color: #9399B2;">] }</span></span> <span class="giallo-l"><span>serde_json</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&quot;</span></span> <span class="giallo-l"><span>uuid</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&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;v4&quot;</span><span style="color: #9399B2;">] }</span></span></code></pre> <p>We have four dependencies:</p> <ul> <li><code>axum</code> is the web framework</li> <li><code>tokio</code> is the async runtime (Axum runs on top of it)</li> <li><code>serde</code> and <code>serde_json</code> handle JSON serialization and deserialization</li> <li><code>uuid</code> generates unique short codes for our URLs. The <code>v4</code> feature gives us random UUIDs</li> </ul> <h2 id="the-simplest-possible-axum-server">The Simplest Possible Axum Server</h2> <p>Open <code>src/main.rs</code>, delete everything, and 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;"> axum</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;">routing</span><span style="color: #94E2D5;">::</span><span>get</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Router</span><span style="color: #9399B2;">};</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">net</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">TcpListener</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;">tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">main</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">async 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> app</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Router</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 style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> get</span><span style="color: #9399B2;">(</span><span>root</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> listener</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> TcpListener</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">bind</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;127.0.0.1:3000&quot;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;Listening on http://127.0.0.1:3000&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;"> axum</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">serve</span><span style="color: #9399B2;">(</span><span>listener</span><span style="color: #9399B2;">,</span><span> app</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> root</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, Axum!&quot;</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>Router::new()</code> creates an empty router. <code>.route("/", get(root))</code> registers a route: when a <code>GET</code> request arrives at <code>/</code>, call the <code>root</code> function. <code>route()</code> takes a path and a method handler. <code>get(root)</code> is shorthand. Axum provides <code>get()</code>, <code>post()</code>, <code>put()</code>, <code>delete()</code>, <code>patch()</code>, <code>head()</code>, and <code>options()</code> for every HTTP method. Each of them wraps your function in the router's internal machinery.</p> <p><code>TcpListener::bind("127.0.0.1:3000").await</code> creates a TCP listener bound to port 3000. This is the same <code>TcpListener</code> from Tokio that we used in the async article. You create the listener yourself and pass ownership of it to <code>axum::serve</code>.</p> <p><code>axum::serve(listener, app)</code> is the entry point. It takes your listener and your router, and runs an event loop: accept connections from the listener, parse HTTP requests with Hyper, route them through your router, and write responses back. It runs until the process is killed or the listener is closed.</p> <p>The <code>root</code> function is a handler. It returns <code>&amp;'static str</code>. Axum knows how to convert <code>&amp;'static str</code> into an HTTP response because <code>&amp;str</code> implements the <code>IntoResponse</code> trait.</p> <p>Run it:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run</span></span></code></pre> <p>Visit <code>http://127.0.0.1:3000</code> in your browser or run <code>curl http://localhost:3000</code>. You should see <code>Hello, Axum!</code>.</p> <h2 id="the-handler-trait-and-async-fn">The Handler Trait and async fn</h2> <p>Why does <code>async fn root() -&gt; &amp;'static str</code> work as a handler? Because Axum implements the <code>Handler</code> trait for async functions that satisfy certain conditions. The implementation is generic over the function's arguments and return type.</p> <p>You do not implement <code>Handler</code> yourself. The framework does it for you through a blanket impl. The rule is simple: any async function whose arguments all implement <code>FromRequestParts</code> (or <code>FromRequest</code> for the body) and whose return type implements <code>IntoResponse</code> is a valid handler.</p> <p>Extractors implementing <code>FromRequest</code> consume the request body, so a handler can have only one body extractor. Extractors implementing <code>FromRequestParts</code> only inspect the request metadata (such as the path, headers, or state), so they can be freely combined.</p> <p>This is what the <code>Handler</code> trait looks like, simplified:</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;"> Handler</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;"> S</span><span style="color: #89DCEB;">&gt;</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;"> Send</span><span style="color: #94E2D5;"> +</span><span style="color: #F9E2AF;font-style: italic;"> Sized</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: #CBA6F7;"> type</span><span style="color: #F9E2AF;font-style: italic;"> Future</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Future</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Output</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #89DCEB;">&gt;</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> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> call</span><span style="color: #9399B2;">(</span><span style="color: #F38BA8;">self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> req</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Request</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> state</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> S</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: #F9E2AF;font-style: italic;">Future</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>When Axum matches a route to your function, it calls <code>Handler::call</code>. The function's arguments are extracted from the request. The function runs. The return value is converted into an <code>http::Response</code> via <code>IntoResponse</code>. The response is written back to the socket.</p> <p>You never see this machinery. You just write a function and Axum does the rest.</p> <h2 id="intoresponse-why-so-many-types-work">IntoResponse - Why So Many Types Work</h2> <p>In the raw HTTP server, we built response strings by hand: <code>format!("HTTP/1.1 200 OK\r\nContent-Length: ...\r\n\r\n{}", body)</code>. That was tedious and error-prone.</p> <p>Axum solves this with the <code>IntoResponse</code> trait:</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;"> IntoResponse</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_response</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;"> Response</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Anything that implements this trait can be returned from a handler. Axum provides implementations for:</p> <table><thead><tr><th>Type</th><th>What it produces</th></tr></thead><tbody> <tr><td><code>&amp;'static str</code></td><td>200 OK with <code>text/plain; charset=utf-8</code></td></tr> <tr><td><code>String</code></td><td>200 OK with <code>text/plain; charset=utf-8</code></td></tr> <tr><td><code>StatusCode</code></td><td>A response with just that status code, no body</td></tr> <tr><td><code>(StatusCode, T)</code></td><td>A response with that status code and body <code>T</code> (where <code>T: IntoResponse</code>)</td></tr> <tr><td><code>(HeaderMap, T)</code></td><td>A response with custom headers and body <code>T</code></td></tr> <tr><td><code>(StatusCode, HeaderMap, T)</code></td><td>Status code, custom headers, and body</td></tr> <tr><td><code>Json&lt;T&gt;</code></td><td>200 OK with <code>application/json</code> body (where <code>T: Serialize</code>)</td></tr> <tr><td><code>Html&lt;T&gt;</code></td><td>200 OK with <code>text/html; charset=utf-8</code> body</td></tr> </tbody></table> <p>The tuple implementations are important. They let you compose status codes and bodies without a single wrapper type:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> handler</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #9399B2;">,</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: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #9399B2;"> (</span><span style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">NOT_FOUND</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;nothing here&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This returns a 404 with a plain-text body. The tuple <code>(StatusCode, T)</code> implements <code>IntoResponse</code> by combining the status code from the first element with the body from the second. The body's <code>IntoResponse</code> implementation handles the <code>Content-Type</code> header and the actual bytes.</p> <p><code>Json&lt;T&gt;</code> is another key type. It wraps any <code>T: Serialize</code> and returns a 200 with <code>Content-Type: application/json</code>. If serialization fails, it returns a 500 Internal Server Error.</p> <h2 id="state-sharing-data-across-handlers">State - Sharing Data Across Handlers</h2> <p>In the raw HTTP server, we used <code>Arc&lt;PathBuf&gt;</code> to share the serve directory across all connection tasks. Axum has the same need, your handlers often need access to shared data like a database pool, a configuration struct, or, in our case, the map of shortened URLs.</p> <p>Axum provides <code>State&lt;T&gt;</code> for 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;"> axum</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">extract</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">State</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;">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> <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> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> AppState</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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> handler</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Arc</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;&gt;</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> state</span><span style="color: #94E2D5;">.</span><span>message</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> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">main</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">async 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> state</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;font-style: italic;">AppState</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> message</span><span style="color: #94E2D5;">:</span><span style="color: #A6E3A1;"> &quot;hello from state&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> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> app</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Router</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;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> get</span><span style="color: #9399B2;">(</span><span>handler</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">with_state</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> listener</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> TcpListener</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">bind</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;127.0.0.1:3000&quot;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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: #F9E2AF;"> axum</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">serve</span><span style="color: #9399B2;">(</span><span>listener</span><span style="color: #9399B2;">,</span><span> app</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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>State&lt;Arc&lt;AppState&gt;&gt;</code> is an extractor. When Axum calls your handler, it looks at the function's arguments and tries to extract each one from the request (or from the application state). <code>State&lt;T&gt;</code> extracts the shared state that you provided to the router via <code>.with_state()</code>.</p> <p><code>Arc&lt;AppState&gt;</code> is the actual state type. It implements <code>Clone</code>, and cloning an <code>Arc</code> is inexpensive because it only increments an atomic reference count. This makes it an ideal way to share immutable ownership of application state across all request handlers.</p> <p><code>.with_state(state)</code> attaches the state to the router. Every handler in that router (and any sub-routers merged into it) can extract it with <code>State&lt;T&gt;</code>.</p> <blockquote> <p><strong>Important:</strong> The state type must be the same for the entire router. If you need different pieces of state in different handlers, put them all in one struct and wrap it in <code>Arc</code>.</p> </blockquote> <h2 id="path-parameters">Path Parameters</h2> <p>In the raw HTTP server, we parsed paths manually, strip the leading <code>/</code>, check for <code>..</code>, join with the serve directory. For a URL shortener, we need something much simpler: extract a short code from the URL path like <code>/abc123</code>.</p> <p>Axum handles this with <code>Path&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;">use</span><span style="color: #F9E2AF;"> axum</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">extract</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> <span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> redirect</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">Path</span><span style="color: #9399B2;">(</span><span>code</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Path</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 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;You requested code: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> code</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>When a request arrives at <code>GET /abc123</code>, Axum extracts <code>"abc123"</code> from the path, deserializes it into the type you specified (<code>String</code>), and passes it to your handler. <code>Path</code> implements <code>FromRequestParts</code>, just like <code>State</code>.</p> <p>The path parameter pattern in the route definition uses <code>{name}</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> app</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Router</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 style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">code</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> get</span><span style="color: #9399B2;">(</span><span>redirect</span><span style="color: #9399B2;">));</span></span></code></pre> <p>A request to <code>/abc123</code> matches this route, and the <code>Path(code)</code> extractor gives you <code>"abc123"</code>.</p> <blockquote> <p>Axum uses the <code>{name}</code> syntax (not the deprecated <code>:name</code> syntax from older versions). If you see <code>:name</code> in old tutorials, replace it with <code>{name}</code>.</p> </blockquote> <h2 id="the-project-url-shortener">The Project: URL Shortener</h2> <p>Now that you understand <code>Router</code>, handlers, <code>State</code>, <code>Path</code>, and <code>IntoResponse</code>, let's build a URL shortener.</p> <p>Our program will:</p> <ul> <li>Accept a <code>POST /shorten</code> with a JSON body containing a long URL</li> <li>Generate a unique short code using UUID v4</li> <li>Store the mapping in memory</li> <li>Return the short code as JSON</li> <li>Accept a <code>GET /{code}</code> that looks up the code and issues a 302 redirect</li> <li>Return 404 if the code does not exist</li> </ul> <p>To keep the focus on Axum itself, the application stores its data in memory using a <code>HashMap</code>. In later articles we will replace this with a real database using SQLx.</p> <h3 id="what-is-a-url-shortener">What is a URL Shortener?</h3> <p>A URL shortener takes a long URL like <code>https://en.wikipedia.org/wiki/Uniform_Resource_Locator</code> and maps it to a short one like <code>https://sho.rt/abc123</code>. When someone visits the short URL, the server looks up the original long URL and redirects them.</p> <p>The mapping is one-way: long URL → short code. There is no requirement to reverse-lookup a long URL to find its short code. This keeps things simple.</p> <h3 id="the-full-code">The Full Code</h3> <p>Replace everything in <code>src/main.rs</code> 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;"> axum</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> extract</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">Path</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #9399B2;">},</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> http</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">StatusCode</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> response</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">IntoResponse</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Redirect</span><span style="color: #9399B2;">},</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> routing</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span>get</span><span style="color: #9399B2;">,</span><span> post</span><span style="color: #9399B2;">},</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Json</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Router</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;">use</span><span style="color: #F9E2AF;"> serde</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">Deserialize</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Serialize</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 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;"> RwLock</span><span style="color: #9399B2;">};</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">net</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">TcpListener</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> uuid</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Uuid</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;">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;"> AppState</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> urls</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;">RwLock</span><span style="color: #89DCEB;">&lt;</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;"> String</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: #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;">Deserialize</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> ShortenRequest</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> url</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: #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;">Serialize</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> ShortenResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> short_url</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: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">main</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">async 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> state</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> AppState</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> urls</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;">RwLock</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;">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: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> app</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Router</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;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/shorten&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> post</span><span style="color: #9399B2;">(</span><span>shorten</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">route</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;/</span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">code</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #89B4FA;font-style: italic;"> get</span><span style="color: #9399B2;">(</span><span>redirect</span><span style="color: #9399B2;">))</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">with_state</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> listener</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> TcpListener</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">bind</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;127.0.0.1:3000&quot;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;Listening on http://127.0.0.1:3000&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;"> axum</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">serve</span><span style="color: #9399B2;">(</span><span>listener</span><span style="color: #9399B2;">,</span><span> app</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> shorten</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span>payload</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Json</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">ShortenRequest</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: #CBA6F7;"> impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> code</span><span style="color: #94E2D5;"> = &amp;</span><span style="color: #F9E2AF;font-style: italic;">Uuid</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new_v4</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 style="color: #94E2D5;">..</span><span style="color: #FAB387;">8</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> state</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span>urls</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">write</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><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 style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span>code</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span><span> payload</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">url</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> short_url</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;http://127.0.0.1:3000/</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> code</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: #F9E2AF;font-style: italic;"> StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">CREATED</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">ShortenResponse</span><span style="color: #9399B2;"> {</span><span> short_url</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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> redirect</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Path</span><span style="color: #9399B2;">(</span><span>code</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Path</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: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> urls</span><span style="color: #94E2D5;"> =</span><span> state</span><span style="color: #94E2D5;">.</span><span>urls</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">read</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> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> urls</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>code</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>long_url</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Redirect</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">to</span><span style="color: #9399B2;">(</span><span>long_url</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into_response</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: #F9E2AF;font-style: italic;"> StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">NOT_FOUND</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;404 Not Found: No URL for this code&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: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">into_response</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> <h3 id="the-state">The State</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;">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;"> AppState</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> urls</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;">RwLock</span><span style="color: #89DCEB;">&lt;</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;"> String</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></code></pre> <p><code>AppState</code> holds our in-memory store, a <code>HashMap</code> mapping short codes to long URLs. It is wrapped in <code>Arc&lt;RwLock&lt;...&gt;&gt;</code> because multiple requests will read and write to it concurrently. <code>RwLock</code> allows many concurrent readers or one exclusive writer, which matches our access pattern: reads are common (every redirect) and writes are rare (only on shortening).</p> <p><code>#[derive(Clone)]</code> is necessary because Axum clones the state for internal use. Since <code>Arc</code> is cheap to clone, it only increments an atomic reference count, the derived <code>Clone</code> implementation simply creates another <code>Arc</code> pointing to the same <code>RwLock&lt;HashMap&lt;...&gt;&gt;</code>.</p> <p>This example uses <code>std::sync::RwLock</code> because each critical section is very small and we never <code>.await</code> while holding the lock. If you need to hold a lock across asynchronous work, prefer <code>tokio::sync::RwLock</code>.</p> <h3 id="the-request-and-response-types">The Request and Response Types</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;">Deserialize</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> ShortenRequest</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> url</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: #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;">Serialize</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> ShortenResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> short_url</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>ShortenRequest</code> is what the client sends in the POST body. <code>#[derive(Deserialize)]</code> from <code>serde</code> tells the compiler to generate code that can parse this struct from JSON. <code>ShortenResponse</code> is what we send back. <code>#[derive(Serialize)]</code> generates code that converts this struct into JSON.</p> <p>These types are used with the <code>Json&lt;T&gt;</code> extractor and response type. When Axum sees <code>Json&lt;ShortenRequest&gt;</code> as a handler argument, it reads the request body, parses the JSON, and if it matches the struct, passes it to the handler. If the body is missing, malformed, or has the wrong types, Axum returns a 422 Unprocessable Entity automatically, before your handler ever runs.</p> <h3 id="the-shorten-handler">The Shorten Handler</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> shorten</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span>payload</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Json</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">ShortenRequest</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: #CBA6F7;"> impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> code</span><span style="color: #94E2D5;"> = &amp;</span><span style="color: #F9E2AF;font-style: italic;">Uuid</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new_v4</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 style="color: #94E2D5;">..</span><span style="color: #FAB387;">8</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> state</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span>urls</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">write</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><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 style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span>code</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span><span> payload</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">url</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> short_url</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;http://127.0.0.1:3000/</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> code</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: #F9E2AF;font-style: italic;"> StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">CREATED</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Json</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">ShortenResponse</span><span style="color: #9399B2;"> {</span><span> short_url</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 handler takes two extractors: <code>State&lt;AppState&gt;</code> (the shared state) and <code>Json&lt;ShortenRequest&gt;</code> (the parsed JSON body). Axum runs both extractors before calling the function. If either fails, the handler is never called and an error response is sent instead.</p> <p><code>Uuid::new_v4()</code> generates a random UUID like <code>a1b2c3d4-e5f6-7890-abcd-ef1234567890</code>. We take the first 8 characters (<code>a1b2c3d4</code>) as our short code. Eight hexadecimal characters provide roughly 4.3 billion possible codes. For this toy project that is more than sufficient, although a production URL shortener would still need to detect and handle collisions before storing a newly generated code.</p> <p><code>state.urls.write().unwrap()</code> acquires a write lock on the <code>RwLock</code>, giving us exclusive access to the <code>HashMap</code>. We insert the short code as the key and the long URL as the value. The lock is released when the <code>RwLockWriteGuard</code> goes out of scope at the end of the expression.</p> <p>The return type is <code>impl IntoResponse</code>. This means "I return something that implements <code>IntoResponse</code>, but I am not naming the exact type." The actual type is <code>(StatusCode, Json&lt;ShortenResponse&gt;)</code>, which is a tuple. The tuple implementation sets the status code to 201 Created and the body to the JSON-serialized response.</p> <h3 id="the-redirect-handler">The Redirect Handler</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> redirect</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> State</span><span style="color: #9399B2;">(</span><span>state</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> State</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">AppState</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> Path</span><span style="color: #9399B2;">(</span><span>code</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Path</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: #9399B2;">)</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #CBA6F7;"> impl</span><span style="color: #F9E2AF;font-style: italic;"> IntoResponse</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> urls</span><span style="color: #94E2D5;"> =</span><span> state</span><span style="color: #94E2D5;">.</span><span>urls</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">read</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> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> urls</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>code</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>long_url</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Redirect</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">to</span><span style="color: #9399B2;">(</span><span>long_url</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into_response</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: #F9E2AF;font-style: italic;"> StatusCode</span><span style="color: #94E2D5;">::</span><span style="color: #FAB387;">NOT_FOUND</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;404 Not Found: No URL for this code&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: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">into_response</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>Path(code): Path&lt;String&gt;</code> extractor pulls the <code>{code}</code> segment from the URL path. When a user visits <code>/abc12345</code>, <code>code</code> is <code>"abc12345"</code>.</p> <p><code>state.urls.read().unwrap()</code> acquires a read lock. Multiple redirect requests can hold read locks simultaneously, they do not block each other. Only the <code>shorten</code> handler's write lock blocks readers.</p> <p><code>urls.get(&amp;code)</code> returns an <code>Option&lt;&amp;String&gt;</code>. If the code exists, we get the long URL and return a <code>Redirect::to(long_url)</code>. <code>Redirect</code> is an Axum response type that produces a 303 Found with a <code>Location</code> header. The browser follows the redirect automatically.</p> <p>If the code does not exist, we return a 404 status with a plain-text body. Both branches call <code>.into_response()</code> explicitly. This is necessary because <code>match</code> arms must have the same type, and the two arms here produce different types (<code>Redirect</code> and <code>(StatusCode, &amp;str)</code>). Calling <code>.into_response()</code> on each arm converts them both to <code>Response</code>, which is a single concrete type.</p> <blockquote> <p><strong>Why <code>impl IntoResponse</code> and not <code>Response</code>?</strong> When the return type is <code>impl IntoResponse</code>, Axum calls <code>.into_response()</code> for you after your handler runs. But when different branches of a <code>match</code> return different types, you need to call <code>.into_response()</code> inside each branch to unify them yourself. The <code>impl IntoResponse</code> in the signature still works because <code>Response</code> implements <code>IntoResponse</code>.</p> </blockquote> <h2 id="running-the-project">Running the Project</h2> <p>Start the server:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run</span></span></code></pre> <p>You should see:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>Listening on http://127.0.0.1:3000</span></span></code></pre><h3 id="shorten-a-url">Shorten a URL</h3> <p>Open another terminal:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -X POST http://localhost:3000/shorten \</span></span> <span class="giallo-l"><span> -H &quot;Content-Type: application/json&quot; \</span></span> <span class="giallo-l"><span> -d &#39;{&quot;url&quot;: &quot;https://www.rust-lang.org&quot;}&#39;</span></span></code></pre> <p>Response:</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;">short_url</span><span style="color: #9399B2;">&quot;:</span><span style="color: #A6E3A1;">&quot;http://127.0.0.1:3000/a1b2c3d4&quot;</span><span style="color: #9399B2;">}</span></span></code></pre><h3 id="follow-the-redirect">Follow the Redirect</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -v http://localhost:3000/a1b2c3d4</span></span></code></pre> <p>You should see:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>* Request completely sent off</span></span> <span class="giallo-l"><span>&lt; HTTP/1.1 303 See Other</span></span> <span class="giallo-l"><span>&lt; location: https://www.rust-lang.org</span></span> <span class="giallo-l"><span>&lt; content-length: 0</span></span></code></pre> <p>Use <code>-L</code> to follow the redirect:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -L http://localhost:3000/a1b2c3d4</span></span></code></pre> <p>This fetches the Rust home page.</p> <h3 id="test-a-missing-code">Test a Missing Code</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -v http://localhost:3000/nonexist</span></span></code></pre> <p>Response:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>&lt; HTTP/1.1 404 Not Found</span></span> <span class="giallo-l"><span>404 Not Found: No URL for this code</span></span></code></pre><h3 id="test-a-bad-post-body">Test a Bad POST Body</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>curl -X POST http://localhost:3000/shorten \</span></span> <span class="giallo-l"><span> -H &quot;Content-Type: application/json&quot; \</span></span> <span class="giallo-l"><span> -d &#39;{&quot;not_url&quot;: 123}&#39;</span></span></code></pre> <p>Response:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>&lt; HTTP/1.1 422 Unprocessable Entity</span></span></code></pre> <p>Axum rejected this before our handler ever ran because the JSON did not match <code>ShortenRequest</code>. The required field <code>url</code> was missing, so deserializing the request into <code>ShortenRequest</code> failed before the handler was called. This is the extractor at work, <code>Json&lt;ShortenRequest&gt;</code> validates the body and returns a 422 if it does not match.</p> <h2 id="how-a-request-flows-through-the-full-trace">How a Request Flows Through - The Full Trace</h2> <p>Let's trace a single <code>GET /abc12345</code> request through every layer of the stack to understand what actually happens.</p> <ol> <li> <p><strong>Tokio</strong>: A TCP packet arrives on port 3000. Tokio's I/O driver is notified that the listening socket is ready, the runtime schedules the appropriate async task, and that task reads the incoming bytes from the socket.</p> </li> <li> <p><strong>Hyper</strong>: Hyper parses the raw bytes into an HTTP request representation, extracting the method, URI, version, headers, and request body before passing it to the next layer.</p> </li> <li> <p><strong>Tower</strong>: The request enters the Tower service stack. If we had middleware (we do not in this project, but we will in Part 5), each <code>Layer</code> would get a chance to inspect or modify the request before passing it inward. The outermost layer runs first.</p> </li> <li> <p><strong>Axum Router</strong>: The router receives the request and efficiently matches the request path against the registered routes. The pattern <code>/{code}</code> matches <code>/abc12345</code>, captures the path segment, verifies the HTTP method is <code>GET</code>, and selects the <code>redirect</code> handler.</p> </li> <li> <p><strong>Handler extraction</strong>: Before calling <code>redirect</code>, Axum runs the extractors. <code>State&lt;AppState&gt;</code> clones the <code>Arc</code> (cheap, just increments a reference count). <code>Path&lt;String&gt;</code> deserializes <code>abc12345</code> into a <code>String</code>. Both succeed. The handler is called with these two arguments.</p> </li> <li> <p><strong>Your handler</strong>: <code>redirect</code> acquires a read lock, looks up the code in the <code>HashMap</code>, finds the long URL, and returns <code>Redirect::to(long_url).into_response()</code>. This produces an <code>http::Response&lt;Body&gt;</code> with status 302 and a <code>Location</code> header.</p> </li> <li> <p><strong>Axum response</strong>: The <code>Response</code> travels back through the router. Axum does nothing further, the response is complete.</p> </li> <li> <p><strong>Tower</strong>: The response travels back out through the middleware stack. Each layer gets a chance to inspect or modify the response.</p> </li> <li> <p><strong>Hyper</strong>: Hyper encodes HTTP responses into bytes before writing them to the socket: <code>HTTP/1.1 302 Found\r\nlocation: https://...\r\ncontent-length: 0\r\n\r\n</code>. It writes these bytes to the socket.</p> </li> <li> <p><strong>Tokio</strong>: The socket write is async. If the socket buffer is full, the task yields. When the buffer drains, the runtime wakes the task. The response finishes writing. The connection is closed (or reused, if keep-alive were enabled).</p> </li> </ol> <p>All of this happens in under a millisecond for a simple in-memory lookup. The async runtime can handle thousands of these concurrently on a handful of OS threads.</p> <p>Compare this to the raw HTTP server from the async article. The flow is the same. The difference is that steps 3 through 7, routing, extraction, handler dispatch, response serialization were all written by hand in that article, and now Axum does them for us.</p> <h2 id="what-we-skipped">What We Skipped</h2> <p>There are a few things I am intentionally skipping in this article:</p> <ul> <li><strong>Persistent storage</strong>: Our URL mappings live in an in-memory <code>HashMap</code>. They disappear when the server restarts. In Part 3, we will add PostgreSQL persistence with SQLx.</li> <li><strong>Request validation</strong>: We accept any string as a URL. A real service would validate the format, reject empty strings, and potentially check that the URL is reachable. We will cover request validation in Part 2.</li> <li><strong>Error handling</strong>: We use <code>.unwrap()</code> on lock acquisition. In a production service, a poisoned lock (from a panic in another thread holding the lock) should be handled gracefully. We will build a proper <code>AppError</code> enum in Part 2.</li> <li><strong>Custom short codes</strong>: We use random UUID prefixes. A real service might let users choose custom codes or use a different encoding scheme (like base62) for shorter URLs.</li> <li><strong>Tower middleware, logging, tracing, CORS</strong>: These come in later parts, deliberately sequenced.</li> <li><strong>Graceful shutdown</strong>: The server stops immediately on Ctrl+C without draining in-flight requests. Part 9 covers this.</li> </ul> <blockquote> <p>Everything we skipped in this article exists for a reason in real-world services. Rather than introducing that complexity all at once, we focused on the Axum request lifecycle, routing, state, path parameters, and response types. This is the foundation that every subsequent part builds on.</p> </blockquote> <h2 id="conclusion">Conclusion</h2> <p>In this post, you learned what Axum is and where it sits in the stack: on top of Hyper and Tower, running inside Tokio. You learned the <code>Handler</code> trait, why any async function that takes extractors and returns <code>IntoResponse</code> just works as a handler. You learned <code>IntoResponse</code>, how tuples, <code>Json&lt;T&gt;</code>, status codes, and <code>Redirect</code> compose into HTTP responses without any boilerplate. You learned <code>State&lt;T&gt;</code> for shared application state and <code>Path&lt;T&gt;</code> for path parameters.</p> <p>You built a URL shortener from scratch. The server accepts <code>POST /shorten</code> with a JSON body, generates a random short code, stores the mapping in an <code>Arc&lt;RwLock&lt;HashMap&gt;&gt;</code>, and returns the short URL. <code>GET /{code}</code> looks up the code and issues a 302 redirect. Missing codes get a 404. Invalid JSON gets a 422.</p> <p>This is the foundation of every Axum application you will ever write. Router, extractors, state, and responses. Everything else like middleware, custom extractors, WebSockets, streaming is built on top of these four concepts.</p> <p>In the next article, we will learn about request bodies and error handling by building a Pastebin API. We will build a proper <code>AppError</code> enum, handle validation, and learn why Axum deliberately makes you decide every status code yourself instead of guessing. See you soon.</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> Sun, 28 Jun 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-the-basics-of-bevy-by-building-and-deploying-pong-to-itch-io/ 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 the Bevy game engine. In each article we build one game and learn different concepts along the way. All projects come from the <a rel="external" href="https://20_games_challenge.gitlab.io/challenge/">20 Games Challenge</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 know Rust (or can learn it on the go). I also have a <a rel="external" href="https://blog.sheerluck.dev/series/learning-rust/">Rust learning series</a> that follows the same project-based approach.</p> <p>In this post, we build <strong>Pong</strong>, the classic arcade game where two players bounce a ball past each other's paddles and publish it on <a rel="external" href="https://itch.io">Itch.io</a>. If you know Rust but have never built a game, this is the perfect place to start.</p> <blockquote> <p><strong>This is a rewrite of the original article</strong> in this series, updated for <strong>Bevy 0.19</strong> and rewritten in an <strong>incremental style</strong>. Every section ends with <code>cargo run</code> , you'll see progress on screen after each step.</p> </blockquote> <p>We'll learn: what a game loop is, how ECS (Entity-Component-System) works, how to detect collisions, how to handle keyboard input, and how to display text on screen.</p> <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 collision algorithm, which we won't do in future articles.</p> </blockquote> <p>Get the full source code from <a rel="external" href="https://github.com/MrSheerluck/bevy-pong">GitHub</a>. Published game is on <a rel="external" href="https://mrsheerluck.itch.io/pong-with-bevy-engine">itch.io</a>.</p> <h2 id="what-is-a-game-engine">What Is a Game Engine?</h2> <p>Before writing 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 paddles, move the ball, check for collisions.</li> <li><strong>Renders</strong> - draw everything on screen.</li> </ol> <p>This is the <strong>game loop</strong>. Without an engine, you'd write this loop yourself, read input, update state, draw pixels directly. An engine like Bevy handles graphics, audio, windowing, and input so you focus on your game.</p> <p>Bevy organizes game code using <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, the ball, the camera.</li> <li><strong>Component</strong>: Data attached to an entity. Position, velocity, color. 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="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">cargo</span><span style="color: #A6E3A1;"> new bevy_pong</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> bevy_pong</span></span></code></pre> <p>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.19&quot;</span></span></code></pre> <p>The <code>[dependencies]</code> section tells Cargo what external libraries to download and compile. <code>bevy = "0.19"</code> pulls in the Bevy engine at version 0.19.</p> <p>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;"> build</span></span></code></pre> <p>This takes 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="1-a-window-on-screen">1. A Window on Screen</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 style="color: #CBA6F7;">use</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;font-style: italic;">WindowResolution</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;"> WINDOW_WIDTH</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 800</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;"> WINDOW_HEIGHT</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 600</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;">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;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> 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;">WINDOW_WIDTH</span><span style="color: #CBA6F7;"> as u32</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> WINDOW_HEIGHT</span><span style="color: #CBA6F7;"> as u32</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> <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><h3 id="the-main-function-your-app-s-headquarters">The <code>main</code> function - your app's headquarters</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:</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>We use <code>.set()</code> to replace the default <code>WindowPlugin</code> with our own. This lets us control the window resolution (800×600) and title ("Pong").</p> <p><code>WindowResolution::new(WINDOW_WIDTH, WINDOW_HEIGHT)</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 for you.</p> <p><code>.insert_resource(ClearColor(Color::srgb(0.0, 0.0, 0.0)))</code> sets the background color. <code>ClearColor</code> is a <strong>resource</strong>, a singleton piece of data. Unlike components attached to entities, there's exactly one instance of it in the world. <code>Color::srgb(0.0, 0.0, 0.0)</code> is pure black (no red, no green, no blue).</p> <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 a few key 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> </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-creating-entities">The <code>setup</code> function - creating entities</h3> <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. You never create entities directly, always go through <code>Commands</code>.</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 coordinates), and <code>Frustum</code> (for culling off-screen objects). Without a camera, there's nothing to render through.</p> <h3 id="understanding-coordinates">Understanding coordinates</h3> <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. <code>Transform::from_xyz(x, y, z)</code> positions the entity at that coordinate. The z component controls which objects appear on top of others, higher z means closer to the camera. In a 2D game, we leave z at 0 for everything.</p> <p><strong>Run it:</strong></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 a black 800×600 window titled "Pong". Nothing else yet, but Bevy is set up correctly and compiles without errors.</p> <h2 id="2-two-paddles">2. Two Paddles</h2> <p>Now we add the paddles that players control.</p> <h3 id="creating-our-game-objects">Creating our game objects</h3> <p>In ECS, data lives in components. Let's define what a paddle is:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">const</span><span style="color: #FAB387;"> PADDLE_WIDTH</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</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 style="color: #CBA6F7;">const</span><span style="color: #FAB387;"> PADDLE_HEIGHT</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</span><span style="color: #94E2D5;"> =</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: #CBA6F7;">const</span><span style="color: #FAB387;"> PADDLE_SPEED</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</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> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span style="color: #FAB387;"> PADDLE_OFFSET</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 50</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: #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></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 Bevy needs to manage the data.</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). We store this data in the component so each paddle knows which keys to listen to.</p> <p><code>Side</code> is an enum, in Bevy, enums can be components too. We use it to determine which keyboard keys move which paddle.</p> <h3 id="spawning-the-paddles">Spawning the paddles</h3> <p>Now replace <code>setup()</code> with a version that spawns both paddles:</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;"> PADDLE_SPEED</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;">PADDLE_WIDTH</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> PADDLE_HEIGHT</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;">WINDOW_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: #94E2D5;"> +</span><span style="color: #FAB387;"> PADDLE_OFFSET</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;"> PADDLE_SPEED</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;">PADDLE_WIDTH</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> PADDLE_HEIGHT</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;">WINDOW_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: #94E2D5;"> -</span><span style="color: #FAB387;"> PADDLE_OFFSET</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 (white), the second is the size in pixels (10 wide, 100 tall).</p> <p><code>Transform::from_xyz(-WINDOW_WIDTH / 2.0 + PADDLE_OFFSET, 0.0, 0.0)</code> positions the left paddle. Our window is 800 pixels wide, so WINDOW_WIDTH / 2.0 = 400. The paddle sits at x = -400 + 50 = -350 (- 50 pixels from the left edge). The right paddle is at the mirror position.</p> <h3 id="making-the-paddles-move">Making the paddles move</h3> <p>Now we write our first real gameplay system, a function that reads keyboard input and moves the paddle:</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> <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> <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> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Clamp to window bounds</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> half_paddle</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> PADDLE_HEIGHT</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_height</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> WINDOW_HEIGHT</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> transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">=</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 style="color: #89B4FA;font-style: italic;">clamp</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> -</span><span>half_height</span><span style="color: #94E2D5;"> +</span><span> half_paddle</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> half_height</span><span style="color: #94E2D5;"> -</span><span> half_paddle</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="system-parameters-how-bevy-feeds-your-functions">System parameters - how Bevy feeds your functions</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 your 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 the W 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. The <code>mut</code> keyword means we can modify the components we asked for mutably.</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> <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. Not ideal (pressing both should cancel to zero), but functional enough for our first game.</p> <h3 id="clamping">Clamping</h3> <p>The <code>clamp</code> call keeps the paddle from going off the top or bottom of the screen. We calculate how far the paddle can travel: from <code>-half_height + half_paddle</code> (bottom edge + half paddle height) to <code>half_height - half_paddle</code> (top edge - half paddle height). This ensures the paddle's edge never crosses the window edge.</p> <p>Register the system 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;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> 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;">WINDOW_WIDTH</span><span style="color: #CBA6F7;"> as u32</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> WINDOW_HEIGHT</span><span style="color: #CBA6F7;"> as u32</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;">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> <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><strong>Run it:</strong></p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run</span></span></code></pre> <p>Two white rectangles appear near the left and right edges. Move the left paddle with <strong>W/S</strong> and the right paddle with <strong>Arrow Up/Down</strong>. The paddles stop at the window edges.</p> <h2 id="3-the-ball">3. The Ball</h2> <p>A Pong game needs a ball. Add the <code>Ball</code> component and the ball movement system:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">const</span><span style="color: #FAB387;"> BALL_SIZE</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</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> <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>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 add the ball to <code>setup()</code>, right after the paddle spawns:</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;"> // 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;">splat</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">BALL_SIZE</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></code></pre> <p><code>Vec2::splat(BALL_SIZE)</code> creates a <code>Vec2(10.0, 10.0)</code>. The ball starts at the exact center of the screen. Its velocity is 300 pixels/second to the right and 150 pixels/second upward. This diagonal path gives it an interesting angle.</p> <p>Add the movement 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_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 ball movement follows the exact same pattern as the paddle: add velocity multiplied by delta time to position. The difference is there's no input logic, the ball just moves according to its stored velocity.</p> <p>Register <code>move_ball</code> alongside <code>move_paddle</code>:</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. They run in the order listed.</p> <p><strong>Run it:</strong></p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run</span></span></code></pre> <p>The ball flies diagonally off-screen. That's expected, we haven't added walls yet.</p> <h2 id="4-walls-and-bouncing">4. Walls and Bouncing</h2> <p>The ball should bounce off the top and bottom of the window. Add this 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;"> bounce_ball</span><span style="color: #9399B2;">(</span><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: #CBA6F7;"> let</span><span> half_height</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> WINDOW_HEIGHT</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_ball</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> BALL_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> <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> half_ball</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> half_ball</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> half_ball</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> half_ball</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="the-collision-check">The collision check</h3> <p><code>half_height = WINDOW_HEIGHT / 2.0</code> - our window is 600 pixels tall, so the center is at y = 0, the top edge is at y = 300, and the bottom edge is at y = -300.</p> <p><code>half_ball = BALL_SIZE / 2.0</code> - our ball is 10×10 pixels, so its half-size (or "radius" for a square) is 5 pixels.</p> <p><code>transform.translation.y + half_ball &gt;= half_height</code> 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 ≥ 300. Collision detected.</p> <h3 id="the-snap">The snap</h3> <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> half_ball</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 - half_ball</code> = 300 - 5 = 295. This prevents the ball from getting stuck outside the wall.</p> <p><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 - half_ball &lt;= -half_height</code>.</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: #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><strong>Run it:</strong></p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run</span></span></code></pre> <p>The ball bounces off the top and bottom edges. It still passes through the paddles</p> <h2 id="5-paddle-collision">5. Paddle Collision</h2> <p>Now we make the ball bounce off both paddles using <strong>AABB collision detection</strong> (Axis-Aligned Bounding Box). Two rectangles overlap if they are <strong>not separated along any axis</strong>.</p> <p>Add this 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;"> 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;">splat</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">BALL_SIZE</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;">PADDLE_WIDTH</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> PADDLE_HEIGHT</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // AABB overlap 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> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Snap ball outside paddle to prevent sticking</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> <span class="giallo-l"><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> <span class="giallo-l"><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-preventing-data-races">Disjoint queries - preventing data races</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 without runtime checks.</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, if none of the four separation conditions are true, the rectangles overlap.</p> <h3 id="collision-response">Collision response</h3> <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 after reversal is positive), it hit the left side of the paddle, so we place it just to the right of the paddle's right edge. If moving left, we place it just to the left of the paddle's left 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>Register it:</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><strong>Run it:</strong></p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run</span></span></code></pre> <p>The ball bounces off both paddles and the top/bottom walls. Two-player Pong is playable.</p> <h2 id="6-scoring">6. Scoring</h2> <p>A game needs a score. We need a resource to store it and text to display it.</p> <h3 id="score-resource-and-text-marker">Score resource and text marker</h3> <p>Add these <strong>above</strong> <code>setup()</code>:</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 attached to entities, resources are global. There's only one score in the entire game. <code>#[derive(Default)]</code> initializes both fields to 0.</p> <p>We call it <code>insert_resource</code> instead of <code>spawn</code> because resources are not entities. They're singletons that any system can access. Entities are for things that exist in the game world (paddles, ball). Resources are for game-wide state (score, settings).</p> <p><code>ScoreText</code> is an empty <strong>marker component</strong>. We 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>Now add the score display to <code>setup()</code>, right after the camera spawn:</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;">text</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">FontSize</span><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> <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> <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: #F9E2AF;"> FontSize</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Px</span><span style="color: #9399B2;">(</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;"> WINDOW_HEIGHT</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 style="color: #FAB387;"> 50</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></code></pre> <p><code>Text2d::new("0 - 0")</code> creates text positioned in the 2D world. It wraps a <code>String</code>. The initial text shows "0 - 0".</p> <p><code>TextFont { font_size: FontSize::Px(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> <blockquote> <p><strong>Bevy 0.19 note:</strong> <code>TextFont::font_size</code> now uses <code>FontSize::Px(40.0)</code> instead of a bare <code>40.0</code>. This is one of the few breaking changes from 0.18.</p> </blockquote> <p><code>Transform::from_xyz(0.0, WINDOW_HEIGHT / 2.0 - 50.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 = 300 - 50 = 250, centered horizontally.</p> <p>Add the <code>use bevy::text::FontSize;</code> import at the very top of the file alongside the other imports:</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;"> bevy</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">text</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">FontSize</span><span style="color: #9399B2;">;</span></span> <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;">window</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">WindowResolution</span><span style="color: #9399B2;">;</span></span></code></pre><h3 id="the-scoring-system">The scoring system</h3> <p>Now add the system that detects when a player scores:</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;"> 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: #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> half_width</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> WINDOW_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;"> let</span><span> scored</span><span style="color: #94E2D5;"> =</span><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: #F38BA8;"> true</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: #F38BA8;"> true</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: #F38BA8;"> false</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>scored</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> 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> <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>Query&lt;&amp;mut Transform, With&lt;Ball&gt;&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>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.</p> <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>Register <code>score_goal</code> 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: #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>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> <span class="giallo-l"><span style="color: #9399B2;"> )</span></span></code></pre> <p><strong>Run it:</strong></p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run</span></span></code></pre> <p>Play a game. Each time a player misses, the score at the top updates and the ball resets to center.</p> <h2 id="deploying-to-itch-io">Deploying to Itch.io</h2> <p>Let's build a web version and publish it so anyone can play in their browser.</p> <p>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:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo install bevy_cli</span></span></code></pre> <p>Build 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</span></span></code></pre> <p>After it finishes, the generated files are in <code>target/wasm32-unknown-unknown/web-release/</code>. You should see:</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>Create an <code>index.html</code> file in that 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 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 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 style="color: #89B4FA;"> margin</span><span style="color: #94E2D5;">:</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">;</span><span style="color: #89B4FA;"> overflow</span><span style="color: #94E2D5;">:</span><span> hidden</span><span style="color: #9399B2;">;</span><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: #89B4FA;"> canvas</span><span style="color: #9399B2;"> {</span><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 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 style="color: #89B4FA;"> display</span><span style="color: #94E2D5;">:</span><span> block</span><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 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 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>Create a clean deployment folder and copy only what itch.io needs:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>mkdir itch_build</span></span> <span class="giallo-l"><span>cp target/wasm32-unknown-unknown/web-release/bevy_pong.js itch_build/</span></span> <span class="giallo-l"><span>cp target/wasm32-unknown-unknown/web-release/bevy_pong.wasm itch_build/</span></span> <span class="giallo-l"><span>cp target/wasm32-unknown-unknown/web-release/bevy_pong_bg.wasm itch_build/</span></span> <span class="giallo-l"><span>cp target/wasm32-unknown-unknown/web-release/index.html itch_build/</span></span> <span class="giallo-l"><span>cp -r target/wasm32-unknown-unknown/web-release/assets itch_build/</span></span></code></pre> <p>Zip it:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cd itch_build</span></span> <span class="giallo-l"><span>zip -r bevy_pong.zip .</span></span></code></pre> <p>Upload <code>bevy_pong.zip</code> to <a rel="external" href="https://itch.io">itch.io</a> as a new project. Under "Kind of project", select <strong>HTML</strong>. Enable <strong>"This file will be played in the browser"</strong>.</p> <h2 id="things-we-could-improve">Things We Could Improve</h2> <ul> <li>Randomize the ball direction after each score (right now it keeps the same velocity).</li> <li>Add sound effects for paddle hits, wall bounces, and scoring.</li> <li>Add a particle effect on collision for game feel.</li> <li>Add a win condition (first to 5, for example) with a game over screen.</li> </ul> <h2 id="what-we-learned">What We Learned</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 build <strong>Snake</strong> and learn about game states, timers, and grid-based movement.</p> <p>See you in the next one.</p> Fri, 26 Jun 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-sql-and-sqlx-by-building-a-book-library-cli-in-rust/ https://blog.sheerluck.dev/posts/learn-sql-and-sqlx-by-building-a-book-library-cli-in-rust/ <p>In this post, we are going to learn SQL from the ground up, no prior database knowledge required. We will learn about tables, data types, constraints, <code>SELECT</code>, <code>INSERT</code>, <code>UPDATE</code>, <code>DELETE</code>, filtering with <code>WHERE</code>, pattern matching with <code>LIKE</code>, sorting with <code>ORDER BY</code>, grouping with <code>GROUP BY</code>, aggregate functions like <code>COUNT</code> and <code>AVG</code>, <code>JOIN</code>s across multiple tables, subqueries, transactions, and indexes.</p> <p>We will practice every concept hands-on in the <code>sqlite3</code> terminal first. Then we will learn how to bring all of that into Rust with SQLx: compile-time checked queries, connection pooling, schema migrations, and the <code>query!</code>, <code>query_as!</code>, and <code>query_scalar!</code> macros. Once we cover all the concepts, we will build a <strong>Book Library CLI</strong> backed by SQLite with full CRUD, rich search, genre statistics, pagination, and bulk import with transactions. 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, smart pointers, concurrency, and async/await with Tokio.</p> <p>Get source code from <a rel="external" href="https://github.com/MrSheerluck/bookcli">here</a></p> <blockquote> <p><strong>A quick note before we begin:</strong> This article is in three parts. Part 1 teaches SQL from scratch using the <code>sqlite3</code> command-line tool, no Rust, just SQL. Part 2 introduces SQLx and explains how its compile-time checked queries work. Part 3 builds the full Book Library CLI. If you already know SQL well, you can skim Part 1. But I recommend at least glancing through it because the examples use the exact same schema we will build in the project, and we cover some patterns (GROUP BY on genres, subqueries for rankings) that you will use in the CLI.</p> </blockquote> <h2 id="part-1-learning-sql-from-scratch">Part 1: Learning SQL from Scratch</h2> <h3 id="what-is-a-database">What Is a Database</h3> <p>A database is an organised collection of data stored on disk. You interact with it using SQL (Structured Query Language). SQL is a declarative language. You describe <em>what</em> you want, not <em>how</em> to get it. The database engine figures out the how.</p> <p>Think of it like this. If you stored books in a JSON file, finding all science fiction books by a specific author would require you to read the entire file into memory, loop through every entry, and filter manually. At 10 books, this is fine. At 10,000 books, it is slow. At 10,000,000 books, it does not fit in memory. A database handles this by keeping data organised on disk, using indexes to find things without scanning everything, and returning only what you asked for.</p> <h3 id="why-sqlite">Why SQLite</h3> <p>The database engine we will use is SQLite. Unlike PostgreSQL or MySQL, SQLite is not a separate server process. It is a library that reads and writes directly to a single file on disk. This makes it perfect for learning, for CLI tools, for mobile apps, for desktop applications, and for embedded systems. SQLite is the most deployed database engine in the world. It runs inside every iPhone, every Android device, every Chrome browser, and every Python installation.</p> <h3 id="getting-started-with-sqlite3">Getting Started with sqlite3</h3> <p>Most systems come with <code>sqlite3</code> pre-installed. Check:</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;">sqlite3</span><span style="color: #A6E3A1;"> --version</span></span></code></pre> <p>If you see something like <code>3.43.0</code>, you are good. If not, install it (<code>brew install sqlite</code> on macOS, <code>apt install sqlite3</code> on Ubuntu).</p> <p>Create a database and enter the interactive shell:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>sqlite3 library.db</span></span></code></pre> <p>You are now inside the SQLite shell. Every command you type is SQL and ends with a semicolon <code>;</code>. To exit, type <code>.quit</code> (with a dot, dot commands are sqlite3-specific, not SQL). Let's create our first table.</p> <h3 id="creating-tables">Creating Tables</h3> <p>A table is like a spreadsheet. Columns have names and types. Rows are individual records. Here is our first table:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">CREATE TABLE</span><span style="color: #89B4FA;font-style: italic;"> books</span><span> (</span></span> <span class="giallo-l"><span> id </span><span style="color: #CBA6F7;">INTEGER PRIMARY KEY</span><span> AUTOINCREMENT,</span></span> <span class="giallo-l"><span> title </span><span style="color: #CBA6F7;">TEXT NOT NULL</span><span>,</span></span> <span class="giallo-l"><span> author </span><span style="color: #CBA6F7;">TEXT NOT NULL</span><span>,</span></span> <span class="giallo-l"><span> genre </span><span style="color: #CBA6F7;">TEXT NOT NULL</span><span>,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> year INTEGER</span><span>,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> read INTEGER NOT NULL DEFAULT</span><span style="color: #FAB387;"> 0</span></span> <span class="giallo-l"><span>);</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>CREATE TABLE books (...)</code> creates a new table called <code>books</code>. Inside the parentheses, we define columns. Each column has a name, a type, and optional constraints.</p> <p><code>id INTEGER PRIMARY KEY AUTOINCREMENT</code>. <code>INTEGER</code> is the type (a whole number). <code>PRIMARY KEY</code> means this column uniquely identifies each row, no two rows can have the same ID. <code>INTEGER PRIMARY KEY</code> already tells SQLite to automatically generate row IDs when you insert a row without specifying an ID. Adding <code>AUTOINCREMENT</code> changes the allocation strategy so previously used IDs are never reused, even if rows are deleted. It has a small performance cost, so most applications only use it when they specifically need that guarantee.</p> <p><code>title TEXT NOT NULL</code>. <code>TEXT</code> stores strings. <code>NOT NULL</code> means this column cannot be empty. You must provide a title for every book.</p> <p><code>author TEXT NOT NULL</code>. Same as title, every book must have an author.</p> <p><code>genre TEXT NOT NULL</code>. Every book must have a genre. We will use this for filtering and grouping later.</p> <p><code>year INTEGER</code>. No <code>NOT NULL</code> here, so <code>year</code> can be <code>NULL</code>. Some books have unknown publication years.</p> <p><code>read INTEGER NOT NULL DEFAULT 0</code>. <code>read</code> is an integer that acts as a boolean because SQLite does not have a separate <code>BOOLEAN</code> type. <code>0</code> means unread, <code>1</code> means read. <code>DEFAULT 0</code> means new books start as unread unless specified otherwise. This is our convention. We will map <code>0</code> and <code>1</code> to Rust's <code>bool</code> later with SQLx.</p> <p>SQLite has five storage classes:</p> <table><thead><tr><th>Storage Class</th><th>What It Stores</th><th>Example</th></tr></thead><tbody> <tr><td><code>INTEGER</code></td><td>Whole numbers</td><td><code>42</code>, <code>0</code>, <code>-7</code></td></tr> <tr><td><code>TEXT</code></td><td>Text strings</td><td><code>'hello'</code>, <code>'world'</code></td></tr> <tr><td><code>REAL</code></td><td>Floating-point numbers</td><td><code>3.14</code>, <code>-0.5</code></td></tr> <tr><td><code>BLOB</code></td><td>Binary data</td><td><code>X'89504E47'</code></td></tr> <tr><td><code>NULL</code></td><td>The absence of a value</td><td><code>NULL</code></td></tr> </tbody></table> <h3 id="inspecting-tables">Inspecting Tables</h3> <p>To see all tables in the database:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>.tables</span></span></code></pre> <p>To see the schema of a specific table:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>.schema books</span></span></code></pre> <p>Output:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">CREATE TABLE</span><span style="color: #89B4FA;font-style: italic;"> books</span><span> (</span></span> <span class="giallo-l"><span> id </span><span style="color: #CBA6F7;">INTEGER PRIMARY KEY</span><span> AUTOINCREMENT,</span></span> <span class="giallo-l"><span> title </span><span style="color: #CBA6F7;">TEXT NOT NULL</span><span>,</span></span> <span class="giallo-l"><span> author </span><span style="color: #CBA6F7;">TEXT NOT NULL</span><span>,</span></span> <span class="giallo-l"><span> genre </span><span style="color: #CBA6F7;">TEXT NOT NULL</span><span>,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> year INTEGER</span><span>,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> read INTEGER NOT NULL DEFAULT</span><span style="color: #FAB387;"> 0</span></span> <span class="giallo-l"><span>);</span></span></code></pre> <p>These dot commands are sqlite3-specific shortcuts. They are not SQL. Real SQL queries go through a different table called <code>sqlite_master</code>, but <code>.tables</code> and <code>.schema</code> are faster to type.</p> <h3 id="inserting-data">Inserting Data</h3> <p>Now let's add some books. The <code>INSERT</code> statement adds rows:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author, genre, </span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;The Rust Programming Language&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;Steve Klabnik&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;Programming&#39;</span><span>, </span><span style="color: #FAB387;">2018</span><span>);</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>INSERT INTO books</code> says we are adding to the <code>books</code> table. The parentheses <code>(title, author, genre, year)</code> list which columns we are providing values for. <code>VALUES (...)</code> provides the corresponding values. We did not specify <code>id</code> because <code>AUTOINCREMENT</code> handles it. We did not specify <code>read</code> because it defaults to <code>0</code>. The single quotes <code>'...'</code> denote string literals in SQL. Double quotes are for identifiers (table names, column names), single quotes are for string values.</p> <p>Insert more books:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author, genre, </span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Project Hail Mary&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;Andy Weir&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;Science Fiction&#39;</span><span>, </span><span style="color: #FAB387;">2021</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author, genre, </span><span style="color: #CBA6F7;">year</span><span>, </span><span style="color: #CBA6F7;">read</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;The Martian&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;Andy Weir&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;Science Fiction&#39;</span><span>, </span><span style="color: #FAB387;">2011</span><span>, </span><span style="color: #FAB387;">1</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author, genre, </span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Atomic Habits&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;James Clear&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;Self-Help&#39;</span><span>, </span><span style="color: #FAB387;">2018</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author, genre, </span><span style="color: #CBA6F7;">year</span><span>, </span><span style="color: #CBA6F7;">read</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Dune&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;Frank Herbert&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;Science Fiction&#39;</span><span>, </span><span style="color: #FAB387;">1965</span><span>, </span><span style="color: #FAB387;">1</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author, genre, </span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Neuromancer&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;William Gibson&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;Cyberpunk&#39;</span><span>, </span><span style="color: #FAB387;">1984</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author, genre, </span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Snow Crash&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;Neal Stephenson&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;Cyberpunk&#39;</span><span>, </span><span style="color: #FAB387;">1992</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author, genre, </span><span style="color: #CBA6F7;">year</span><span>, </span><span style="color: #CBA6F7;">read</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;The Name of the Wind&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;Patrick Rothfuss&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;Fantasy&#39;</span><span>, </span><span style="color: #FAB387;">2007</span><span>, </span><span style="color: #FAB387;">1</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author, genre, </span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;A Wise Man&#39;</span><span>s Fear</span><span style="color: #A6E3A1;">&#39;, &#39;</span><span>Patrick Rothfuss</span><span style="color: #A6E3A1;">&#39;, &#39;</span><span>Fantasy</span><span style="color: #A6E3A1;">&#39;, 2011);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #A6E3A1;">INSERT INTO books (title, author, genre, year, read) VALUES</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> (&#39;</span><span>Deep Work</span><span style="color: #A6E3A1;">&#39;, &#39;</span><span>Cal Newport</span><span style="color: #A6E3A1;">&#39;, &#39;</span><span style="color: #CBA6F7;">Self</span><span style="color: #94E2D5;">-</span><span>Help</span><span style="color: #A6E3A1;">&#39;, 2016, 1);</span></span></code></pre> <p>Now we have 10 books to work with.</p> <h3 id="selecting-data">Selecting Data</h3> <p>The <code>SELECT</code> statement retrieves data. It is the most used statement in SQL.</p> <h4 id="select-all-columns">SELECT All Columns</h4> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span style="color: #94E2D5;"> *</span><span style="color: #CBA6F7;"> FROM</span><span> books;</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>id title author genre year read</span></span> <span class="giallo-l"><span>-- --------------------------- ----------------- --------------- ---- ----</span></span> <span class="giallo-l"><span>1 The Rust Programming Langua Steve Klabnik Programming 2018 0</span></span> <span class="giallo-l"><span>2 Project Hail Mary Andy Weir Science Fiction 2021 0</span></span> <span class="giallo-l"><span>3 The Martian Andy Weir Science Fiction 2011 1</span></span> <span class="giallo-l"><span>4 Atomic Habits James Clear Self-Help 2018 0</span></span> <span class="giallo-l"><span>5 Dune Frank Herbert Science Fiction 1965 1</span></span> <span class="giallo-l"><span>6 Neuromancer William Gibson Cyberpunk 1984 0</span></span> <span class="giallo-l"><span>7 Snow Crash Neal Stephenson Cyberpunk 1992 0</span></span> <span class="giallo-l"><span>8 The Name of the Wind Patrick Rothfuss Fantasy 2007 1</span></span> <span class="giallo-l"><span>9 A Wise Man&#39;s Fear Patrick Rothfuss Fantasy 2011 0</span></span> <span class="giallo-l"><span>10 Deep Work Cal Newport Self-Help 2016 1</span></span></code></pre> <p><code>*</code> means "all columns." Read this as "select all columns from the books table."</p> <h4 id="select-specific-columns">SELECT Specific Columns</h4> <p>Selecting everything is wasteful if you only need titles. Be specific:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, author </span><span style="color: #CBA6F7;">FROM</span><span> books;</span></span></code></pre><h4 id="select-with-aliases">SELECT with Aliases</h4> <p>You can rename columns in the output with <code>AS</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title </span><span style="color: #CBA6F7;">AS</span><span> book_title, author </span><span style="color: #CBA6F7;">AS</span><span> written_by </span><span style="color: #CBA6F7;">FROM</span><span> books;</span></span></code></pre><h4 id="select-distinct">SELECT DISTINCT</h4> <p>To get unique values without duplicates:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT DISTINCT</span><span> genre </span><span style="color: #CBA6F7;">FROM</span><span> books;</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>genre</span></span> <span class="giallo-l"><span>---------------</span></span> <span class="giallo-l"><span>Programming</span></span> <span class="giallo-l"><span>Science Fiction</span></span> <span class="giallo-l"><span>Self-Help</span></span> <span class="giallo-l"><span>Cyberpunk</span></span> <span class="giallo-l"><span>Fantasy</span></span></code></pre> <p><code>DISTINCT</code> removes duplicates. There are 10 books but only 5 distinct genres.</p> <h3 id="filtering-with-where">Filtering with WHERE</h3> <p><code>WHERE</code> filters rows based on conditions. It comes after <code>FROM</code> and before <code>ORDER BY</code>.</p> <h4 id="equality-and-comparison">Equality and Comparison</h4> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, </span><span style="color: #CBA6F7;">year FROM</span><span> books </span><span style="color: #CBA6F7;">WHERE</span><span> author </span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;"> &#39;Andy Weir&#39;</span><span>;</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>title year</span></span> <span class="giallo-l"><span>------------------ ----</span></span> <span class="giallo-l"><span>Project Hail Mary 2021</span></span> <span class="giallo-l"><span>The Martian 2011</span></span></code></pre> <p>Comparison operators: <code>=</code> (equal), <code>!=</code> or <code>&lt;&gt;</code> (not equal), <code>&lt;</code> (less than), <code>&gt;</code> (greater than), <code>&lt;=</code>, <code>&gt;=</code>.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, </span><span style="color: #CBA6F7;">year FROM</span><span> books </span><span style="color: #CBA6F7;">WHERE year</span><span style="color: #94E2D5;"> &gt;=</span><span style="color: #FAB387;"> 2015</span><span>;</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>title year</span></span> <span class="giallo-l"><span>--------------------------- ----</span></span> <span class="giallo-l"><span>The Rust Programming Langua 2018</span></span> <span class="giallo-l"><span>Project Hail Mary 2021</span></span> <span class="giallo-l"><span>Atomic Habits 2018</span></span> <span class="giallo-l"><span>Deep Work 2016</span></span></code></pre><h4 id="and-or-not">AND, OR, NOT</h4> <p>Combine conditions with <code>AND</code> and <code>OR</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, </span><span style="color: #CBA6F7;">year FROM</span><span> books </span><span style="color: #CBA6F7;">WHERE</span><span> genre </span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;"> &#39;Science Fiction&#39;</span><span style="color: #CBA6F7;"> AND year</span><span style="color: #94E2D5;"> &lt;</span><span style="color: #FAB387;"> 2020</span><span>;</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>title year</span></span> <span class="giallo-l"><span>------------- ----</span></span> <span class="giallo-l"><span>The Martian 2011</span></span> <span class="giallo-l"><span>Dune 1965</span></span></code></pre> <p>Both conditions must be true for <code>AND</code>. For <code>OR</code>, only one needs to be true:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, genre </span><span style="color: #CBA6F7;">FROM</span><span> books </span><span style="color: #CBA6F7;">WHERE</span><span> genre </span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;"> &#39;Cyberpunk&#39;</span><span style="color: #CBA6F7;"> OR</span><span> genre </span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;"> &#39;Fantasy&#39;</span><span>;</span></span></code></pre> <p>You can group conditions with parentheses:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, author, </span><span style="color: #CBA6F7;">year FROM</span><span> books</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">WHERE</span><span> (genre </span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;"> &#39;Science Fiction&#39;</span><span style="color: #CBA6F7;"> OR</span><span> genre </span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;"> &#39;Fantasy&#39;</span><span>) </span><span style="color: #CBA6F7;">AND year</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #FAB387;"> 2000</span><span>;</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p>This finds Science Fiction or Fantasy books published after the year 2000. Without the parentheses, <code>AND</code> has higher precedence than <code>OR</code>, so <code>genre = 'Fantasy' AND year &gt; 2000</code> would be evaluated first, changing the meaning. Always use parentheses when mixing <code>AND</code> and <code>OR</code>.</p> <p><code>NOT</code> negates a condition:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title </span><span style="color: #CBA6F7;">FROM</span><span> books </span><span style="color: #CBA6F7;">WHERE NOT read</span><span>;</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>title</span></span> <span class="giallo-l"><span>---------------------------</span></span> <span class="giallo-l"><span>The Rust Programming Langua</span></span> <span class="giallo-l"><span>Project Hail Mary</span></span> <span class="giallo-l"><span>Atomic Habits</span></span> <span class="giallo-l"><span>Neuromancer</span></span> <span class="giallo-l"><span>Snow Crash</span></span> <span class="giallo-l"><span>A Wise Man&#39;s Fear</span></span></code></pre> <p>In SQLite, <code>read</code> is <code>0</code> or <code>1</code>. <code>NOT 0</code> is true, <code>NOT 1</code> is false. This shows all unread books. You could also write <code>WHERE read = 0</code>.</p> <h4 id="between">BETWEEN</h4> <p><code>BETWEEN</code> checks if a value is within a range (inclusive on both ends):</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, </span><span style="color: #CBA6F7;">year FROM</span><span> books </span><span style="color: #CBA6F7;">WHERE year BETWEEN</span><span style="color: #FAB387;"> 1990</span><span style="color: #CBA6F7;"> AND</span><span style="color: #FAB387;"> 2020</span><span>;</span></span></code></pre> <p>This is equivalent to <code>WHERE year &gt;= 1990 AND year &lt;= 2020</code>.</p> <h4 id="in">IN</h4> <p><code>IN</code> checks if a value matches any value in a list:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, genre </span><span style="color: #CBA6F7;">FROM</span><span> books </span><span style="color: #CBA6F7;">WHERE</span><span> genre </span><span style="color: #CBA6F7;">IN</span><span> (</span><span style="color: #A6E3A1;">&#39;Cyberpunk&#39;</span><span>, </span><span style="color: #A6E3A1;">&#39;Fantasy&#39;</span><span>);</span></span></code></pre> <p>This is equivalent to <code>WHERE genre = 'Cyberpunk' OR genre = 'Fantasy'</code>. <code>IN</code> is much cleaner when you have many values.</p> <h4 id="like-and-pattern-matching">LIKE and Pattern Matching</h4> <p><code>LIKE</code> does pattern matching on text. Two wildcards:</p> <ul> <li><code>%</code> matches any sequence of characters (including zero)</li> <li><code>_</code> matches exactly one character</li> </ul> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title </span><span style="color: #CBA6F7;">FROM</span><span> books </span><span style="color: #CBA6F7;">WHERE</span><span> title </span><span style="color: #CBA6F7;">LIKE</span><span style="color: #A6E3A1;"> &#39;%Rust%&#39;</span><span>;</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>title</span></span> <span class="giallo-l"><span>---------------------------</span></span> <span class="giallo-l"><span>The Rust Programming Langua</span></span></code></pre> <p><code>%Rust%</code> means "anything, then Rust, then anything." It finds any title containing the word "Rust."</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title </span><span style="color: #CBA6F7;">FROM</span><span> books </span><span style="color: #CBA6F7;">WHERE</span><span> author </span><span style="color: #CBA6F7;">LIKE</span><span style="color: #A6E3A1;"> &#39;A%&#39;</span><span>;</span></span></code></pre> <p><code>A%</code> means "starts with A." This matches Andy Weir.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title </span><span style="color: #CBA6F7;">FROM</span><span> books </span><span style="color: #CBA6F7;">WHERE</span><span> title </span><span style="color: #CBA6F7;">LIKE</span><span style="color: #A6E3A1;"> &#39;The %&#39;</span><span>;</span></span></code></pre> <p>In SQLite, <code>LIKE</code> is case-insensitive for ASCII characters by default. For example, <code>LIKE '%rust%'</code> also matches <code>"Rust"</code>.</p> <h4 id="is-null-and-is-not-null">IS NULL and IS NOT NULL</h4> <p>To check for NULL values, you cannot use <code>=</code> because <code>NULL = NULL</code> is false in SQL (NULL means "unknown," and two unknowns are not equal). Use <code>IS NULL</code> and <code>IS NOT NULL</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title </span><span style="color: #CBA6F7;">FROM</span><span> books </span><span style="color: #CBA6F7;">WHERE year IS NULL</span><span>;</span></span></code></pre> <p>This would return books with no publication year. We do not have any yet, so it returns nothing.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, </span><span style="color: #CBA6F7;">year FROM</span><span> books </span><span style="color: #CBA6F7;">WHERE year IS NOT NULL</span><span>;</span></span></code></pre> <p>This returns all books (all our books have years).</p> <h3 id="sorting-with-order-by">Sorting with ORDER BY</h3> <p><code>ORDER BY</code> sorts the result set. It comes after <code>WHERE</code> (and after <code>GROUP BY</code> if present).</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, </span><span style="color: #CBA6F7;">year FROM</span><span> books </span><span style="color: #CBA6F7;">ORDER BY year</span><span>;</span></span></code></pre> <p>Ascending (oldest first) is the default. For descending, add <code>DESC</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, </span><span style="color: #CBA6F7;">year FROM</span><span> books </span><span style="color: #CBA6F7;">ORDER BY year DESC</span><span>;</span></span></code></pre> <p>You can sort by multiple columns:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, author, </span><span style="color: #CBA6F7;">year FROM</span><span> books </span><span style="color: #CBA6F7;">ORDER BY</span><span> author, </span><span style="color: #CBA6F7;">year DESC</span><span>;</span></span></code></pre> <p>This sorts by author alphabetically. For books by the same author, it sorts by year descending (newest first).</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, </span><span style="color: #CBA6F7;">year FROM</span><span> books </span><span style="color: #CBA6F7;">ORDER BY read</span><span>, </span><span style="color: #CBA6F7;">year DESC</span><span>;</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p>Sorting by <code>read</code> first groups unread books together (read = 0 comes before read = 1 in ascending order). Within each read group, books are sorted by year descending. This is a common pattern: sort by a category first, then by a numeric value within each category.</p> <h3 id="limiting-and-paginating-with-limit-and-offset">Limiting and Paginating with LIMIT and OFFSET</h3> <p><code>LIMIT</code> restricts how many rows are returned. <code>OFFSET</code> skips rows at the beginning:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, </span><span style="color: #CBA6F7;">year FROM</span><span> books </span><span style="color: #CBA6F7;">ORDER BY year DESC LIMIT</span><span style="color: #FAB387;"> 3</span><span>;</span></span></code></pre> <p>This returns the 3 most recent books.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, </span><span style="color: #CBA6F7;">year FROM</span><span> books </span><span style="color: #CBA6F7;">ORDER BY year DESC LIMIT</span><span style="color: #FAB387;"> 3</span><span> OFFSET </span><span style="color: #FAB387;">3</span><span>;</span></span></code></pre> <p>This skips the first 3 and returns books 4 through 6. This is pagination. Page 1: <code>LIMIT 3 OFFSET 0</code>. Page 2: <code>LIMIT 3 OFFSET 3</code>. Page 3: <code>LIMIT 3 OFFSET 6</code>.</p> <p>SQLite also supports a shorthand:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, </span><span style="color: #CBA6F7;">year FROM</span><span> books </span><span style="color: #CBA6F7;">ORDER BY year DESC LIMIT</span><span style="color: #FAB387;"> 3</span><span>, </span><span style="color: #FAB387;">3</span><span>;</span></span></code></pre> <p><code>LIMIT 3, 3</code> means <code>LIMIT 3 OFFSET 3</code>. The first number is the offset, the second is the limit. I find this confusing, so I always write <code>LIMIT x OFFSET y</code>.</p> <h3 id="aggregate-functions">Aggregate Functions</h3> <p>Aggregate functions compute a single value from multiple rows.</p> <h4 id="count">COUNT</h4> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span style="color: #89B4FA;font-style: italic;"> COUNT</span><span>(</span><span style="color: #94E2D5;">*</span><span>) </span><span style="color: #CBA6F7;">FROM</span><span> books;</span></span></code></pre> <p>Returns <code>10</code>, the total number of rows.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span style="color: #89B4FA;font-style: italic;"> COUNT</span><span>(</span><span style="color: #94E2D5;">*</span><span>) </span><span style="color: #CBA6F7;">FROM</span><span> books </span><span style="color: #CBA6F7;">WHERE read</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 1</span><span>;</span></span></code></pre> <p>Returns <code>4</code>, the number of read books.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span style="color: #89B4FA;font-style: italic;"> COUNT</span><span>(</span><span style="color: #CBA6F7;">DISTINCT</span><span> author) </span><span style="color: #CBA6F7;">FROM</span><span> books;</span></span></code></pre> <p>Returns the number of unique authors. In our sample data there are 8 unique authors: Steve Klabnik, Andy Weir, James Clear, Frank Herbert, William Gibson, Neal Stephenson, Patrick Rothfuss, and Cal Newport.</p> <h4 id="sum-avg-max-min">SUM, AVG, MAX, MIN</h4> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span style="color: #89B4FA;font-style: italic;"> MAX</span><span>(</span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">FROM</span><span> books;</span></span></code></pre> <p>Returns <code>2021</code>, the most recent publication year.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span style="color: #89B4FA;font-style: italic;"> MIN</span><span>(</span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">FROM</span><span> books;</span></span></code></pre> <p>Returns <code>1965</code>.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span style="color: #89B4FA;font-style: italic;"> AVG</span><span>(</span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">FROM</span><span> books;</span></span></code></pre> <p>Returns the average publication year.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span style="color: #89B4FA;font-style: italic;"> SUM</span><span>(</span><span style="color: #CBA6F7;">read</span><span>) </span><span style="color: #CBA6F7;">FROM</span><span> books;</span></span></code></pre> <p>Returns <code>4</code>, since <code>read</code> is <code>0</code> or <code>1</code>, summing gives the count of read books.</p> <p>Because <code>read</code> stores <code>0</code> and <code>1</code>, <code>SUM(read)</code> gives the number of read books. This is a perfectly valid SQL technique. Some developers prefer <code>COUNT(*)</code> with a <code>WHERE</code> clause because it more clearly expresses the intent.</p> <h3 id="grouping-with-group-by">Grouping with GROUP BY</h3> <p><code>GROUP BY</code> groups rows that have the same values in specified columns. You then use aggregate functions on each group.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> genre, </span><span style="color: #89B4FA;font-style: italic;">COUNT</span><span>(</span><span style="color: #94E2D5;">*</span><span>) </span><span style="color: #CBA6F7;">AS</span><span> book_count </span><span style="color: #CBA6F7;">FROM</span><span> books </span><span style="color: #CBA6F7;">GROUP BY</span><span> genre;</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>genre book_count</span></span> <span class="giallo-l"><span>--------------- ----------</span></span> <span class="giallo-l"><span>Programming 1</span></span> <span class="giallo-l"><span>Science Fiction 3</span></span> <span class="giallo-l"><span>Self-Help 2</span></span> <span class="giallo-l"><span>Cyberpunk 2</span></span> <span class="giallo-l"><span>Fantasy 2</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>GROUP BY genre</code> creates one row per unique genre. <code>COUNT(*)</code> counts how many books are in each group. <code>AS book_count</code> gives the count column a name. Without <code>AS</code>, the column would be named <code>COUNT(*)</code>, which is ugly.</p> <p>The rule of <code>GROUP BY</code>: every column in the <code>SELECT</code> list must either be in the <code>GROUP BY</code> clause or be wrapped in an aggregate function. If you select <code>genre</code> and <code>title</code>, but only group by <code>genre</code>, which title should SQLite show? It cannot decide, so most databases reject this query. SQLite is lenient and picks an arbitrary title, but you should not rely on this.</p> <h4 id="group-by-with-multiple-columns">GROUP BY with Multiple Columns</h4> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> author, genre, </span><span style="color: #89B4FA;font-style: italic;">COUNT</span><span>(</span><span style="color: #94E2D5;">*</span><span>) </span><span style="color: #CBA6F7;">FROM</span><span> books </span><span style="color: #CBA6F7;">GROUP BY</span><span> author, genre;</span></span></code></pre> <p>This groups by the combination of author and genre. If an author writes in multiple genres, they appear in multiple rows.</p> <h4 id="having-filtering-groups">HAVING - Filtering Groups</h4> <p><code>WHERE</code> filters rows before grouping. <code>HAVING</code> filters groups after grouping:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> genre, </span><span style="color: #89B4FA;font-style: italic;">COUNT</span><span>(</span><span style="color: #94E2D5;">*</span><span>) </span><span style="color: #CBA6F7;">AS</span><span> cnt </span><span style="color: #CBA6F7;">FROM</span><span> books</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">GROUP BY</span><span> genre</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">HAVING</span><span> cnt </span><span style="color: #94E2D5;">&gt;</span><span style="color: #FAB387;"> 1</span><span>;</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>genre cnt</span></span> <span class="giallo-l"><span>--------------- ---</span></span> <span class="giallo-l"><span>Science Fiction 3</span></span> <span class="giallo-l"><span>Self-Help 2</span></span> <span class="giallo-l"><span>Cyberpunk 2</span></span> <span class="giallo-l"><span>Fantasy 2</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>GROUP BY genre</code> creates the groups. <code>HAVING cnt &gt; 1</code> keeps only groups with more than one book. Programming is excluded because it has only one book. The order of operations is: <code>FROM</code> → <code>WHERE</code> → <code>GROUP BY</code> → <code>HAVING</code> → <code>SELECT</code> → <code>ORDER BY</code> → <code>LIMIT</code>.</p> <h4 id="group-by-with-multiple-aggregates">GROUP BY with Multiple Aggregates</h4> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span></span> <span class="giallo-l"><span> genre,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> COUNT</span><span>(</span><span style="color: #94E2D5;">*</span><span>) </span><span style="color: #CBA6F7;">AS</span><span> total,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> SUM</span><span>(</span><span style="color: #CBA6F7;">read</span><span>) </span><span style="color: #CBA6F7;">AS</span><span> read_count,</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> ROUND</span><span>(</span><span style="color: #89B4FA;font-style: italic;">AVG</span><span>(</span><span style="color: #CBA6F7;">year</span><span>)) </span><span style="color: #CBA6F7;">AS</span><span> avg_year</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">FROM</span><span> books</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">GROUP BY</span><span> genre</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">ORDER BY</span><span> total </span><span style="color: #CBA6F7;">DESC</span><span>;</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p>Each genre group gets three computed values: the total number of books, the count of read books (by summing the <code>read</code> column, which is 0 or 1), and the rounded average publication year. <code>ROUND()</code> is a scalar function that rounds to the nearest integer. The result is sorted by total books, most popular genres first. This kind of query is the backbone of any dashboard or reporting feature.</p> <h3 id="updating-data">Updating Data</h3> <p><code>UPDATE</code> modifies existing rows:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">UPDATE</span><span> books </span><span style="color: #CBA6F7;">SET read</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 1</span><span style="color: #CBA6F7;"> WHERE</span><span> id </span><span style="color: #94E2D5;">=</span><span style="color: #FAB387;"> 1</span><span>;</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p>This marks book 1 as read. The <code>WHERE</code> clause is critical. If you omit it:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">UPDATE</span><span> books </span><span style="color: #CBA6F7;">SET read</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 1</span><span>; </span><span style="color: #9399B2;font-style: italic;">-- DANGER: updates ALL rows</span></span></code></pre> <p>Every book would be marked as read. Always double-check your <code>WHERE</code> clause before running an <code>UPDATE</code>.</p> <p>You can update multiple columns:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">UPDATE</span><span> books </span><span style="color: #CBA6F7;">SET read</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 1</span><span>, </span><span style="color: #CBA6F7;">year</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 2020</span><span style="color: #CBA6F7;"> WHERE</span><span> id </span><span style="color: #94E2D5;">=</span><span style="color: #FAB387;"> 6</span><span>;</span></span></code></pre> <p>The <code>WHERE</code> clause can use any condition we have learned:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">UPDATE</span><span> books </span><span style="color: #CBA6F7;">SET read</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 1</span><span style="color: #CBA6F7;"> WHERE</span><span> author </span><span style="color: #CBA6F7;">LIKE</span><span style="color: #A6E3A1;"> &#39;Andy%&#39;</span><span>;</span></span></code></pre> <p>This marks all books by authors whose name starts with "Andy" as read.</p> <h3 id="deleting-data">Deleting Data</h3> <p><code>DELETE</code> removes rows:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">DELETE FROM</span><span> books </span><span style="color: #CBA6F7;">WHERE</span><span> id </span><span style="color: #94E2D5;">=</span><span style="color: #FAB387;"> 10</span><span>;</span></span></code></pre> <p>Again, the <code>WHERE</code> clause is critical. Without it, every row is deleted:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">DELETE FROM</span><span> books; </span><span style="color: #9399B2;font-style: italic;">-- DANGER: deletes ALL rows from the table</span></span></code></pre> <p>If you want to delete all rows in test data, a faster alternative is <code>DELETE FROM books</code> (which logs each deletion) or <code>TRUNCATE TABLE books</code> (not supported by SQLite, use <code>DELETE FROM books</code> instead).</p> <h3 id="subqueries">Subqueries</h3> <p>A subquery is a query nested inside another query. The inner query runs first, and its result is used by the outer query.</p> <h4 id="subquery-in-where">Subquery in WHERE</h4> <p>Find all books published in a year where at least one book was read:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> title, </span><span style="color: #CBA6F7;">year FROM</span><span> books</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">WHERE year IN</span><span> (</span><span style="color: #CBA6F7;">SELECT year FROM</span><span> books </span><span style="color: #CBA6F7;">WHERE read</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 1</span><span>);</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p>The inner query <code>SELECT year FROM books WHERE read = 1</code> returns the years of all read books. The outer query finds all books published in any of those years, whether read or not. This is a semi-join pattern.</p> <h4 id="subquery-in-select">Subquery in SELECT</h4> <p>Show each book's publication year relative to the average:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span></span> <span class="giallo-l"><span> title,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> year</span><span>,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> year</span><span style="color: #94E2D5;"> -</span><span> (</span><span style="color: #CBA6F7;">SELECT</span><span style="color: #89B4FA;font-style: italic;"> AVG</span><span>(</span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">FROM</span><span> books) </span><span style="color: #CBA6F7;">AS</span><span> diff_from_avg</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">FROM</span><span> books</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">ORDER BY</span><span> diff_from_avg </span><span style="color: #CBA6F7;">DESC</span><span>;</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p>The subquery <code>SELECT AVG(year) FROM books</code> computes the average publication year once. For each book, we compute how far its year is from that average. Books after the average have positive values. Books before the average have negative values. The subquery in <code>SELECT</code> must return exactly one row and one column (a scalar value).</p> <h4 id="subquery-in-from">Subquery in FROM</h4> <p>Find the genre with the most books:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> genre, cnt </span><span style="color: #CBA6F7;">FROM</span><span> (</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> SELECT</span><span> genre, </span><span style="color: #89B4FA;font-style: italic;">COUNT</span><span>(</span><span style="color: #94E2D5;">*</span><span>) </span><span style="color: #CBA6F7;">AS</span><span> cnt </span><span style="color: #CBA6F7;">FROM</span><span> books </span><span style="color: #CBA6F7;">GROUP BY</span><span> genre</span></span> <span class="giallo-l"><span>) </span><span style="color: #CBA6F7;">AS</span><span> genre_counts</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">ORDER BY</span><span> cnt </span><span style="color: #CBA6F7;">DESC</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">LIMIT</span><span style="color: #FAB387;"> 1</span><span>;</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p>The inner query creates a temporary table (<code>genre_counts</code>) with genre names and counts. The outer query takes that temporary result and sorts it to find the most common genre. Subqueries in <code>FROM</code> are called derived tables. They must have an alias (<code>AS genre_counts</code>). This pattern is useful for multi-step analysis where you need to query the result of an aggregation.</p> <blockquote> <p>There is a cleaner way to write this using a Common Table Expression (CTE or <code>WITH</code> clause), but we will save CTEs for a future article.</p> </blockquote> <h3 id="joining-tables">Joining Tables</h3> <p>So far we have worked with a single table. Real databases have multiple related tables. Let's create two more tables to demonstrate joins.</p> <h4 id="creating-related-tables">Creating Related Tables</h4> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">CREATE TABLE</span><span style="color: #89B4FA;font-style: italic;"> authors</span><span> (</span></span> <span class="giallo-l"><span> id </span><span style="color: #CBA6F7;">INTEGER PRIMARY KEY</span><span> AUTOINCREMENT,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> name TEXT NOT NULL UNIQUE</span></span> <span class="giallo-l"><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">CREATE TABLE</span><span style="color: #89B4FA;font-style: italic;"> genres</span><span> (</span></span> <span class="giallo-l"><span> id </span><span style="color: #CBA6F7;">INTEGER PRIMARY KEY</span><span> AUTOINCREMENT,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> name TEXT NOT NULL UNIQUE</span></span> <span class="giallo-l"><span>);</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>UNIQUE</code> means no two rows can have the same value in this column. If we try to insert "Andy Weir" twice into <code>authors</code>, the second insert fails. This prevents duplicate authors and genres.</p> <p>Insert data into these tables:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> authors (</span><span style="color: #CBA6F7;">name</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Steve Klabnik&#39;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Andy Weir&#39;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;James Clear&#39;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Frank Herbert&#39;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;William Gibson&#39;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Neal Stephenson&#39;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Patrick Rothfuss&#39;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Cal Newport&#39;</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> genres (</span><span style="color: #CBA6F7;">name</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Programming&#39;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Science Fiction&#39;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Self-Help&#39;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Cyberpunk&#39;</span><span>),</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Fantasy&#39;</span><span>);</span></span></code></pre> <p>Now we have three tables. But they are not connected. We need to link books to authors and genres.</p> <h4 id="creating-a-better-books-table">Creating a Better Books Table</h4> <p>Let's drop our old books table and create one with foreign keys:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">DROP TABLE</span><span> books;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">CREATE TABLE</span><span style="color: #89B4FA;font-style: italic;"> books</span><span> (</span></span> <span class="giallo-l"><span> id </span><span style="color: #CBA6F7;">INTEGER PRIMARY KEY</span><span> AUTOINCREMENT,</span></span> <span class="giallo-l"><span> title </span><span style="color: #CBA6F7;">TEXT NOT NULL</span><span>,</span></span> <span class="giallo-l"><span> author_id </span><span style="color: #CBA6F7;">INTEGER NOT NULL</span><span>,</span></span> <span class="giallo-l"><span> genre_id </span><span style="color: #CBA6F7;">INTEGER NOT NULL</span><span>,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> year INTEGER</span><span>,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> read INTEGER NOT NULL DEFAULT</span><span style="color: #FAB387;"> 0</span><span>,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> FOREIGN KEY</span><span> (author_id) </span><span style="color: #CBA6F7;">REFERENCES</span><span> authors(id),</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> FOREIGN KEY</span><span> (genre_id) </span><span style="color: #CBA6F7;">REFERENCES</span><span> genres(id)</span></span> <span class="giallo-l"><span>);</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>DROP TABLE books</code> deletes the entire table. This is irreversible. In a real application, you would use migrations to add columns to an existing table instead of dropping it. We are doing this for the learning exercise.</p> <p><code>author_id INTEGER NOT NULL</code> stores the ID from the <code>authors</code> table instead of the author's name directly. <code>genre_id</code> does the same for genres. <code>FOREIGN KEY (author_id) REFERENCES authors(id)</code> tells SQLite that <code>author_id</code> must match an existing <code>id</code> in the <code>authors</code> table. If you try to insert a book with <code>author_id = 999</code> when no author has that ID, the insert fails. This is called referential integrity.</p> <blockquote> <p><strong>Want to learn how to design relational databases?</strong> We intentionally designed this schema to be simple so we can focus on learning SQL. In a real application, deciding <strong>what tables to create, how they relate to each other, when to normalize data, which constraints to use, and which columns should be indexed</strong> is an important skill on its own. I'll cover all of that in a dedicated follow-up article where we'll design relational databases from scratch, starting from application requirements and gradually evolving them into well-structured, production-ready schemas.</p> </blockquote> <p>Insert books with the new schema:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author_id, genre_id, </span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;The Rust Programming Language&#39;</span><span>, </span><span style="color: #FAB387;">1</span><span>, </span><span style="color: #FAB387;">1</span><span>, </span><span style="color: #FAB387;">2018</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author_id, genre_id, </span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Project Hail Mary&#39;</span><span>, </span><span style="color: #FAB387;">2</span><span>, </span><span style="color: #FAB387;">2</span><span>, </span><span style="color: #FAB387;">2021</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author_id, genre_id, </span><span style="color: #CBA6F7;">year</span><span>, </span><span style="color: #CBA6F7;">read</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;The Martian&#39;</span><span>, </span><span style="color: #FAB387;">2</span><span>, </span><span style="color: #FAB387;">2</span><span>, </span><span style="color: #FAB387;">2011</span><span>, </span><span style="color: #FAB387;">1</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author_id, genre_id, </span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Atomic Habits&#39;</span><span>, </span><span style="color: #FAB387;">3</span><span>, </span><span style="color: #FAB387;">3</span><span>, </span><span style="color: #FAB387;">2018</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author_id, genre_id, </span><span style="color: #CBA6F7;">year</span><span>, </span><span style="color: #CBA6F7;">read</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Dune&#39;</span><span>, </span><span style="color: #FAB387;">4</span><span>, </span><span style="color: #FAB387;">2</span><span>, </span><span style="color: #FAB387;">1965</span><span>, </span><span style="color: #FAB387;">1</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author_id, genre_id, </span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Neuromancer&#39;</span><span>, </span><span style="color: #FAB387;">5</span><span>, </span><span style="color: #FAB387;">4</span><span>, </span><span style="color: #FAB387;">1984</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author_id, genre_id, </span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Snow Crash&#39;</span><span>, </span><span style="color: #FAB387;">6</span><span>, </span><span style="color: #FAB387;">4</span><span>, </span><span style="color: #FAB387;">1992</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author_id, genre_id, </span><span style="color: #CBA6F7;">year</span><span>, </span><span style="color: #CBA6F7;">read</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;The Name of the Wind&#39;</span><span>, </span><span style="color: #FAB387;">7</span><span>, </span><span style="color: #FAB387;">5</span><span>, </span><span style="color: #FAB387;">2007</span><span>, </span><span style="color: #FAB387;">1</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author_id, genre_id, </span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;A Wise Man&#39;</span><span>s Fear</span><span style="color: #A6E3A1;">&#39;, 7, 5, 2011);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #A6E3A1;">INSERT INTO books (title, author_id, genre_id, year, read) VALUES</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> (&#39;</span><span>Deep Work</span><span style="color: #A6E3A1;">&#39;, 8, 3, 2016, 1);</span></span></code></pre> <p>Now if we <code>SELECT * FROM books</code>, we see IDs instead of names. That is not helpful for humans. We need to join the tables.</p> <h4 id="inner-join">INNER JOIN</h4> <p>An <code>INNER JOIN</code> combines rows from two tables based on a matching condition. It only returns rows where the match exists in both tables:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> books.title, authors.name</span><span style="color: #CBA6F7;"> AS</span><span> author, genres.name</span><span style="color: #CBA6F7;"> AS</span><span> genre</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">FROM</span><span> books</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">INNER JOIN</span><span> authors </span><span style="color: #CBA6F7;">ON</span><span> books.author_id</span><span style="color: #94E2D5;"> =</span><span> authors.id</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">INNER JOIN</span><span> genres </span><span style="color: #CBA6F7;">ON</span><span> books.genre_id</span><span style="color: #94E2D5;"> =</span><span> genres.id;</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>title author genre</span></span> <span class="giallo-l"><span>--------------------------- ----------------- ---------------</span></span> <span class="giallo-l"><span>The Rust Programming Langua Steve Klabnik Programming</span></span> <span class="giallo-l"><span>Project Hail Mary Andy Weir Science Fiction</span></span> <span class="giallo-l"><span>The Martian Andy Weir Science Fiction</span></span> <span class="giallo-l"><span>Atomic Habits James Clear Self-Help</span></span> <span class="giallo-l"><span>Dune Frank Herbert Science Fiction</span></span> <span class="giallo-l"><span>Neuromancer William Gibson Cyberpunk</span></span> <span class="giallo-l"><span>Snow Crash Neal Stephenson Cyberpunk</span></span> <span class="giallo-l"><span>The Name of the Wind Patrick Rothfuss Fantasy</span></span> <span class="giallo-l"><span>A Wise Man&#39;s Fear Patrick Rothfuss Fantasy</span></span> <span class="giallo-l"><span>Deep Work Cal Newport Self-Help</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>FROM books</code> starts with the books table. <code>INNER JOIN authors ON books.author_id = authors.id</code> takes each book row, looks up the matching author row where <code>authors.id</code> equals <code>books.author_id</code>, and combines them into a single result row. <code>INNER JOIN genres ON books.genre_id = genres.id</code> does the same for genres. The result looks like our original flat table, but the data is normalised, author names and genre names are stored only once, in their own tables. If an author's name changes, we update one row in <code>authors</code>, not every book by that author.</p> <p>When joining, you can prefix column names with the table name (<code>books.title</code>, <code>authors.name</code>) to avoid ambiguity. If two tables have columns with the same name, you must qualify them.</p> <h4 id="left-join">LEFT JOIN</h4> <p>An <code>INNER JOIN</code> excludes rows that do not have a match. A <code>LEFT JOIN</code> includes all rows from the left table, filling unmatched columns with <code>NULL</code>:</p> <p>Let's add an author with no books:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> authors (</span><span style="color: #CBA6F7;">name</span><span>) </span><span style="color: #CBA6F7;">VALUES</span><span> (</span><span style="color: #A6E3A1;">&#39;Isaac Asimov&#39;</span><span>);</span></span></code></pre> <p>Now compare:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">-- INNER JOIN: only authors who have books</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> authors.name, </span><span style="color: #89B4FA;font-style: italic;">COUNT</span><span>(books.id) </span><span style="color: #CBA6F7;">AS</span><span> book_count</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">FROM</span><span> authors</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">INNER JOIN</span><span> books </span><span style="color: #CBA6F7;">ON</span><span> authors.id</span><span style="color: #94E2D5;"> =</span><span> books.author_id</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">GROUP BY</span><span> authors.name</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">ORDER BY</span><span> book_count </span><span style="color: #CBA6F7;">DESC</span><span>;</span></span></code></pre> <p>This only shows the 8 authors who have books. Isaac Asimov is excluded.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #9399B2;font-style: italic;">-- LEFT JOIN: all authors, even those with no books</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span><span> authors.name, </span><span style="color: #89B4FA;font-style: italic;">COUNT</span><span>(books.id) </span><span style="color: #CBA6F7;">AS</span><span> book_count</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">FROM</span><span> authors</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">LEFT JOIN</span><span> books </span><span style="color: #CBA6F7;">ON</span><span> authors.id</span><span style="color: #94E2D5;"> =</span><span> books.author_id</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">GROUP BY</span><span> authors.name</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">ORDER BY</span><span> book_count </span><span style="color: #CBA6F7;">DESC</span><span>;</span></span></code></pre> <p>Isaac Asimov appears with <code>book_count = 0</code>.</p> <p>Now, let me explain what we just did.</p> <p><code>LEFT JOIN</code> keeps every row from the left table (<code>authors</code>). For Isaac Asimov, there are no matching <code>books</code> rows, so <code>books.id</code> is <code>NULL</code> for that joined row. <code>COUNT(books.id)</code> counts only non-NULL values, so it returns <code>0</code>. This is how you find authors with no books, genres with no books, or any "missing" relationship.</p> <h4 id="join-with-filtering-and-sorting">Join with Filtering and Sorting</h4> <p>You can combine joins with everything else we have learned:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">SELECT</span></span> <span class="giallo-l"><span> authors.name</span><span style="color: #CBA6F7;"> AS</span><span> author,</span></span> <span class="giallo-l"><span> books.title,</span></span> <span class="giallo-l"><span> books.year,</span></span> <span class="giallo-l"><span> genres.name</span><span style="color: #CBA6F7;"> AS</span><span> genre</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">FROM</span><span> books</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">INNER JOIN</span><span> authors </span><span style="color: #CBA6F7;">ON</span><span> books.author_id</span><span style="color: #94E2D5;"> =</span><span> authors.id</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">INNER JOIN</span><span> genres </span><span style="color: #CBA6F7;">ON</span><span> books.genre_id</span><span style="color: #94E2D5;"> =</span><span> genres.id</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">WHERE</span><span> books.read</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 0</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> AND</span><span> genres.name</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &#39;Science Fiction&#39;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">ORDER BY</span><span> books.year</span><span style="color: #CBA6F7;"> DESC</span><span>;</span></span></code></pre> <p>This finds all unread science fiction books, sorted by publication year (newest first). The query reads almost like English: "Select author name, book title, year, and genre name from books, joined with authors and genres, where the book is unread and the genre is Science Fiction, sorted by year descending."</p> <h3 id="transactions">Transactions</h3> <p>Start a transaction with <code>BEGIN</code>, run your statements, then <code>COMMIT</code> to save or <code>ROLLBACK</code> to undo:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">BEGIN</span><span>;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author_id, genre_id, </span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Foundation&#39;</span><span>, </span><span style="color: #FAB387;">9</span><span>, </span><span style="color: #FAB387;">2</span><span>, </span><span style="color: #FAB387;">1951</span><span>);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author_id, genre_id, </span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Foundation and Empire&#39;</span><span>, </span><span style="color: #FAB387;">9</span><span>, </span><span style="color: #FAB387;">2</span><span>, </span><span style="color: #FAB387;">1952</span><span>);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author_id, genre_id, </span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;Second Foundation&#39;</span><span>, </span><span style="color: #FAB387;">9</span><span>, </span><span style="color: #FAB387;">2</span><span>, </span><span style="color: #FAB387;">1953</span><span>);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">COMMIT</span><span>;</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p>All three inserts happen within a single transaction. If the computer crashes after the first insert but before <code>COMMIT</code>, the database rolls back to the state before <code>BEGIN</code>. Other database connections do not observe the changes until the transaction commits, subject to SQLite's transaction isolation rules.</p> <p>Try a rollback:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">BEGIN</span><span>;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">INSERT INTO</span><span> books (title, author_id, genre_id, </span><span style="color: #CBA6F7;">year</span><span>) </span><span style="color: #CBA6F7;">VALUES</span></span> <span class="giallo-l"><span> (</span><span style="color: #A6E3A1;">&#39;I, Robot&#39;</span><span>, </span><span style="color: #FAB387;">9</span><span>, </span><span style="color: #FAB387;">2</span><span>, </span><span style="color: #FAB387;">1950</span><span>);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">ROLLBACK</span><span>;</span></span></code></pre> <p>The insert is undone. <code>I, Robot</code> does not appear in the table.</p> <p>Transactions are essential for data integrity. Without them, a crash during a bulk import leaves your database in an inconsistent state. With them, it is all or nothing.</p> <h3 id="indexes">Indexes</h3> <p>When you run <code>SELECT * FROM books WHERE author_id = 5</code>, SQLite scans every row in the table checking the condition. With 10 rows, this is instant. With 10,000,000 rows, it is slow. An index speeds up lookups:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">CREATE INDEX</span><span style="color: #89B4FA;font-style: italic;"> idx_books_author_id</span><span style="color: #CBA6F7;"> ON</span><span> books(author_id);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">CREATE INDEX</span><span style="color: #89B4FA;font-style: italic;"> idx_books_genre_id</span><span style="color: #CBA6F7;"> ON</span><span> books(genre_id);</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p>An index is a separate data structure (a B-tree) that maps values to row locations. When you query <code>WHERE author_id = 5</code>, SQLite looks up <code>5</code> in the index (using a B-tree) instead of scanning every row in the table, making lookups, joins, and many sorts much more efficient on large datasets. Indexes also speed up <code>ORDER BY</code> and <code>JOIN</code> operations on the indexed columns.</p> <p>Indexes have a cost. Every <code>INSERT</code>, <code>UPDATE</code>, and <code>DELETE</code> must also update the indexes. And indexes take up disk space. Index columns you frequently filter or join on. Do not index columns that are rarely queried.</p> <p>To see what indexes exist:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>.indexes</span></span></code></pre> <p>SQLite also provides <code>EXPLAIN QUERY PLAN</code> to show how it intends to execute a query. Other database systems provide similar commands, although the syntax differs:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span>EXPLAIN QUERY PLAN </span><span style="color: #CBA6F7;">SELECT</span><span style="color: #94E2D5;"> *</span><span style="color: #CBA6F7;"> FROM</span><span> books </span><span style="color: #CBA6F7;">WHERE</span><span> author_id </span><span style="color: #94E2D5;">=</span><span style="color: #FAB387;"> 5</span><span>;</span></span></code></pre><h3 id="sql-summary">SQL Summary</h3> <p>We have covered a lot in this first part of the article. Here is a quick reference of the SQL concepts you now know.</p> <table><thead><tr><th>Clause / Keyword</th><th>What It Does</th><th>Example</th></tr></thead><tbody> <tr><td><code>CREATE TABLE</code></td><td>Defines a new table</td><td><code>CREATE TABLE t (id INTEGER PRIMARY KEY, name TEXT)</code></td></tr> <tr><td><code>INSERT INTO</code></td><td>Adds rows</td><td><code>INSERT INTO t (name) VALUES ('Alice')</code></td></tr> <tr><td><code>SELECT</code></td><td>Retrieves data</td><td><code>SELECT * FROM t</code></td></tr> <tr><td><code>SELECT DISTINCT</code></td><td>Returns unique values</td><td><code>SELECT DISTINCT name FROM t</code></td></tr> <tr><td><code>WHERE</code></td><td>Filters rows</td><td><code>WHERE age &gt; 18</code></td></tr> <tr><td><code>AND</code>, <code>OR</code>, <code>NOT</code></td><td>Combines conditions</td><td><code>WHERE a AND (b OR NOT c)</code></td></tr> <tr><td><code>BETWEEN</code></td><td>Range check</td><td><code>WHERE x BETWEEN 1 AND 10</code></td></tr> <tr><td><code>IN</code></td><td>Checks membership in a list</td><td><code>WHERE color IN ('red', 'blue')</code></td></tr> <tr><td><code>LIKE</code></td><td>Pattern matching</td><td><code>WHERE name LIKE 'A%'</code></td></tr> <tr><td><code>IS NULL</code>, <code>IS NOT NULL</code></td><td>Checks for NULL values</td><td><code>WHERE email IS NULL</code></td></tr> <tr><td><code>ORDER BY</code></td><td>Sorts results</td><td><code>ORDER BY year DESC</code></td></tr> <tr><td><code>LIMIT</code>, <code>OFFSET</code></td><td>Paginates results</td><td><code>LIMIT 10 OFFSET 20</code></td></tr> <tr><td><code>COUNT</code>, <code>SUM</code>, <code>AVG</code></td><td>Aggregate functions</td><td><code>SELECT COUNT(*) FROM t</code></td></tr> <tr><td><code>MAX</code>, <code>MIN</code></td><td>Finds extreme values</td><td><code>SELECT MAX(score) FROM t</code></td></tr> <tr><td><code>GROUP BY</code></td><td>Groups rows for aggregation</td><td><code>GROUP BY category</code></td></tr> <tr><td><code>HAVING</code></td><td>Filters grouped results</td><td><code>HAVING COUNT(*) &gt; 5</code></td></tr> <tr><td><code>UPDATE</code></td><td>Modifies existing rows</td><td><code>UPDATE t SET x = 1 WHERE id = 1</code></td></tr> <tr><td><code>DELETE</code></td><td>Removes rows</td><td><code>DELETE FROM t WHERE id = 1</code></td></tr> <tr><td><code>INNER JOIN</code></td><td>Combines matching rows from multiple tables</td><td><code>... INNER JOIN b ON a.id = b.a_id</code></td></tr> <tr><td><code>LEFT JOIN</code></td><td>Keeps all rows from the left table</td><td><code>... LEFT JOIN b ON a.id = b.a_id</code></td></tr> <tr><td><code>FOREIGN KEY</code></td><td>Enforces relationships between tables</td><td><code>FOREIGN KEY (x) REFERENCES t(id)</code></td></tr> <tr><td><code>BEGIN</code>, <code>COMMIT</code></td><td>Starts and commits a transaction</td><td><code>BEGIN; ... COMMIT;</code></td></tr> <tr><td><code>ROLLBACK</code></td><td>Cancels a transaction</td><td><code>BEGIN; ... ROLLBACK;</code></td></tr> <tr><td><code>CREATE INDEX</code></td><td>Speeds up lookups</td><td><code>CREATE INDEX idx ON t(col)</code></td></tr> <tr><td><code>EXPLAIN QUERY PLAN</code></td><td>Shows how SQLite executes a query</td><td><code>EXPLAIN QUERY PLAN SELECT ...</code></td></tr> </tbody></table> <p>At this point, you know enough SQL to build real applications. You can create tables, modify data, query it in different ways, combine related tables with joins, and write efficient queries using indexes and transactions.</p> <p>The next step is bringing those SQL queries into Rust. In Part 2, we'll learn SQLx, a library that lets us write raw SQL while giving us compile-time query checking, asynchronous database access, and a powerful migration system. Once we've learned SQLx, we'll put everything together in Part 3 by building our complete Book Library CLI.</p> <h2 id="part-2-sqlx-sql-meets-rust">Part 2: SQLx - SQL Meets Rust</h2> <h3 id="why-sqlx">Why SQLx</h3> <p>Rust has several libraries for working with databases, each with a different philosophy.</p> <table><thead><tr><th>Library</th><th>Style</th><th style="text-align: center">Async</th><th style="text-align: center">Compile-Time Query Checks</th></tr></thead><tbody> <tr><td>Diesel</td><td>ORM with its own query DSL</td><td style="text-align: center">No (synchronous)</td><td style="text-align: center">Yes</td></tr> <tr><td>SeaORM</td><td>ORM built on top of SQLx</td><td style="text-align: center">Yes</td><td style="text-align: center">Via SQLx</td></tr> <tr><td>rusqlite</td><td>Raw SQL</td><td style="text-align: center">No (synchronous)</td><td style="text-align: center">No</td></tr> <tr><td>SQLx</td><td>Raw SQL</td><td style="text-align: center">Yes</td><td style="text-align: center">Yes</td></tr> </tbody></table> <p>For this series, we'll use <strong>SQLx</strong>.</p> <p>There are three reasons.</p> <p>First, it is fully asynchronous and integrates directly with Tokio, making it suitable for modern Rust applications.</p> <p>Second, it lets us write <strong>real SQL</strong> instead of learning another query language. We just spent the entire first half of this article learning SQL, so it makes sense to use that knowledge directly.</p> <p>Finally and this is SQLx's biggest feature, it verifies your SQL queries at compile time against your actual database schema. If you misspell a column name, reference a table that doesn't exist, or try to map an SQL type to an incompatible Rust type, the compiler reports the error before your application ever runs.</p> <p>That combination of asynchronous I/O, raw SQL, and compile-time verification makes SQLx one of the most popular choices for database access in modern Rust applications.</p> <h3 id="compile-time-checked-queries">Compile-Time Checked Queries</h3> <p>This is SQLx's signature feature. 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> books</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;SELECT id, title, author FROM books&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">fetch_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span></code></pre> <p>At compile time, SQLx:</p> <ol> <li>Reads your <code>DATABASE_URL</code> environment variable</li> <li>Connects to the database</li> <li>Asks the database to validate the query and report information about the result columns and parameter types. The exact mechanism depends on the database backend.</li> <li>Checks that every column you are selecting actually exists</li> <li>Checks that the types match (TEXT maps to <code>String</code>, INTEGER maps to <code>i64</code>, etc.)</li> <li>Generates a struct with the correct field names and types</li> </ol> <p>If you mistype a column name:</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> books</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;SELECT id, title, authr FROM books&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">fetch_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span></code></pre> <p>The compiler gives you an error:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>error: no such column: authr</span></span></code></pre> <p>If you mismatch the number of parameters:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F9E2AF;">sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;INSERT INTO books (title, author) VALUES (?, ?, ?)&quot;</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> ...</span><span style="color: #9399B2;">)</span></span></code></pre> <p>The compiler tells you that you have 2 columns but 3 parameters.</p> <h3 id="setting-up-sqlx">Setting Up SQLx</h3> <p>Add to <code>Cargo.toml</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>dependencies</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>sqlx</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.9&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;runtime-tokio&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;sqlite&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;macros&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;migrate&quot;</span><span style="color: #9399B2;">] }</span></span> <span class="giallo-l"><span>tokio</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&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;full&quot;</span><span style="color: #9399B2;">] }</span></span></code></pre> <p><code>runtime-tokio</code> tells SQLx to use Tokio for async I/O. <code>sqlite</code> enables the SQLite driver.</p> <p>Set the database URL environment variable. You need this set whenever you compile because the macros connect to the database:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #CBA6F7;">export</span><span> DATABASE_URL</span><span style="color: #94E2D5;">=</span><span>sqlite:books.db</span></span></code></pre> <p><code>sqlite:books.db</code> means "SQLite database in the file <code>books.db</code>." You can also use <code>sqlite::memory:</code> for an in-memory database (ephemeral), or <code>sqlite:/absolute/path/to/db.sqlite</code> for a specific location.</p> <h3 id="connection-pooling-with-sqlitepool">Connection Pooling with SqlitePool</h3> <p>A connection pool holds multiple open connections. Tasks check out connections, use them, and return them. This gives concurrent database access without serialising everything through a mutex:</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;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">sqlite</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">SqlitePoolOptions</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></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;"> SqlitePoolOptions</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;">max_connections</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: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">connect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;sqlite:books.db&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>SqlitePoolOptions::new()</code> creates a builder. <code>.max_connections(5)</code> sets the pool size. Five is a reasonable default for many SQLite applications. SQLite supports many concurrent readers but only one writer at a time, so increasing the pool size does not necessarily improve write throughput. <code>.connect("sqlite:books.db").await</code> opens the file and creates the initial connections. The pool is cheap to clone (it uses <code>Arc</code> internally). Pass clones to different async tasks.</p> <h3 id="running-migrations">Running Migrations</h3> <p>Migrations are versioned SQL files that define your schema. SQLx keeps track of which migrations have already been applied so each migration is executed only once. When you run migrations, SQLx applies any that have not been applied yet. Create a <code>migrations</code> directory and add numbered SQL files:</p> <p><code>migrations/0001_initial.sql</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">CREATE TABLE</span><span style="color: #89B4FA;font-style: italic;"> IF</span><span style="color: #CBA6F7;"> NOT EXISTS</span><span> books (</span></span> <span class="giallo-l"><span> id </span><span style="color: #CBA6F7;">INTEGER PRIMARY KEY</span><span> AUTOINCREMENT,</span></span> <span class="giallo-l"><span> title </span><span style="color: #CBA6F7;">TEXT NOT NULL</span><span>,</span></span> <span class="giallo-l"><span> author </span><span style="color: #CBA6F7;">TEXT NOT NULL</span><span>,</span></span> <span class="giallo-l"><span> genre </span><span style="color: #CBA6F7;">TEXT NOT NULL</span><span>,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> read INTEGER NOT NULL DEFAULT</span><span style="color: #FAB387;"> 0</span></span> <span class="giallo-l"><span>);</span></span></code></pre> <p><code>migrations/0002_add_rating.sql</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">ALTER TABLE</span><span> books </span><span style="color: #CBA6F7;">ADD</span><span> COLUMN rating </span><span style="color: #CBA6F7;">INTEGER</span><span>;</span></span></code></pre> <p>In Rust:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F9E2AF;">sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">migrate!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;./migrations&quot;</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 style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span></code></pre> <p>The <code>migrate!</code> macro embeds the SQL files into the binary at compile time. At runtime, <code>.run(&amp;pool)</code> applies pending migrations. This is idempotent, running it multiple times is safe.</p> <h3 id="the-query-macros">The query! Macros</h3> <p>SQLx provides three macros for different return shapes.</p> <h4 id="query-ad-hoc-structs"><code>query!</code> - Ad-Hoc Structs</h4> <p>The macro generates an anonymous struct with fields matching the selected columns:</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> rows</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;SELECT id, title, author FROM books&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">fetch_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;">for</span><span> row</span><span style="color: #CBA6F7;"> in</span><span> rows</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;"> by </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> row</span><span style="color: #94E2D5;">.</span><span>id</span><span style="color: #9399B2;">,</span><span> row</span><span style="color: #94E2D5;">.</span><span>title</span><span style="color: #9399B2;">,</span><span> row</span><span style="color: #94E2D5;">.</span><span>author</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The generated struct has fields <code>id: i64</code>, <code>title: String</code>, <code>author: String</code>. You cannot name this type or store it in a struct field. Use it for quick queries where you consume the result immediately.</p> <h4 id="query-as-maps-to-your-structs"><code>query_as!</code> - Maps to Your Structs</h4> <p>Define a struct and derive <code>FromRow</code>:</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;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">FromRow</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Book</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> title</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> 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> genre</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> read</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> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">let</span><span> books</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">Book</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;SELECT id, title, author, genre, read FROM books&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">fetch_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span></code></pre> <p>The macro checks that every field in <code>Book</code> has a matching column, that the types are compatible, and that no required column is missing. <code>read: bool</code> maps <code>0</code>/<code>1</code> integers automatically.</p> <p>Although this example derives <code>sqlx::FromRow</code>, the <code>query_as!</code> macro does not actually require it because the macro generates the mapping at compile time. <code>FromRow</code> is mainly used with the runtime <code>query_as::&lt;_, T&gt;()</code> API.</p> <h4 id="query-scalar-single-value"><code>query_scalar!</code> - Single Value</h4> <p>For queries that return one column and one row:</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> count</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_scalar!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;SELECT COUNT(*) as count FROM books&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">fetch_one</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span></code></pre> <p><code>fetch_one</code> expects exactly one row. If there are zero or more than one, it returns an error.</p> <h4 id="parameterised-queries">Parameterised Queries</h4> <p>All three macros support <code>?</code> placeholders with parameters:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #F9E2AF;">sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;INSERT INTO books (title, author, genre) VALUES (?, ?, ?)&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> title</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> genre</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;">execute</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span></code></pre> <p>The macro checks at compile time that the number of <code>?</code> matches the number of parameters, and that each parameter's Rust type is compatible with the SQL column type. Parameters are bound separately, not interpolated into the SQL string, this prevents SQL injection.</p> <h2 id="part-3-the-project-book-library-cli">Part 3: The Project - Book Library CLI</h2> <p>Now that you know SQL and SQLx, let's build a Book Library CLI. Our program will:</p> <ul> <li>Store books in a SQLite database with title, author, genre, publication year, read status, and rating</li> <li>Run two migrations: create the <code>books</code> table, then add a <code>rating</code> column</li> <li>Add, list, search, update, rate, and delete books</li> <li>Search by title, author, or genre with <code>LIKE</code> patterns</li> <li>Show genre statistics with <code>GROUP BY</code> and <code>COUNT</code></li> <li>Sort results by title, year, or rating with <code>ORDER BY</code></li> <li>Support pagination with <code>LIMIT</code> and <code>OFFSET</code></li> <li>Import books in bulk from JSON using transactions</li> <li>Every query is type-safe and checked against the live database at compile time</li> </ul> <h3 id="project-setup">Project Setup</h3> <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 bookcli</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> bookcli</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">mkdir</span><span style="color: #A6E3A1;"> -p migrations</span></span></code></pre> <p><code>Cargo.toml</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;bookcli&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;2021&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>sqlx</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.9&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;runtime-tokio&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;sqlite&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;macros&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;migrate&quot;</span><span style="color: #9399B2;">] }</span></span> <span class="giallo-l"><span>tokio</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&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;full&quot;</span><span style="color: #9399B2;">] }</span></span> <span class="giallo-l"><span>serde</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&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;derive&quot;</span><span style="color: #9399B2;">] }</span></span> <span class="giallo-l"><span>serde_json</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&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>Set the database URL. Create a <code>.env</code> file so the macros can find it at compile time:</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;"> &#39;DATABASE_URL=sqlite:books.db&#39;</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #A6E3A1;"> .env</span></span></code></pre> <p>You can also export it in your shell (the <code>.env</code> file is the most reliable approach since it is checked before every compile):</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #CBA6F7;">export</span><span> DATABASE_URL</span><span style="color: #94E2D5;">=</span><span>sqlite:books.db</span></span></code></pre><h3 id="migration-files">Migration Files</h3> <p><code>migrations/0001_initial.sql</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">CREATE TABLE</span><span style="color: #89B4FA;font-style: italic;"> IF</span><span style="color: #CBA6F7;"> NOT EXISTS</span><span> books (</span></span> <span class="giallo-l"><span> id </span><span style="color: #CBA6F7;">INTEGER PRIMARY KEY</span><span> AUTOINCREMENT,</span></span> <span class="giallo-l"><span> title </span><span style="color: #CBA6F7;">TEXT NOT NULL</span><span>,</span></span> <span class="giallo-l"><span> author </span><span style="color: #CBA6F7;">TEXT NOT NULL</span><span>,</span></span> <span class="giallo-l"><span> genre </span><span style="color: #CBA6F7;">TEXT NOT NULL</span><span>,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> year INTEGER</span><span>,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> read INTEGER NOT NULL DEFAULT</span><span style="color: #FAB387;"> 0</span></span> <span class="giallo-l"><span>);</span></span></code></pre> <p><code>migrations/0002_add_rating.sql</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="sql"><span class="giallo-l"><span style="color: #CBA6F7;">ALTER TABLE</span><span> books </span><span style="color: #CBA6F7;">ADD</span><span> COLUMN rating </span><span style="color: #CBA6F7;">INTEGER</span><span>;</span></span></code></pre><h3 id="bootstrap-the-database">Bootstrap the Database</h3> <p>Before the macros can verify queries, the database must exist with the schema applied. Write a minimal <code>src/main.rs</code> to run migrations:</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;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">sqlite</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">SqlitePoolOptions</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;">tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">main</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> main</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;"> Box</span><span style="color: #89DCEB;">&lt;</span><span style="color: #CBA6F7;">dyn</span><span style="color: #EBA0AC;"> std</span><span style="color: #94E2D5;">::</span><span style="color: #EBA0AC;">error</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Error</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> pool</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> SqlitePoolOptions</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;">max_connections</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: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">connect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;sqlite:books.db&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">migrate!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;./migrations&quot;</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 style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;Database set up successfully.&quot;</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></code></pre> <p>Run it once:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run</span></span></code></pre> <p>Now <code>books.db</code> exists with the schema applied. Delete the temporary main and let's build the real CLI.</p> <p>(Alternatively, you can use <code>sqlx database create &amp;&amp; sqlx migrate run</code> instead of the temporary main.rs. This requires <code>sqlx-cli</code> to be installed: <code>cargo install sqlx-cli</code>.)</p> <h3 id="the-book-struct-error-type-and-display">The Book Struct, Error Type, and Display</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;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">FromRow</span><span style="color: #9399B2;">;</span></span> <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: #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> <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;"> FromRow</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Book</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> id</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> title</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> 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> genre</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> year</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> read</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> rating</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: #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;"> AppError</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;Database 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;"> Db</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;"> sqlx</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;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Migration 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;"> Migrate</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;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">migrate</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">MigrateError</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;">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> <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;JSON 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;"> Json</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;"> serde_json</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;">error</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;</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;"> Message</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> <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;"> Book</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> status</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>read </span><span style="color: #94E2D5;">!=</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;"> {</span><span style="color: #A6E3A1;"> &quot;[x]&quot;</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</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</span><span> year_str</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>year</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>y</span><span style="color: #94E2D5;">|</span><span> y</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</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 style="color: #A6E3A1;"> &quot;????&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: #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;">:3</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">. </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> by </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> <span class="giallo-l"><span> status</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>id</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>title</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>author</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>genre</span><span style="color: #9399B2;">,</span><span> year_str</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;"> if let</span><span style="color: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>r</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>rating </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;">&quot;</span><span style="color: #9399B2;">,</span><span> r</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> <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: #9399B2;">}</span></span></code></pre> <p>Now, let me explain what we just did.</p> <p><code>Book</code> has all the columns from our schema. <code>year</code> is <code>Option&lt;i64&gt;</code> because some books might not have a publication year. <code>read</code> is <code>i64</code>, SQLite stores booleans as <code>0</code>/<code>1</code> integers, and the <code>query_as!</code> macro sees <code>INTEGER</code> in the schema and requires <code>i64</code>. We treat <code>0</code> as unread and any non-zero value as read. <code>rating</code> is <code>Option&lt;i64&gt;</code> because the second migration added it later and existing rows default to <code>NULL</code>.</p> <p>Note that when you <em>bind</em> a Rust <code>bool</code> as a query parameter (e.g., in <code>mark_book</code>), SQLx's <code>Encode</code> trait converts <code>false</code> → <code>0</code> and <code>true</code> → <code>1</code> automatically. The asymmetry is that <em>reading</em> a column back must match the Rust field type, while <em>writing</em> a parameter can convert freely.</p> <p><code>AppError</code> has variants for database errors, migration errors, I/O errors, JSON parsing errors, and custom messages. The <code>#[from]</code> attributes let us use <code>?</code> on <code>sqlx::Error</code>, <code>MigrateError</code>, <code>std::io::Error</code>, and <code>serde_json::Error</code>, they auto-convert.</p> <p><code>Display</code> for <code>Book</code> uses <code>[x]</code> for read, <code>[ ]</code> for unread, and shows the year (or <code>????</code> if unknown). If a rating exists, it shows stars.</p> <h3 id="database-initialisation">Database Initialisation</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;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">sqlite</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">SqlitePool</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> SqlitePoolOptions</span><span style="color: #9399B2;">};</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> init_db</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;">SqlitePool</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</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;"> SqlitePoolOptions</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;">max_connections</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: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">connect</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;sqlite:books.db&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">migrate!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;./migrations&quot;</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 style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><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>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre><h3 id="adding-a-book">Adding a Book</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> add_book</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> pool</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">SqlitePool</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> title</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;"> author</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;"> genre</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;"> year</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 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;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;INSERT INTO books (title, author, genre, year) VALUES (?, ?, ?, ?)&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> title</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> genre</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> year</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;">execute</span><span style="color: #9399B2;">(</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;Added: </span><span style="color: #F5C2E7;">\&quot;</span><span style="color: #9399B2;">{}</span><span style="color: #F5C2E7;">\&quot;</span><span style="color: #A6E3A1;"> by </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> title</span><span style="color: #9399B2;">,</span><span> author</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></code></pre> <p>Now, let me explain what we just did.</p> <p><code>year: Option&lt;i64&gt;</code> is passed directly as a parameter. SQLx maps <code>None</code> to SQL <code>NULL</code> and <code>Some(n)</code> to the integer <code>n</code>. The <code>?</code> placeholder accepts either. The macro verifies that the type (<code>Option&lt;i64&gt;</code>) is compatible with the column type (<code>INTEGER</code>).</p> <h3 id="listing-books-with-sorting-and-pagination">Listing Books with Sorting and Pagination</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> list_books</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> pool</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">SqlitePool</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> unread_only</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: #EBA0AC;"> sort_by</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;"> descending</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: #EBA0AC;"> limit</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: #EBA0AC;"> offset</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 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;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> order_col</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> sort_by</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;year&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;year&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;rating&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;rating&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;author&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;author&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;genre&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;genre&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;id&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;"> let</span><span> direction</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if</span><span> descending</span><span style="color: #9399B2;"> {</span><span style="color: #A6E3A1;"> &quot;DESC&quot;</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span><span style="color: #A6E3A1;"> &quot;ASC&quot;</span><span style="color: #9399B2;"> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> books</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if</span><span> unread_only</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Because the SQL is built dynamically, we use the non-macro query!</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // for the WHERE clause variation. But for compile-time checking,</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // we use the macro on the base query pattern.</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Book</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;SELECT id, title, author, genre, year, read, rating FROM books WHERE read = 0 ORDER BY id&quot;</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;">fetch_all</span><span style="color: #9399B2;">(</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Book</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;SELECT id, title, author, genre, year, read, rating FROM books ORDER BY id&quot;</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;">fetch_all</span><span style="color: #9399B2;">(</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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;"> // Sorting and pagination are applied in Rust since the ORDER BY</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // and LIMIT/OFFSET vary at runtime. This is fine for CLI-scale data.</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> books</span><span style="color: #94E2D5;"> =</span><span> books</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> books</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">sort_by</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>a</span><span style="color: #9399B2;">,</span><span> b</span><span style="color: #94E2D5;">|</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> cmp</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> order_col</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;year&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span> a</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">year</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">cmp</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>b</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">year</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">then</span><span style="color: #9399B2;">(</span><span>a</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">title</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">cmp</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>b</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">title</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;rating&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span> a</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">rating</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">cmp</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>b</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">rating</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">then</span><span style="color: #9399B2;">(</span><span>a</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">title</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">cmp</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>b</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">title</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;author&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span> a</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">author</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">cmp</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>b</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">author</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">then</span><span style="color: #9399B2;">(</span><span>a</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">title</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">cmp</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>b</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">title</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;genre&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span> a</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">genre</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">cmp</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>b</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">genre</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">then</span><span style="color: #9399B2;">(</span><span>a</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">title</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">cmp</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>b</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">title</span><span style="color: #9399B2;">)),</span></span> <span class="giallo-l"><span> _</span><span style="color: #94E2D5;"> =&gt;</span><span> a</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">id</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">cmp</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>b</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">id</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> descending</span><span style="color: #9399B2;"> {</span><span> cmp</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">reverse</span><span style="color: #9399B2;">() }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span><span> cmp</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> start</span><span style="color: #94E2D5;"> =</span><span> offset</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: #CBA6F7;"> as usize</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> end</span><span style="color: #94E2D5;"> =</span><span> limit</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>l</span><span style="color: #94E2D5;">|</span><span> start</span><span style="color: #94E2D5;"> +</span><span> l</span><span style="color: #CBA6F7;"> as usize</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>books</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> page</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;">Book</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span> books</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>start</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">take</span><span style="color: #9399B2;">(</span><span>end</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">saturating_sub</span><span style="color: #9399B2;">(</span><span>start</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;"> if</span><span> page</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 books 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> book</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>page</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> book</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;"> book(s) shown (total: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">)&quot;</span><span style="color: #9399B2;">,</span><span> page</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">(),</span><span> books</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> <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>Now, let me explain what we just did.</p> <p>Dynamic sorting and pagination are tricky with compile-time checked macros because <code>ORDER BY</code> and <code>LIMIT</code> vary at runtime. One approach is to use <code>sqlx::QueryBuilder</code> for fully dynamic SQL. Another approach, which we use here, is to fetch all matching rows with a compile-time checked query and then sort and paginate in Rust. For a personal book library with hundreds or thousands of books, this is perfectly fast. For millions of rows, you would use dynamic SQL with <code>QueryBuilder</code> or separate compile-time queries for each sort order.</p> <p>The <code>.sort_by()</code> closure compares fields based on the <code>order_col</code> string. <code>Option&lt;i64&gt;</code> comparison puts <code>None</code> before <code>Some(n)</code>. For pagination, we <code>skip(offset)</code> and <code>take(limit)</code> using standard iterator methods. We show the page count and total count so the user knows where they are.</p> <p>An alternative approach which demonstrates more SQL is to build the query with <code>sqlx::query_as</code> (runtime-checked, not compile-time checked) and string interpolation for the <code>ORDER BY</code> and <code>LIMIT</code> clauses. But the parameters must still be bound through placeholders, never string-interpolated:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>// Example of dynamic ORDER BY using runtime query (no compile-time check on sort column):</span></span> <span class="giallo-l"><span>let query_str = format!(</span></span> <span class="giallo-l"><span> &quot;SELECT id, title, author, genre, year, read, rating FROM books ORDER BY {} {} LIMIT ? OFFSET ?&quot;,</span></span> <span class="giallo-l"><span> order_col, direction</span></span> <span class="giallo-l"><span>);</span></span> <span class="giallo-l"><span>// This loses compile-time checking for the ORDER BY clause.</span></span> <span class="giallo-l"><span>// For a learning project, sorting in Rust is simpler and safer.</span></span></code></pre> <p>We will stick with sorting in Rust for clarity.</p> <h3 id="searching-books">Searching Books</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> search_books</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">pool</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">SqlitePool</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> query</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;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> pattern</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> query</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> books</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Book</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;SELECT id, title, author, genre, year, read, rating FROM books</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> WHERE title LIKE ? OR author LIKE ? OR genre LIKE ?</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> ORDER BY id&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> pattern</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> pattern</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> pattern</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;">fetch_all</span><span style="color: #9399B2;">(</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> if</span><span> books</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 books matching </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> query</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> book</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>books</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> book</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;"> book(s) found&quot;</span><span style="color: #9399B2;">,</span><span> books</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> <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>Now, let me explain what we just did.</p> <p><code>LIKE</code> with <code>%query%</code> does a substring search across title, author, and genre. All three columns use the same pattern. The macro checks that three <code>?</code> placeholders match three parameters. This is the same <code>LIKE</code> we practiced in Part 1.</p> <h3 id="searching-by-author-or-genre">Searching by Author or Genre</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> search_by_author</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">pool</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">SqlitePool</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> author</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;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> pattern</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> author</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> books</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Book</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;SELECT id, title, author, genre, year, read, rating FROM books WHERE author LIKE ? ORDER BY year DESC&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> pattern</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;">fetch_all</span><span style="color: #9399B2;">(</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> if</span><span> books</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 books by author matching </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> author</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> book</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>books</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> book</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;"> book(s) found&quot;</span><span style="color: #9399B2;">,</span><span> books</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> <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> <span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> search_by_genre</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">pool</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">SqlitePool</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> genre</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;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> pattern</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> genre</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> books</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_as!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Book</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;SELECT id, title, author, genre, year, read, rating FROM books WHERE genre LIKE ? ORDER BY year DESC&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> pattern</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;">fetch_all</span><span style="color: #9399B2;">(</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> if</span><span> books</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 books in genre matching </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> genre</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> book</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>books</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> book</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;"> book(s) found&quot;</span><span style="color: #9399B2;">,</span><span> books</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> <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>The search by author and genre both sort by year descending, newest first. This is useful: when you browse an author's work, you typically want to see their latest book first.</p> <h3 id="getting-genre-statistics-with-group-by">Getting Genre Statistics with GROUP BY</h3> <p>This is where we use the SQL we learned in Part 1 to build a useful feature:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> genre_stats</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">pool</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">SqlitePool</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;"> AppError</span><span style="color: #89DCEB;">&gt;</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;">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;"> GenreStat</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> genre</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> total</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> read_count</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> avg_rating</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;">f64</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;"> let</span><span> rows</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;SELECT</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> genre,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> COUNT(*) as total,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> SUM(read) as read_count,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> AVG(CAST(rating AS REAL)) as avg_rating</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> FROM books</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> GROUP BY genre</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> ORDER BY total DESC, genre ASC&quot;</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;">fetch_all</span><span style="color: #9399B2;">(</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> if</span><span> rows</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 books in the library.&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> <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;">:&lt;20</span><span style="color: #9399B2;">} {</span><span style="color: #A6E3A1;">:&gt;6</span><span style="color: #9399B2;">} {</span><span style="color: #A6E3A1;">:&gt;6</span><span style="color: #9399B2;">} {</span><span style="color: #A6E3A1;">:&gt;10</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Genre&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Books&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Read&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Avg Rating&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 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;">46</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> row</span><span style="color: #CBA6F7;"> in</span><span> rows</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> avg</span><span style="color: #94E2D5;"> =</span><span> row</span><span style="color: #94E2D5;">.</span><span>avg_rating</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>r</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;">:.1</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: #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: #A6E3A1;"> &quot; -&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: #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;">:&lt;20</span><span style="color: #9399B2;">} {</span><span style="color: #A6E3A1;">:&gt;6</span><span style="color: #9399B2;">} {</span><span style="color: #A6E3A1;">:&gt;6</span><span style="color: #9399B2;">} {</span><span style="color: #A6E3A1;">:&gt;10</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> row</span><span style="color: #94E2D5;">.</span><span>genre</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> row</span><span style="color: #94E2D5;">.</span><span>total</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> row</span><span style="color: #94E2D5;">.</span><span>read_count</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> avg</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;"> Ok</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>This query uses <code>GROUP BY genre</code> with three aggregate functions: <code>COUNT(*)</code> for total books, <code>SUM(read)</code> for read books (summing 0s and 1s), and <code>AVG(CAST(rating AS REAL))</code> for the average rating. The <code>CAST(rating AS REAL)</code> is needed because <code>AVG</code> on an <code>INTEGER</code> column causes the sqlx macro to infer <code>Option&lt;i64&gt;</code> instead of <code>Option&lt;f64&gt;</code>, which leads to wrong formatting (no decimal places) or a runtime type mismatch crash. <code>ORDER BY total DESC, genre ASC</code> puts the most popular genres first and breaks ties alphabetically.</p> <p><code>query!</code> generates an anonymous struct. We access fields as <code>row.genre</code>, <code>row.total</code>, etc. <code>row.read_count</code> is <code>i64</code> (not optional) because sqlx infers <code>SUM(read)</code> on a <code>NOT NULL</code> column as non-nullable over a non-empty group. No <code>.unwrap_or(0)</code> needed. <code>row.avg_rating</code> is <code>Option&lt;f64&gt;</code>, <code>AVG</code> can return <code>NULL</code> when there are no ratings. We format it to one decimal place or show <code>-</code> if no ratings exist.</p> <h3 id="showing-author-statistics">Showing Author Statistics</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> author_stats</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">pool</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">SqlitePool</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;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> rows</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;SELECT</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> author,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> COUNT(*) as total,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> SUM(read) as read_count,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> MIN(year) as first_published,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> MAX(year) as latest_published</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> FROM books</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> GROUP BY author</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> HAVING total &gt; 0</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> ORDER BY total DESC, author ASC&quot;</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;">fetch_all</span><span style="color: #9399B2;">(</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> if</span><span> rows</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 books in the library.&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> <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;">:&lt;20</span><span style="color: #9399B2;">} {</span><span style="color: #A6E3A1;">:&gt;6</span><span style="color: #9399B2;">} {</span><span style="color: #A6E3A1;">:&gt;6</span><span style="color: #9399B2;">} {</span><span style="color: #A6E3A1;">:&gt;14</span><span style="color: #9399B2;">} {</span><span style="color: #A6E3A1;">:&gt;14</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Author&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Books&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Read&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;First Pub&quot;</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Latest Pub&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 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;">66</span><span style="color: #9399B2;">));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> row</span><span style="color: #CBA6F7;"> in</span><span> rows</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> first</span><span style="color: #94E2D5;"> =</span><span> row</span><span style="color: #94E2D5;">.</span><span>first_published</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>y</span><span style="color: #94E2D5;">|</span><span> y</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</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 style="color: #A6E3A1;"> &quot; ?&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: #CBA6F7;"> let</span><span> latest</span><span style="color: #94E2D5;"> =</span><span> row</span><span style="color: #94E2D5;">.</span><span>latest_published</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>y</span><span style="color: #94E2D5;">|</span><span> y</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</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 style="color: #A6E3A1;"> &quot; ?&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: #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;">:&lt;20</span><span style="color: #9399B2;">} {</span><span style="color: #A6E3A1;">:&gt;6</span><span style="color: #9399B2;">} {</span><span style="color: #A6E3A1;">:&gt;6</span><span style="color: #9399B2;">} {</span><span style="color: #A6E3A1;">:&gt;14</span><span style="color: #9399B2;">} {</span><span style="color: #A6E3A1;">:&gt;14</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> row</span><span style="color: #94E2D5;">.</span><span>author</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">as_deref</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> row</span><span style="color: #94E2D5;">.</span><span>total</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> row</span><span style="color: #94E2D5;">.</span><span>read_count</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> first</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> latest</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;"> Ok</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>GROUP BY author</code> with <code>MIN(year)</code> and <code>MAX(year)</code> shows the span of each author's work. This uses <code>HAVING total &gt; 0</code> even though it is redundant (no author has 0 books because they are grouped from the books table). I include it to show the <code>HAVING</code> syntax in a real query. <code>MIN</code> and <code>MAX</code> on <code>year</code> (which is <code>INTEGER</code>) return the earliest and latest publication years. If all <code>year</code> values are <code>NULL</code>, they return <code>NULL</code>.</p> <h3 id="marking-books-rating-and-deleting">Marking Books, Rating, and Deleting</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> mark_book</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">pool</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">SqlitePool</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> id</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> read</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;"> Result</span><span style="color: #89DCEB;">&lt;</span><span style="color: #9399B2;">(),</span><span style="color: #F9E2AF;font-style: italic;"> AppError</span><span style="color: #89DCEB;">&gt;</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;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;UPDATE books SET read = ? WHERE id = ?&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> read</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> id</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;">execute</span><span style="color: #9399B2;">(</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> if</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">rows_affected</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: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;No book found with ID </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">.&quot;</span><span style="color: #9399B2;">,</span><span> id</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> status</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> if</span><span> read</span><span style="color: #9399B2;"> {</span><span style="color: #A6E3A1;"> &quot;read&quot;</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</span><span style="color: #9399B2;"> {</span><span style="color: #A6E3A1;"> &quot;unread&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;Marked book </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> as </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">.&quot;</span><span style="color: #9399B2;">,</span><span> id</span><span style="color: #9399B2;">,</span><span> status</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> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> rate_book</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">pool</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">SqlitePool</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> id</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> rating</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</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;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> rating</span><span style="color: #94E2D5;"> &lt;</span><span style="color: #FAB387;"> 1</span><span style="color: #94E2D5;"> ||</span><span> rating</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: #CBA6F7;"> return</span><span style="color: #F9E2AF;font-style: italic;"> Err</span><span style="color: #9399B2;">(</span><span style="color: #F9E2AF;font-style: italic;">AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Message</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Rating must be between 1 and 5.&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> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> result</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;UPDATE books SET rating = ? WHERE id = ?&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> rating</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> id</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;">execute</span><span style="color: #9399B2;">(</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> if</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">rows_affected</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: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;No book found with ID </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">.&quot;</span><span style="color: #9399B2;">,</span><span> id</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;Rated book </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> with </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> stars.&quot;</span><span style="color: #9399B2;">,</span><span> id</span><span style="color: #9399B2;">,</span><span> rating</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> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> delete_book</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">pool</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">SqlitePool</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> id</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</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;"> AppError</span><span style="color: #89DCEB;">&gt;</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;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;DELETE FROM books WHERE id = ?&quot;</span><span style="color: #9399B2;">,</span><span> id</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">execute</span><span style="color: #9399B2;">(</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> if</span><span> result</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">rows_affected</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: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;No book found with ID </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">.&quot;</span><span style="color: #9399B2;">,</span><span> id</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;Deleted book </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">.&quot;</span><span style="color: #9399B2;">,</span><span> id</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><code>rows_affected()</code> tells us whether any row was actually updated or deleted. If the ID does not exist, we get <code>0</code> and print a message.</p> <h3 id="counting-with-query-scalar">Counting with query_scalar!</h3> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> show_counts</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">pool</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">SqlitePool</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;"> AppError</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> total</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_scalar!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;SELECT COUNT(*) as count FROM books&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">fetch_one</span><span style="color: #9399B2;">(</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> let</span><span> read_count</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_scalar!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;SELECT COUNT(*) as count FROM books WHERE read = 1&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">fetch_one</span><span style="color: #9399B2;">(</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> let</span><span> has_ratings</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_scalar!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;SELECT COUNT(*) as count FROM books WHERE rating IS NOT NULL&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">fetch_one</span><span style="color: #9399B2;">(</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;"> let</span><span> avg_rating</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query_scalar!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;SELECT AVG(CAST(rating AS REAL)) as avg_rating FROM books WHERE rating IS NOT NULL&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">fetch_one</span><span style="color: #9399B2;">(</span><span>pool</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</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;Total books: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> total</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;Read: </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> read_count</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> total</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;"> { (</span><span>read_count</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> 100</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> /</span><span> total</span><span style="color: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</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: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Unread: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> total</span><span style="color: #94E2D5;"> -</span><span> read_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;With ratings: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> has_ratings</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>avg</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> avg_rating</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;Average rating: </span><span style="color: #9399B2;">{</span><span style="color: #A6E3A1;">:.1</span><span style="color: #9399B2;">}</span><span style="color: #A6E3A1;"> / 5&quot;</span><span style="color: #9399B2;">,</span><span> avg</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>Now, let me explain what we just did.</p> <p>Four separate <code>query_scalar!</code> calls. <code>COUNT(*)</code> never returns <code>NULL</code> in SQL, so the macro infers <code>i64</code> directly, not <code>Option&lt;i64&gt;</code>. We do <strong>not</strong> call <code>.unwrap_or(0)</code> because the type is already <code>i64</code>.</p> <p><code>AVG(CAST(rating AS REAL))</code> uses <code>CAST</code> because without it, sqlx infers <code>AVG(rating)</code> on an <code>INTEGER</code> column as <code>Option&lt;i64&gt;</code> (it reasons from the input column type rather than the SQL return type of <code>AVG</code>). At runtime, SQLite returns a <code>REAL</code> value, causing a type mismatch crash. With <code>CAST</code>, sqlx infers <code>Option&lt;f64&gt;</code> correctly, and we handle it with <code>if let Some(avg)</code>.</p> <h3 id="bulk-import-with-transactions">Bulk Import with Transactions</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;"> serde</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Deserialize</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;">Deserialize</span><span style="color: #9399B2;">)]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">struct</span><span style="color: #F9E2AF;font-style: italic;"> BookImport</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> title</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> 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> genre</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> year</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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> import_books</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">pool</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">SqlitePool</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> file_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;"> AppError</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;"> tokio</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>file_path</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> imports</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;">BookImport</span><span style="color: #89DCEB;">&gt;</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> serde_json</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>content</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">map_err</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>e</span><span style="color: #94E2D5;">|</span><span style="color: #F9E2AF;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Message</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid JSON: </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 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;Importing </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> books...&quot;</span><span style="color: #9399B2;">,</span><span> imports</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 mut</span><span> tx</span><span style="color: #94E2D5;"> =</span><span> pool</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">begin</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;"> for</span><span style="color: #9399B2;"> (</span><span>i</span><span style="color: #9399B2;">,</span><span> book</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span> imports</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: #F9E2AF;"> sqlx</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">query!</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;INSERT INTO books (title, author, genre, year) VALUES (?, ?, ?, ?)&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> book</span><span style="color: #94E2D5;">.</span><span>title</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> book</span><span style="color: #94E2D5;">.</span><span>author</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> book</span><span style="color: #94E2D5;">.</span><span>genre</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> book</span><span style="color: #94E2D5;">.</span><span>year</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;">execute</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #94E2D5;"> *</span><span>tx</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #CBA6F7;">await</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">map_err</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>e</span><span style="color: #94E2D5;">|</span><span style="color: #F9E2AF;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Message</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">format!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Row </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> i</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 1</span><span style="color: #9399B2;">,</span><span> e</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> <span class="giallo-l"></span> <span class="giallo-l"><span> tx</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">commit</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;Successfully imported </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;"> books.&quot;</span><span style="color: #9399B2;">,</span><span> imports</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;"> Ok</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>pool.begin().await?</code> starts a transaction. Inside the loop, we pass <code>&amp;mut *tx</code> to <code>.execute()</code>, this tells SQLx to run within the transaction. If any insert fails, the <code>?</code> returns early, the <code>Transaction</code> is dropped before commit, and SQLx automatically rolls back. <code>tx.commit().await?</code> makes all inserts permanent.</p> <p>The error is wrapped with the row number for debugging. If row 42 has a typo in the JSON, the error tells you exactly which row.</p> <h3 id="cli-parsing">CLI Parsing</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>env</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">async 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;"> AppError</span><span style="color: #89DCEB;">&gt;</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: #89B4FA;font-style: italic;"> init_db</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;"> 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> <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;"> 2</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> print_usage</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> <span class="giallo-l"><span style="color: #CBA6F7;"> match</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;">as_str</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;add&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <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;"> 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;Usage: cargo run -- add &lt;title&gt; &lt;author&gt; &lt;genre&gt; [year]&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: #CBA6F7;"> let</span><span> year</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: #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;"> 5</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>args</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: #89B4FA;font-style: italic;">parse</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">map_err</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>_</span><span style="color: #94E2D5;">|</span><span style="color: #F9E2AF;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Message</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid year.&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</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 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: #89B4FA;font-style: italic;"> add_book</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>args</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">2</span><span style="color: #9399B2;">],</span><span style="color: #94E2D5;"> &amp;</span><span>args</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">],</span><span style="color: #94E2D5;"> &amp;</span><span>args</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">4</span><span style="color: #9399B2;">],</span><span> year</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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;list&quot;</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> unread_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> sort_by</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;id&quot;</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> descending</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> limit</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> offset</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;"> let mut</span><span> i</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;"> while</span><span> i</span><span style="color: #94E2D5;"> &lt;</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;--unread&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span> unread_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;--sort&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><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: #CBA6F7;"> if</span><span> i</span><span style="color: #94E2D5;"> &lt;</span><span> args</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">() {</span><span> sort_by</span><span style="color: #94E2D5;"> = &amp;</span><span>args</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;"> &quot;--desc&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span> descending</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;--limit&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><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: #CBA6F7;"> if</span><span> i</span><span style="color: #94E2D5;"> &lt;</span><span> args</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">() {</span><span> limit</span><span style="color: #94E2D5;"> =</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;">parse</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: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;--offset&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><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: #CBA6F7;"> if</span><span> i</span><span style="color: #94E2D5;"> &lt;</span><span> args</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">len</span><span style="color: #9399B2;">() {</span><span> offset</span><span style="color: #94E2D5;"> =</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;">parse</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: #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> 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: #89B4FA;font-style: italic;"> list_books</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">,</span><span> unread_only</span><span style="color: #9399B2;">,</span><span> sort_by</span><span style="color: #9399B2;">,</span><span> descending</span><span style="color: #9399B2;">,</span><span> limit</span><span style="color: #9399B2;">,</span><span> offset</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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;search&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <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: #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;Usage: cargo run -- search &lt;query&gt;&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: #89B4FA;font-style: italic;"> search_books</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</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: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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;search-author&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <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: #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;Usage: cargo run -- search-author &lt;author&gt;&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: #89B4FA;font-style: italic;"> search_by_author</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</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: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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;search-genre&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <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: #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;Usage: cargo run -- search-genre &lt;genre&gt;&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: #89B4FA;font-style: italic;"> search_by_genre</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</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: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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;read&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <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: #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;Usage: cargo run -- read &lt;id&gt;&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: #CBA6F7;"> let</span><span> id</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #94E2D5;"> =</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;">parse</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">map_err</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>_</span><span style="color: #94E2D5;">|</span><span style="color: #F9E2AF;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Message</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid ID.&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</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;"> mark_book</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">,</span><span> id</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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;unread&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <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: #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;Usage: cargo run -- unread &lt;id&gt;&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: #CBA6F7;"> let</span><span> id</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #94E2D5;"> =</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;">parse</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">map_err</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>_</span><span style="color: #94E2D5;">|</span><span style="color: #F9E2AF;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Message</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid ID.&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</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;"> mark_book</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">,</span><span> id</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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;rate&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <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: #94E2D5;"> !=</span><span style="color: #FAB387;"> 4</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: cargo run -- rate &lt;id&gt; &lt;1-5&gt;&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: #CBA6F7;"> let</span><span> id</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #94E2D5;"> =</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;">parse</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">map_err</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>_</span><span style="color: #94E2D5;">|</span><span style="color: #F9E2AF;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Message</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid ID.&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</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> rating</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #94E2D5;"> =</span><span> args</span><span style="color: #9399B2;">[</span><span style="color: #FAB387;">3</span><span style="color: #9399B2;">]</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">parse</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">map_err</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>_</span><span style="color: #94E2D5;">|</span><span style="color: #F9E2AF;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Message</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid rating.&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</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;"> rate_book</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">,</span><span> id</span><span style="color: #9399B2;">,</span><span> rating</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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;delete&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <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: #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;Usage: cargo run -- delete &lt;id&gt;&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: #CBA6F7;"> let</span><span> id</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i64</span><span style="color: #94E2D5;"> =</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;">parse</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">map_err</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">|</span><span>_</span><span style="color: #94E2D5;">|</span><span style="color: #F9E2AF;"> AppError</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">Message</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Invalid ID.&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</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;"> delete_book</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">,</span><span> id</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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;import&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <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: #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;Usage: cargo run -- import &lt;file.json&gt;&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: #89B4FA;font-style: italic;"> import_books</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</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: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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;genres&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> genre_stats</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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;authors&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> author_stats</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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;stats&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> show_counts</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>pool</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">?</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;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Unknown command: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><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> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> print_usage</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;"> Ok</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;"> print_usage</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;Book Library CLI&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;Commands:&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; add &lt;title&gt; &lt;author&gt; &lt;genre&gt; [year]&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; Add a new book&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; list [--unread] [--sort &lt;col&gt;] [--desc] [--limit N] [--offset N]&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; List books with optional filters&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; search &lt;query&gt; Search by title, author, or genre&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; search-author &lt;author&gt; Search by author&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; search-genre &lt;genre&gt; Search by genre&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; read &lt;id&gt; Mark a book as read&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; unread &lt;id&gt; Mark a book as unread&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; rate &lt;id&gt; &lt;1-5&gt; Rate a book (1-5 stars)&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; delete &lt;id&gt; Delete a book&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; import &lt;file.json&gt; Import books from a JSON array&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; genres Show genre statistics (GROUP BY)&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; authors Show author 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; stats Show library summary&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: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">main</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">async 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 style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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.</p> <p>The CLI has grown from previous projects. The <code>list</code> command supports <code>--sort</code> (by <code>id</code>, <code>title</code>, <code>author</code>, <code>genre</code>, <code>year</code>, <code>rating</code>), <code>--desc</code>, <code>--unread</code>, and <code>--limit</code>/<code>--offset</code> for pagination. The <code>genres</code> and <code>authors</code> commands give us statistical views of the library using the <code>GROUP BY</code> queries we practiced in Part 1. The <code>stats</code> command gives an overview. The <code>add</code> command accepts an optional year. The <code>import</code> command reads JSON arrays with transactions.</p> <h3 id="running-the-project">Running the Project</h3> <p>Make sure <code>DATABASE_URL</code> is set before compiling:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>export DATABASE_URL=sqlite:books.db</span></span></code></pre> <p>Add some books:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run -- add &quot;The Rust Programming Language&quot; &quot;Steve Klabnik&quot; &quot;Programming&quot; 2018</span></span> <span class="giallo-l"><span>cargo run -- add &quot;Project Hail Mary&quot; &quot;Andy Weir&quot; &quot;Science Fiction&quot; 2021</span></span> <span class="giallo-l"><span>cargo run -- add &quot;The Martian&quot; &quot;Andy Weir&quot; &quot;Science Fiction&quot; 2011</span></span> <span class="giallo-l"><span>cargo run -- add &quot;Atomic Habits&quot; &quot;James Clear&quot; &quot;Self-Help&quot; 2018</span></span> <span class="giallo-l"><span>cargo run -- add &quot;Dune&quot; &quot;Frank Herbert&quot; &quot;Science Fiction&quot; 1965</span></span> <span class="giallo-l"><span>cargo run -- add &quot;Neuromancer&quot; &quot;William Gibson&quot; &quot;Cyberpunk&quot; 1984</span></span> <span class="giallo-l"><span>cargo run -- add &quot;Snow Crash&quot; &quot;Neal Stephenson&quot; &quot;Cyberpunk&quot; 1992</span></span> <span class="giallo-l"><span>cargo run -- add &quot;The Name of the Wind&quot; &quot;Patrick Rothfuss&quot; &quot;Fantasy&quot; 2007</span></span> <span class="giallo-l"><span>cargo run -- add &quot;A Wise Mans Fear&quot; &quot;Patrick Rothfuss&quot; &quot;Fantasy&quot; 2011</span></span> <span class="giallo-l"><span>cargo run -- add &quot;Deep Work&quot; &quot;Cal Newport&quot; &quot;Self-Help&quot; 2016</span></span></code></pre> <p>List all books:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run -- list</span></span></code></pre> <p>Expected output:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>[ ] 1. The Rust Programming Language by Steve Klabnik (Programming) [2018]</span></span> <span class="giallo-l"><span>[ ] 2. Project Hail Mary by Andy Weir (Science Fiction) [2021]</span></span> <span class="giallo-l"><span>[ ] 3. The Martian by Andy Weir (Science Fiction) [2011]</span></span> <span class="giallo-l"><span>[ ] 4. Atomic Habits by James Clear (Self-Help) [2018]</span></span> <span class="giallo-l"><span>[ ] 5. Dune by Frank Herbert (Science Fiction) [1965]</span></span> <span class="giallo-l"><span>[ ] 6. Neuromancer by William Gibson (Cyberpunk) [1984]</span></span> <span class="giallo-l"><span>[ ] 7. Snow Crash by Neal Stephenson (Cyberpunk) [1992]</span></span> <span class="giallo-l"><span>[ ] 8. The Name of the Wind by Patrick Rothfuss (Fantasy) [2007]</span></span> <span class="giallo-l"><span>[ ] 9. A Wise Mans Fear by Patrick Rothfuss (Fantasy) [2011]</span></span> <span class="giallo-l"><span>[ ] 10. Deep Work by Cal Newport (Self-Help) [2016]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>10 book(s) shown (total: 10)</span></span></code></pre> <p>List with sorting and pagination:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run -- list --sort year --desc --limit 3</span></span></code></pre> <p>Expected output (3 most recent books):</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>[ ] 2. Project Hail Mary by Andy Weir (Science Fiction) [2021]</span></span> <span class="giallo-l"><span>[ ] 1. The Rust Programming Language by Steve Klabnik (Programming) [2018]</span></span> <span class="giallo-l"><span>[ ] 4. Atomic Habits by James Clear (Self-Help) [2018]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>3 book(s) shown (total: 10)</span></span></code></pre> <p>Search:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run -- search &quot;Science Fiction&quot;</span></span></code></pre> <p>Expected output:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>[ ] 2. Project Hail Mary by Andy Weir (Science Fiction) [2021]</span></span> <span class="giallo-l"><span>[ ] 3. The Martian by Andy Weir (Science Fiction) [2011]</span></span> <span class="giallo-l"><span>[ ] 5. Dune by Frank Herbert (Science Fiction) [1965]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>3 book(s) found</span></span></code></pre> <p>Mark books as read and rate them:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run -- read 1</span></span> <span class="giallo-l"><span>cargo run -- read 3</span></span> <span class="giallo-l"><span>cargo run -- read 5</span></span> <span class="giallo-l"><span>cargo run -- rate 1 5</span></span> <span class="giallo-l"><span>cargo run -- rate 3 4</span></span> <span class="giallo-l"><span>cargo run -- rate 5 5</span></span></code></pre> <p>View genre statistics (the GROUP BY query):</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run -- genres</span></span></code></pre> <p>Expected output:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>Genre Books Read Avg Rating</span></span> <span class="giallo-l"><span>----------------------------------------------</span></span> <span class="giallo-l"><span>Science Fiction 3 2 4.5</span></span> <span class="giallo-l"><span>Cyberpunk 2 0 -</span></span> <span class="giallo-l"><span>Fantasy 2 0 -</span></span> <span class="giallo-l"><span>Self-Help 2 0 -</span></span> <span class="giallo-l"><span>Programming 1 1 5.0</span></span></code></pre> <p>View author statistics (MIN and MAX years):</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run -- authors</span></span></code></pre> <p>Expected output:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>Author Books Read First Pub Latest Pub</span></span> <span class="giallo-l"><span>------------------------------------------------------------------</span></span> <span class="giallo-l"><span>Andy Weir 2 1 2011 2021</span></span> <span class="giallo-l"><span>Patrick Rothfuss 2 0 2007 2011</span></span> <span class="giallo-l"><span>Cal Newport 1 0 2016 2016</span></span> <span class="giallo-l"><span>Frank Herbert 1 1 1965 1965</span></span> <span class="giallo-l"><span>James Clear 1 0 2018 2018</span></span> <span class="giallo-l"><span>Neal Stephenson 1 0 1992 1992</span></span> <span class="giallo-l"><span>Steve Klabnik 1 1 2018 2018</span></span> <span class="giallo-l"><span>William Gibson 1 0 1984 1984</span></span></code></pre> <p>View overall stats:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run -- stats</span></span></code></pre> <p>Expected output:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>Total books: 10</span></span> <span class="giallo-l"><span>Read: 3 (30%)</span></span> <span class="giallo-l"><span>Unread: 7</span></span> <span class="giallo-l"><span>With ratings: 3</span></span> <span class="giallo-l"><span>Average rating: 4.7 / 5</span></span></code></pre><h3 id="bulk-import-with-a-json-file">Bulk Import with a JSON File</h3> <p>Create <code>more_books.json</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>[</span></span> <span class="giallo-l"><span> { &quot;title&quot;: &quot;Foundation&quot;, &quot;author&quot;: &quot;Isaac Asimov&quot;, &quot;genre&quot;: &quot;Science Fiction&quot;, &quot;year&quot;: 1951 },</span></span> <span class="giallo-l"><span> { &quot;title&quot;: &quot;Hyperion&quot;, &quot;author&quot;: &quot;Dan Simmons&quot;, &quot;genre&quot;: &quot;Science Fiction&quot;, &quot;year&quot;: 1989 },</span></span> <span class="giallo-l"><span> { &quot;title&quot;: &quot;The Hobbit&quot;, &quot;author&quot;: &quot;J.R.R. Tolkien&quot;, &quot;genre&quot;: &quot;Fantasy&quot;, &quot;year&quot;: 1937 }</span></span> <span class="giallo-l"><span>]</span></span></code></pre> <p>Import:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run -- import more_books.json</span></span></code></pre> <p>Expected output:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>Importing 3 books...</span></span> <span class="giallo-l"><span>Successfully imported 3 books.</span></span></code></pre><h3 id="pagination-in-action">Pagination in Action</h3> <p>After importing, we have 13 books. Paginate through them:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run -- list --sort year --limit 5 --offset 0</span></span></code></pre> <p>Output shows the 5 oldest books. Then:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run -- list --sort year --limit 5 --offset 5</span></span></code></pre> <p>Output shows books 6–10. Then:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>cargo run -- list --sort year --limit 5 --offset 10</span></span></code></pre> <p>Output shows the remaining 3.</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="plain"><span class="giallo-l"><span>13 book(s) shown (total: 13)</span></span></code></pre><h2 id="conclusion">Conclusion</h2> <p>You now know enough SQL to build real applications with Rust. We covered table creation, querying, filtering, joins, aggregation, transactions, indexes, and then used SQLx to integrate those concepts into a complete CLI application with compile-time checked queries.</p> <p>In the next article, we'll revisit this project from a different perspective. Instead of focusing on SQL and SQLx, we'll design the database itself, starting from requirements, modeling relationships, normalizing the schema, choosing constraints and indexes, and implementing the final design using both SQL and SQLx. See you soon.</p> Thu, 18 Jun 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/build-breakout-in-bevy-step-by-step/ https://blog.sheerluck.dev/posts/build-breakout-in-bevy-step-by-step/ <p>In this post, we are going to build <strong>Breakout</strong>, the classic arcade game where you control a paddle, bounce a ball, and destroy a grid of bricks. If you have been following the series from Pong and Snake, you already know the ECS basics, queries, resources, timers, and game states. Now we put it all together into a complete game with particles, lives, and a proper game over loop.</p> <p>We will build the game incrementally. After every section, you can <code>cargo run</code> and see something new on screen. This article won't teach you anything new, the motive of this article is to reinforce what you learnt in the previous 2 articles of this series.</p> <p>Get the full source code from <a rel="external" href="https://github.com/MrSheerluck/breakout-bevy">here</a>.</p> <p><img src="/images/breakout-still-image.png" alt="breakout-still-image" /></p> <h3 id="what-we-are-building">What We Are Building</h3> <p>If you have not played Breakout before, here is how it works. A paddle sits near the bottom of the screen. A ball bounces around the play area. Bricks are arranged in rows at the top. Your goal is to destroy all the bricks by bouncing the ball into them. If the ball falls past the paddle, you lose a life. Lose all three lives and it is game over.</p> <p>We will build this using colored rectangles for everything, no sprite sheets or image files needed. The bricks will have different colors per row. The ball will leave a particle burst every time it destroys a brick. Score and lives will be displayed as text.</p> <h3 id="1-a-window-on-screen">1. A Window on Screen</h3> <p>Open your terminal and create a new Rust 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 bevy_breakout</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> bevy_breakout</span></span></code></pre> <p>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_breakout&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> for randomizing particle directions later. The <code>wav</code> feature enables Bevy audio support for the future.</p> <p>Now open <code>src/main.rs</code> and write our first version, a window with a dark background, nothing else yet:</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;"> bevy</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">window</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">WindowResolution</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;"> WINDOW_WIDTH</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 800</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;"> WINDOW_HEIGHT</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 600</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;">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;Breakout&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;"> 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;">WINDOW_WIDTH</span><span style="color: #CBA6F7;"> as u32</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> WINDOW_HEIGHT</span><span style="color: #CBA6F7;"> as u32</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;">05</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">05</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">08</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>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 should see a dark 800×600 window titled "Breakout". Nothing moves yet but it compiles and runs, which means Bevy is set up correctly. Now we add the paddle.</p> <h3 id="2-the-paddle">2. The Paddle</h3> <p>We need a paddle that the player can move left and right. Add these constants and the <code>Paddle</code> marker component <strong>above</strong> <code>fn main()</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">const</span><span style="color: #FAB387;"> PADDLE_WIDTH</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</span><span style="color: #94E2D5;"> =</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: #CBA6F7;">const</span><span style="color: #FAB387;"> PADDLE_HEIGHT</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 16</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;"> PADDLE_SPEED</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 600</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;"> PADDLE_Y</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</span><span style="color: #94E2D5;"> = -</span><span style="color: #FAB387;">250</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: #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></code></pre> <p>Now add the <code>setup</code> function that spawns the camera and the paddle, and the <code>move_paddle</code> system that handles keyboard input. Place both above <code>fn 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;"> 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> 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> <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;">6</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;"> 1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</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;">PADDLE_WIDTH</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> PADDLE_HEIGHT</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;"> PADDLE_Y</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> <span class="giallo-l"></span> <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: #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;"> 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;">Paddle</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 mut</span><span> transform</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 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> <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;">ArrowLeft</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> ||</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;">KeyA</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><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: #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;">ArrowRight</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> ||</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;">KeyD</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><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> <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> direction</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> PADDLE_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> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> half_width</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> WINDOW_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 style="color: #CBA6F7;"> let</span><span> half_paddle</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> PADDLE_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> transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">=</span><span> transform</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span>translation</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span>x</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">clamp</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">-</span><span>half_width</span><span style="color: #94E2D5;"> +</span><span> half_paddle</span><span style="color: #9399B2;">,</span><span> half_width</span><span style="color: #94E2D5;"> -</span><span> half_paddle</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>clamp</code> call keeps the paddle from going off-screen. Now update <code>main()</code> to register these systems. Replace your current <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: #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;Breakout&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;"> 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;">WINDOW_WIDTH</span><span style="color: #CBA6F7;"> as u32</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> WINDOW_HEIGHT</span><span style="color: #CBA6F7;"> as u32</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;">05</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">05</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">08</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: #F9E2AF;font-style: italic;">Update</span><span style="color: #9399B2;">,</span><span> move_paddle</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>Run <code>cargo run</code>. You should see a light blue paddle near the bottom of the screen. Press Left/Right arrow keys or A/D to move it. The paddle stays within the window bounds.</p> <h3 id="3-ball-and-walls">3. Ball and Walls</h3> <p>Now we add a ball that moves on its own and bounces off walls. We will also introduce <code>GameState</code> even though we only have one state for now, it sets us up for the game over flow later.</p> <p>Add these constants and the <code>Ball</code> component above <code>fn setup()</code>:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">const</span><span style="color: #FAB387;"> BALL_SIZE</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 12</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;"> BALL_SPEED</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</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> <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;"> Vec2</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Add the game state enum, for now it only has <code>Playing</code>:</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: #9399B2;">}</span></span></code></pre> <p>Now update <code>setup()</code> to spawn the walls and the ball. Replace your entire <code>setup()</code> function 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;"> 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;"> // Walls</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> wall_thickness</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 style="color: #CBA6F7;"> let</span><span> wall_color</span><span style="color: #94E2D5;"> =</span><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;">3</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: #FAB387;"> 0</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: #9399B2;font-style: italic;"> // Left wall</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;"> Sprite</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_color</span><span style="color: #9399B2;">(</span><span>wall_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;">new</span><span style="color: #9399B2;">(</span><span>wall_thickness</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> WINDOW_HEIGHT</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 200</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;">WINDOW_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: #94E2D5;"> -</span><span> wall_thickness</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 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;">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;font-style: italic;"> // Right wall</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;"> Sprite</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_color</span><span style="color: #9399B2;">(</span><span>wall_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;">new</span><span style="color: #9399B2;">(</span><span>wall_thickness</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> WINDOW_HEIGHT</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 200</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;">WINDOW_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: #94E2D5;"> +</span><span> wall_thickness</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 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;">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;font-style: italic;"> // Top wall</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;"> Sprite</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_color</span><span style="color: #9399B2;">(</span><span>wall_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;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">WINDOW_WIDTH</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 200</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span> wall_thickness</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;"> WINDOW_HEIGHT</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> wall_thickness</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 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;">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;font-style: italic;"> // Bottom wall</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;"> Sprite</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from_color</span><span style="color: #9399B2;">(</span><span>wall_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;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">WINDOW_WIDTH</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> 200</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">,</span><span> wall_thickness</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: #94E2D5;"> -</span><span style="color: #FAB387;">WINDOW_HEIGHT</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> wall_thickness</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 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;">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;"> // 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> <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;">6</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;"> 1</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">0</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;">PADDLE_WIDTH</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> PADDLE_HEIGHT</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;"> PADDLE_Y</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> <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 style="color: #FAB387;">BALL_SPEED</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> BALL_SPEED</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;"> 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: #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;">BALL_SIZE</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;"> PADDLE_Y</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> PADDLE_HEIGHT</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 style="color: #FAB387;"> BALL_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 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 walls are extended sprites placed just outside the visible area, they serve as invisible collision boundaries. The ball starts sitting on top of the paddle.</p> <p>Now add the two new systems, ball movement and wall bouncing:</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 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 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: #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: #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> 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 style="color: #9399B2;"> (</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 style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">extend</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> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">fn</span><span style="color: #89B4FA;font-style: italic;"> bounce_ball_off_walls</span><span style="color: #9399B2;">(</span><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: #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: #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> query</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 style="color: #FAB387;"> WINDOW_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 style="color: #CBA6F7;"> let</span><span> half_height</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> WINDOW_HEIGHT</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_ball</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> BALL_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> <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;">-</span><span> half_ball</span><span style="color: #89DCEB;"> &lt;</span><span style="color: #94E2D5;"> -</span><span>half_width</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>half_width</span><span style="color: #94E2D5;"> +</span><span> half_ball</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: #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;">+</span><span> half_ball</span><span style="color: #94E2D5;"> &gt;</span><span> half_width</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> half_width</span><span style="color: #94E2D5;"> -</span><span> half_ball</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: #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>y </span><span style="color: #94E2D5;">+</span><span> half_ball</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> half_ball</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: #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> half_ball</span><span style="color: #89DCEB;"> &lt;</span><span style="color: #94E2D5;"> -</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> half_ball</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> <p>The ball moves by adding velocity × delta time to its position. When it hits a wall, we reverse the appropriate velocity component and snap the ball back inside the play area to prevent it from getting stuck.</p> <p>Update <code>main()</code> to include the state and the three gameplay systems:</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;Breakout&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;"> 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;">WINDOW_WIDTH</span><span style="color: #CBA6F7;"> as u32</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> WINDOW_HEIGHT</span><span style="color: #CBA6F7;"> as u32</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;">05</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">05</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">08</span><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> <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> move_paddle</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> move_ball</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> bounce_ball_off_walls</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 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>Notice <code>run_if(in_state(GameState::Playing))</code> these systems only run when the game is in the <code>Playing</code> state. For now we only have one state, but this pattern will matter when we add <code>GameOver</code> later.</p> <p>Run <code>cargo run</code>. The ball launches upward and bounces off all four walls. The paddle still moves. The ball passes right through the paddle for now, we fix that next.</p> <p><img src="/images/breakout-start.mp4" alt="breakout-start" /></p> <h3 id="4-paddle-collision">4. Paddle Collision</h3> <p>Add the paddle collision system. This uses an AABB overlap check, the same one from Pong but with a smarter bounce. The angle depends on where the ball hits the paddle:</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: #89DCEB;">&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: #94E2D5;">&amp;</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;">Paddle</span><span style="color: #89DCEB;">&gt;</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;</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 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;"> for</span><span> paddle_transform</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> 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> 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> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> half_ball</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> BALL_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_paddle_w</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> PADDLE_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 style="color: #CBA6F7;"> let</span><span> half_paddle_h</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> PADDLE_HEIGHT</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;"> let</span><span> overlap</span><span style="color: #94E2D5;"> = !</span><span style="color: #9399B2;">(</span><span>ball_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">+</span><span> half_ball</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> half_paddle_w</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> half_ball</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> half_paddle_w</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> half_ball</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> half_paddle_h</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> half_ball</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> half_paddle_h</span><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: #94E2D5;"> &amp;&amp;</span><span> ball</span><span style="color: #94E2D5;">.</span><span>velocity</span><span style="color: #94E2D5;">.</span><span>y</span><span style="color: #94E2D5;"> &lt;</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</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> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> hit_offset</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span>ball_pos</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: #9399B2;">)</span><span style="color: #94E2D5;"> /</span><span> half_paddle_w</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> hit_offset</span><span style="color: #94E2D5;"> *</span><span style="color: #FAB387;"> BALL_SPEED</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> ball_transform</span><span style="color: #94E2D5;">.</span><span>translation</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">=</span><span> paddle_pos</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">+</span><span> half_paddle_h</span><span style="color: #94E2D5;"> +</span><span> half_ball</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>hit_offset</code> ranges from -1.0 (left edge) to 1.0 (right edge). The ball's horizontal velocity is set to <code>hit_offset * BALL_SPEED</code>, so hitting the edge sends the ball flying at an angle while hitting the center sends it straight up. This gives the player real control over ball direction.</p> <p>The <code>ball.velocity.y &lt; 0.0</code> check prevents the ball from bouncing upward if it approaches the paddle from below.</p> <p>Add this system to the <code>Update</code> set in <code>main()</code>. Find the <code>Update</code> block and add the line:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span>check_paddle_collision</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></code></pre> <p>So the full <code>Update</code> block now looks like:</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> <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> move_paddle</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> move_ball</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> bounce_ball_off_walls</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> check_paddle_collision</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 style="color: #9399B2;"> ),</span></span> <span class="giallo-l"><span style="color: #9399B2;">)</span></span></code></pre> <p>Run <code>cargo run</code>. The ball now bounces off the paddle. Try hitting it with different parts of the paddle, the angle changes.</p> <p><img src="/images/breakout-ball-bounce.mp4" alt="breakout-ball-bounce" /></p> <h3 id="5-bricks-and-score">5. Bricks and Score</h3> <p>Time for the main event. We need a grid of colored bricks, collision detection that knows which side the ball hit, and a score counter.</p> <p>Add the brick constants and new components:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">const</span><span style="color: #FAB387;"> BRICK_WIDTH</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 64</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;"> BRICK_HEIGHT</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> 24</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;"> BRICK_PADDING</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</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> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span style="color: #FAB387;"> BRICK_TOP</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> f32</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: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">const</span><span style="color: #FAB387;"> BRICK_COLS</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> i32</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;">const</span><span style="color: #FAB387;"> BRICK_ROWS</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> <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;"> Brick</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 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 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;">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>Bricks are 64×24 pixels each, arranged in a 10×5 grid with 4 pixels of padding.</p> <p>Update <code>setup()</code> to insert the score resource and spawn the score text. Add these lines <strong>inside</strong> the <code>setup()</code> function, anywhere after the camera spawn:</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;">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> 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;"> 24</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: #94E2D5;">-</span><span style="color: #FAB387;">WINDOW_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: #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 style="color: #FAB387;"> WINDOW_HEIGHT</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 style="color: #FAB387;"> 30</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></code></pre> <p>Now add the <code>spawn_bricks</code> system. We use <code>OnEnter(GameState::Playing)</code> so bricks reset every time the game restarts:</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_bricks</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 style="color: #CBA6F7;"> let</span><span> brick_colors</span><span style="color: #94E2D5;"> =</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;">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;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;">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;">5</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> <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;">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;">1</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;">4</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> <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;">6</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> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> total_grid_width</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> BRICK_COLS</span><span style="color: #CBA6F7;"> as f32</span><span style="color: #94E2D5;"> *</span><span style="color: #9399B2;"> (</span><span style="color: #FAB387;">BRICK_WIDTH</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> BRICK_PADDING</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -</span><span style="color: #FAB387;"> BRICK_PADDING</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> start_x</span><span style="color: #94E2D5;"> = -</span><span>total_grid_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: #94E2D5;"> +</span><span style="color: #FAB387;"> BRICK_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</span><span> row</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 0</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">BRICK_ROWS</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span> col</span><span style="color: #CBA6F7;"> in</span><span style="color: #FAB387;"> 0</span><span style="color: #94E2D5;">..</span><span style="color: #FAB387;">BRICK_COLS</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> start_x</span><span style="color: #94E2D5;"> +</span><span> col</span><span style="color: #CBA6F7;"> as f32</span><span style="color: #94E2D5;"> *</span><span style="color: #9399B2;"> (</span><span style="color: #FAB387;">BRICK_WIDTH</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> BRICK_PADDING</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: #FAB387;"> BRICK_TOP</span><span style="color: #94E2D5;"> +</span><span> row</span><span style="color: #CBA6F7;"> as f32</span><span style="color: #94E2D5;"> *</span><span style="color: #9399B2;"> (</span><span style="color: #FAB387;">BRICK_HEIGHT</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> BRICK_PADDING</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;"> Brick</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>brick_colors</span><span style="color: #9399B2;">[</span><span>row</span><span style="color: #CBA6F7;"> as usize</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;">BRICK_WIDTH</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> BRICK_HEIGHT</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>x</span><span style="color: #9399B2;">,</span><span> y</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> <span class="giallo-l"><span style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>The grid is centered horizontally. Each row gets a different color: red, orange, yellow, green, blue.</p> <p>Now the brick collision system. This is the most interesting system in the game, when the ball overlaps a brick, we figure out which side it hit so we can bounce in the correct direction:</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_brick_collision</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: #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;"> brick_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: #F9E2AF;font-style: italic;">Entity</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: #F9E2AF;font-style: italic;">With</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Brick</span><span style="color: #89DCEB;">&gt;</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;</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;"> 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: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</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> half_ball</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> BALL_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> <span class="giallo-l"><span style="color: #CBA6F7;"> for</span><span style="color: #9399B2;"> (</span><span>brick_entity</span><span style="color: #9399B2;">,</span><span> brick_transform</span><span style="color: #9399B2;">)</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span>brick_query</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> brick_pos</span><span style="color: #94E2D5;"> =</span><span> brick_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> half_brick_w</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> BRICK_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 style="color: #CBA6F7;"> let</span><span> half_brick_h</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> BRICK_HEIGHT</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;"> let</span><span> overlap</span><span style="color: #94E2D5;"> = !</span><span style="color: #9399B2;">(</span><span>ball_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">+</span><span> half_ball</span><span style="color: #94E2D5;"> &lt;</span><span> brick_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">-</span><span> half_brick_w</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> half_ball</span><span style="color: #94E2D5;"> &gt;</span><span> brick_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">+</span><span> half_brick_w</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> half_ball</span><span style="color: #94E2D5;"> &lt;</span><span> brick_pos</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">-</span><span> half_brick_h</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> half_ball</span><span style="color: #94E2D5;"> &gt;</span><span> brick_pos</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">+</span><span> half_brick_h</span><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 style="color: #CBA6F7;"> let</span><span> overlap_left</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span>ball_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">+</span><span> half_ball</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -</span><span style="color: #9399B2;"> (</span><span>brick_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">-</span><span> half_brick_w</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> overlap_right</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span>brick_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">+</span><span> half_brick_w</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -</span><span style="color: #9399B2;"> (</span><span>ball_pos</span><span style="color: #94E2D5;">.</span><span>x </span><span style="color: #94E2D5;">-</span><span> half_ball</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> overlap_top</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span>ball_pos</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">+</span><span> half_ball</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -</span><span style="color: #9399B2;"> (</span><span>brick_pos</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">-</span><span> half_brick_h</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> overlap_bottom</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> (</span><span>brick_pos</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">+</span><span> half_brick_h</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> -</span><span style="color: #9399B2;"> (</span><span>ball_pos</span><span style="color: #94E2D5;">.</span><span>y </span><span style="color: #94E2D5;">-</span><span> half_ball</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> min_overlap_x</span><span style="color: #94E2D5;"> =</span><span> overlap_left</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">min</span><span style="color: #9399B2;">(</span><span>overlap_right</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> min_overlap_y</span><span style="color: #94E2D5;"> =</span><span> overlap_top</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">min</span><span style="color: #9399B2;">(</span><span>overlap_bottom</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> min_overlap_x</span><span style="color: #94E2D5;"> &lt;</span><span> min_overlap_y</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: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</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> <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>brick_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> score</span><span style="color: #94E2D5;">.</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> <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></code></pre> <p>The technique: calculate how much the ball overlaps each edge of the brick. The axis with the smaller overlap is the one the ball hit. If <code>min_overlap_x</code> is smaller, the ball hit the left or right side. Otherwise, hit the top or bottom. The <code>break</code> ensures we only process one brick per frame.</p> <p>Add the score text update 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;"> update_score_text</span><span style="color: #9399B2;">(</span><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 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;"> 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> 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: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Now update <code>main()</code>. Replace it with this version that adds <code>OnEnter</code> for bricks and the two new systems:</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;Breakout&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;"> 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;">WINDOW_WIDTH</span><span style="color: #CBA6F7;"> as u32</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> WINDOW_HEIGHT</span><span style="color: #CBA6F7;"> as u32</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;">05</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">05</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">08</span><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;">Playing</span><span style="color: #9399B2;">),</span><span> spawn_bricks</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> move_paddle</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> move_ball</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> bounce_ball_off_walls</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> check_paddle_collision</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> check_brick_collision</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> update_score_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;"> )</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>. Five rows of colored bricks appear at the top. Bounce the ball into them, they disappear on contact and the score goes up. The ball bounces in the correct direction depending on which side of the brick it hits. "Score: 0" is displayed on the top left.</p> <h3 id="6-particle-burst">6. Particle Burst</h3> <p>Breaking bricks is more satisfying with a visual reward. We will spawn a burst of particles each time a brick is destroyed, with each particle flying outward and fading out over half a second.</p> <p>Add the <code>Particle</code> component:</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;"> 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>Add the <code>spawn_brick_particles</code> helper function and the <code>update_particles</code> 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;"> spawn_brick_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;">8</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;"> 80</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;"> 120</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;">5</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;">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;">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: #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> <span class="giallo-l"></span> <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;">just_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 style="color: #9399B2;"> }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Eight yellow particles burst from the brick position. Each particle gets a random angle, <code>rand::random::&lt;f32&gt;() * TAU</code> gives us a full 360° spread and a speed between 80 and 200 pixels per second. The <code>Timer</code> gives each particle a 0.5 second lifetime. <code>fraction_remaining()</code> goes from 1.0 (just spawned) to 0.0 (about to despawn), which drives the alpha fade.</p> <p>Now hook it up. In <code>check_brick_collision</code>, find the line <code>commands.entity(brick_entity).despawn();</code> and add <code>spawn_brick_particles</code> right before it:</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;"> spawn_brick_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> brick_transform</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">translation</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>brick_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></code></pre> <p>Add <code>update_particles</code> to the <code>Update</code> set in <code>main()</code>. Find the <code>Update</code> block and add:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span> update_particles</span><span style="color: #9399B2;">,</span></span></code></pre> <p>So the <code>Update</code> block now looks like:</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> <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> move_paddle</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> move_ball</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> bounce_ball_off_walls</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> check_paddle_collision</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> check_brick_collision</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> update_particles</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 style="color: #9399B2;"> ),</span></span> <span class="giallo-l"><span style="color: #9399B2;"> )</span></span></code></pre> <p><code>update_particles</code> runs unconditionally, no <code>run_if</code> so particles continue animating even when we add the game over screen later.</p> <p>Run <code>cargo run</code>. Destroy a brick and watch eight yellow particles fly outward and fade. Feels satisfying.</p> <h3 id="7-lives-and-game-over">7. Lives and Game Over</h3> <p>The final piece: if the ball falls past the paddle, the player loses a life. Lose all three and it is game over, with a prompt to restart.</p> <p>Add the new components and resources:</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;"> Lives</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;">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;"> LivesText</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></code></pre> <p>Update the <code>GameState</code> enum to include <code>GameOver</code>:</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>Update <code>setup()</code> to add the lives resource and lives text. Add these lines inside <code>setup()</code>:</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;">insert_resource</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">Lives</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> 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;"> LivesText</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;Lives: 3&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;"> 24</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;">WINDOW_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: #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 style="color: #FAB387;"> WINDOW_HEIGHT</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 style="color: #FAB387;"> 30</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></code></pre> <p>Now replace the <code>bounce_ball_off_walls</code> function entirely. The bottom wall no longer bounces instead it decrements lives and either resets the ball or transitions to game over:</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_off_walls</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: #CBA6F7;"> mut</span><span style="color: #EBA0AC;"> lives</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;">Lives</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: #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 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> half_width</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> WINDOW_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 style="color: #CBA6F7;"> let</span><span> half_height</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> WINDOW_HEIGHT</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_ball</span><span style="color: #94E2D5;"> =</span><span style="color: #FAB387;"> BALL_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> <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;">-</span><span> half_ball</span><span style="color: #89DCEB;"> &lt;</span><span style="color: #94E2D5;"> -</span><span>half_width</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>half_width</span><span style="color: #94E2D5;"> +</span><span> half_ball</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: #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;">+</span><span> half_ball</span><span style="color: #94E2D5;"> &gt;</span><span> half_width</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> half_width</span><span style="color: #94E2D5;"> -</span><span> half_ball</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: #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>y </span><span style="color: #94E2D5;">+</span><span> half_ball</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> half_ball</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: #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> half_ball</span><span style="color: #89DCEB;"> &lt;</span><span style="color: #94E2D5;"> -</span><span>half_height</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> lives</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #94E2D5;"> =</span><span> lives</span><span style="color: #94E2D5;">.</span><span style="color: #FAB387;">0</span><span style="color: #9399B2;">.</span><span style="color: #89B4FA;font-style: italic;">saturating_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: #CBA6F7;"> if</span><span> lives</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> 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: #9399B2;"> }</span><span style="color: #CBA6F7;"> else</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> <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 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;"> PADDLE_Y</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> PADDLE_HEIGHT</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 style="color: #FAB387;"> BALL_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 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</span><span style="color: #94E2D5;">.</span><span>velocity </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;">BALL_SPEED</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> BALL_SPEED</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>saturating_sub(1)</code> ensures lives never go below zero even if multiple collisions happen in the same frame. When lives reach zero, the state transitions to <code>GameOver</code>. Otherwise the ball resets to its starting position on the paddle.</p> <p>Add the brick cleanup, game over display, restart, and lives text systems:</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;"> cleanup_bricks</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;"> bricks</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;">Brick</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>bricks</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> <span class="giallo-l"></span> <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 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> <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> <span class="giallo-l"></span> <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;"> lives</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;">Lives</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;"> 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: #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> lives</span><span style="color: #94E2D5;">.</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> 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 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> transform</span><span style="color: #94E2D5;">.</span><span>translation </span><span style="color: #94E2D5;">=</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 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;"> PADDLE_Y</span><span style="color: #94E2D5;"> +</span><span style="color: #FAB387;"> PADDLE_HEIGHT</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 style="color: #FAB387;"> BALL_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 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</span><span style="color: #94E2D5;">.</span><span>velocity </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;">BALL_SPEED</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> BALL_SPEED</span><span style="color: #9399B2;">);</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;">Playing</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;"> update_lives_text</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">lives</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;">Lives</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span><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;">LivesText</span><span style="color: #89DCEB;">&gt;&gt;</span><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> 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;Lives: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> lives</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>The state transitions do the heavy lifting here:</p> <ul> <li><code>OnExit(GameState::Playing)</code> → <code>cleanup_bricks</code> despawns all bricks.</li> <li><code>OnEnter(GameState::Playing)</code> → <code>spawn_bricks</code> (already added in section 5) spawns fresh bricks.</li> <li><code>OnEnter(GameState::GameOver)</code> → <code>show_game_over</code> spawns the message.</li> <li><code>OnExit(GameState::GameOver)</code> → <code>hide_game_over</code> despawns the message.</li> </ul> <p>This guarantees bricks and the game over message are always in sync with the state, whether we are starting fresh or restarting.</p> <p>Finally, replace <code>main()</code> with the complete version:</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;Breakout&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;"> 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;">WINDOW_WIDTH</span><span style="color: #CBA6F7;"> as u32</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> WINDOW_HEIGHT</span><span style="color: #CBA6F7;"> as u32</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;">05</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">05</span><span style="color: #9399B2;">,</span><span style="color: #FAB387;"> 0</span><span style="color: #9399B2;">.</span><span style="color: #FAB387;">08</span><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;">Playing</span><span style="color: #9399B2;">),</span><span> spawn_bricks</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;">Playing</span><span style="color: #9399B2;">),</span><span> cleanup_bricks</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> move_paddle</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> move_ball</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> bounce_ball_off_walls</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> check_paddle_collision</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> check_brick_collision</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> update_particles</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_lives_text</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 now have the complete game:</p> <p><img src="/images/breakout-gameplay.mp4" alt="Breakout gameplay" /></p> <h3 id="things-we-could-improve">Things We Could Improve</h3> <ul> <li>Add sound effects for paddle hits, wall bounces, brick breaks, and life loss</li> <li>Add a high score that persists across sessions using file I/O</li> <li>Add a title screen with settings (volume sliders, fullscreen toggle)</li> <li>Add power-up drops from destroyed bricks (wider paddle, multi-ball)</li> <li>Remove the bottom wall sprite from <code>setup()</code> now that we handle the bottom with lives</li> </ul> <h3 id="conclusion">Conclusion</h3> <p>This was a fun one. We built a complete Breakout game in seven incremental steps, running the game after each one to see real progress. Along the way we covered collision side detection, particle bursts with lifetime timers, lives and game over with state transitions, and a clean restart loop using <code>OnEnter</code> and <code>OnExit</code> systems.</p> <p>In the next post, we will start Phase 2 of our series and build Frogger, where we learn about physics engines, tilemaps, and moving platforms.</p> <p>See you in the next one.</p> Wed, 17 Jun 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-rust-async-await-by-building-an-http-server/ https://blog.sheerluck.dev/posts/learn-rust-async-await-by-building-an-http-server/ <p>In this post, we are going to learn about async/await in Rust. We will learn about futures, the difference between OS threads and async tasks, the Tokio runtime, async TCP with <code>tokio::net::TcpListener</code>, <code>tokio::spawn</code> for concurrent tasks, and async file I/O. Once we cover all the concepts, we will build an <strong>Async HTTP/1.1 Server</strong> with a raw TCP listener, manual HTTP request parsing (no framework), request routing, static file serving with proper content types, and concurrent connection handling with <code>tokio::spawn</code>. 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, smart pointers, and concurrency with threads.</p> <p>In the last article, we built a Thread Pool from scratch using OS threads, channels, <code>Arc&lt;Mutex&lt;T&gt;&gt;</code>, and graceful shutdown. That was preemptive concurrency: the operating system decides when each thread runs. Today we will learn about cooperative concurrency with async/await, where tasks voluntarily yield control at <code>.await</code> points. We will build a real HTTP server that handles thousands of concurrent connections using async I/O.</p> <blockquote> <p><strong>A quick note before we begin:</strong> Async Rust introduces several new concepts such as futures, polling, wakers, and runtimes. Don't worry if every detail doesn't immediately click on the first read. Focus on understanding the overall flow of how async programs are structured and how the pieces fit together. We'll revisit many of these concepts in future projects, where repeated exposure will make them feel much more natural.</p> </blockquote> <p>Get source code from <a rel="external" href="https://github.com/MrSheerluck/async-http-in-rust">here</a></p> <h2 id="threads-vs-async">Threads vs Async</h2> <p>Let's start with a mental model. In the Thread Pool article, each worker was a dedicated OS thread. The OS scheduler preempts threads, meaning it can pause any thread at any instruction and switch to another. Threads are heavyweight: each one has its own stack (typically a few megabytes), and context switching between threads has overhead from the OS kernel.</p> <blockquote> <p>Please learn Operating Systems to learn more deeply. It's really interesting</p> </blockquote> <p>Async is different. An async runtime (like Tokio) runs many tasks on a small number of OS threads, often just one per CPU core. Tasks are lightweight state machines. When a task hits an <code>.await</code> point, it yields control back to the runtime, which picks another ready task to run. Tasks are cooperatively scheduled by the runtime. The OS can still preempt the worker thread, but task switching itself does not require a kernel-mediated thread context switch.</p> <p>Think of threads as a restaurant where each table gets its own dedicated waiter. Expensive but responsive. Think of async as a single waiter handling many tables. The waiter takes an order from table 1, while the kitchen prepares table 1's food the waiter takes table 2's order, then table 3's, then checks if table 1's food is ready. The waiter is never blocked waiting. They switch between tables whenever a table is not ready.</p> <p>The key insight: async shines when your program spends a lot of time waiting for external operations such as network requests, database queries, timers, or file access. While one task waits for a response, the runtime runs another task. CPU-bound workloads benefit more from threads (and <code>rayon</code> for data parallelism, which we won't cover today).</p> <h2 id="futures">Futures</h2> <p>In Rust, an async function or block returns a future. A future is a value that represents a computation that is not yet complete. Under the hood, a future is a type that implements the <code>Future</code> trait from the standard library:</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;">future</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Future</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;">pin</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Pin</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;">task</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">Context</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> Poll</span><span style="color: #9399B2;">};</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">pub trait</span><span style="color: #F9E2AF;font-style: italic;"> Future</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> type</span><span style="color: #F9E2AF;font-style: italic;"> Output</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> poll</span><span style="color: #9399B2;">(</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> Pin</span><span style="color: #89DCEB;">&lt;</span><span style="color: #94E2D5;">&amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> Self</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> cx</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #CBA6F7;">mut</span><span style="color: #F9E2AF;font-style: italic;"> Context</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;font-style: italic;"> Poll</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;">Output</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>Let me read this from the outside in:</p> <ul> <li><code>type Output</code> is the type the future resolves to. For <code>async fn foo() -&gt; i32</code>, <code>Output</code> is <code>i32</code>.</li> <li><code>poll</code> is the heart of the trait. It asks the future: "are you done yet?".</li> <li><code>Poll&lt;T&gt;</code> is an enum with two variants: <code>Poll::Ready(T)</code> meaning the computation is complete and here is the result, and <code>Poll::Pending</code> meaning the computation is not ready yet, try again later.</li> <li><code>Context</code> carries a <code>Waker</code>, which is a handle the runtime gives to the future. When the future is <code>Pending</code>, it must arrange for the waker to be called when progress can be made (for example, when data arrives on a socket).</li> </ul> <p>You almost never implement <code>Future</code> by hand. The compiler generates the state machine when you write <code>async fn</code> or <code>async { }</code> blocks. But understanding the trait helps you understand what <code>.await</code> actually does.</p> <h2 id="async-and-await">async and .await</h2> <p>An async function is syntactic sugar for a function that returns a future:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> hello</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: #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: #9399B2;">}</span></span></code></pre> <p>This is roughly equivalent to:</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;</span><span style="color: #CBA6F7;"> impl</span><span style="color: #F9E2AF;font-style: italic;"> Future</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Output</span><span style="color: #94E2D5;"> =</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;"> async</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;hello&quot;</span><span style="color: #9399B2;">) }</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Calling an async function does not run its body. It returns a future. You need to <code>.await</code> the future to run it:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="rust"><span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> greet</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 style="color: #89B4FA;font-style: italic;"> hello</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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> 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>hello()</code> returns a future of type <code>impl Future&lt;Output = String&gt;</code>. The <code>.await</code> drives that future to completion. When we hit <code>hello().await</code>, control yields to the runtime. If the future is ready immediately, execution continues without yielding. If it is pending, the runtime switches to another task.</p> <p>You can only use <code>.await</code> inside another async function or block. This is the "async infection" people talk about: once you go async, everything up the call stack must be async too.</p> <h2 id="async-blocks">Async Blocks</h2> <p>You can also create async blocks inline:</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> future</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> async</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;"> compute_a</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;"> compute_b</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span> a</span><span style="color: #94E2D5;"> +</span><span> b</span></span> <span class="giallo-l"><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> future</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #9399B2;">;</span></span></code></pre> <p>An async block is like a closure but for creating futures. It captures variables from the surrounding scope just like closures do.</p> <h2 id="the-tokio-runtime">The Tokio Runtime</h2> <p>Futures are inert. They don't do anything on their own. You need a runtime to poll them. The runtime has two main components:</p> <ol> <li><strong>The Reactor</strong>: Registers interest in I/O events with the operating system (using epoll on Linux, kqueue on macOS, IOCP on Windows). When a socket has data, the reactor wakes the task that is waiting on it.</li> <li><strong>The Executor</strong>: Maintains a queue of tasks that are ready to run. It polls tasks, one at a time, on a small number of worker threads.</li> </ol> <p>Tokio is the most popular async runtime for Rust. It provides the reactor, the executor, and async versions of standard library types: <code>TcpListener</code>, <code>TcpStream</code>, <code>File</code>, timers, channels, and more.</p> <p>Add Tokio to your Cargo.toml:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="toml"><span class="giallo-l"><span style="color: #9399B2;">[</span><span>dependencies</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span>tokio</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&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;full&quot;</span><span style="color: #9399B2;">] }</span></span></code></pre> <p>The <code>features = ["full"]</code> flag enables all of Tokio's functionality. In production you would pick only the features you need. For learning, full is fine.</p> <h2 id="tokio-main"><code>#[tokio::main]</code></h2> <p>Tokio provides a macro to set up the runtime and run your async main function:</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;">tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">main</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">async 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 from async land&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>This expands to roughly:</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> rt</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">runtime</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Runtime</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 style="color: #89B4FA;font-style: italic;">unwrap</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> rt</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">block_on</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">async</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 async land&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>#[tokio::main]</code> creates a multi-threaded runtime by default. By default, Tokio creates one worker thread per available CPU. You can control this with <code>#[tokio::main(flavor = "current_thread")]</code> for a single-threaded runtime, or <code>#[tokio::main(worker_threads = 4)]</code> for a specific count.</p> <p>For an HTTP server, the multi-threaded runtime is appropriate because we want to distribute connections across cores.</p> <h2 id="async-tcp-with-tokio">Async TCP with Tokio</h2> <p>Let's write a simple TCP echo server to understand async I/O:</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;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">io</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span style="color: #F9E2AF;font-style: italic;">AsyncReadExt</span><span style="color: #9399B2;">,</span><span style="color: #F9E2AF;font-style: italic;"> AsyncWriteExt</span><span style="color: #9399B2;">};</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">net</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">TcpListener</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;">tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">main</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">io</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Result</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: #CBA6F7;"> let</span><span> listener</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> TcpListener</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">bind</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;127.0.0.1:8080&quot;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;Listening on 127.0.0.1:8080&quot;</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;"> let</span><span style="color: #9399B2;"> (</span><span style="color: #CBA6F7;">mut</span><span> socket</span><span style="color: #9399B2;">,</span><span> addr</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span> listener</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">accept</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;Connection from </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> addr</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #F9E2AF;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">async move</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> buf</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;">u8</span><span style="color: #9399B2;">;</span><span style="color: #FAB387;"> 1024</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> socket</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 style="color: #CBA6F7;">mut</span><span> buf</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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: #FAB387;">0</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;Connection closed by </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> addr</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: #F9E2AF;font-style: italic;"> Ok</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;"> if</span><span> socket</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">write_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>buf</span><span style="color: #9399B2;">[</span><span style="color: #94E2D5;">..</span><span>n</span><span style="color: #9399B2;">])</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_err</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: #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;"> 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: #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>TcpListener::bind("127.0.0.1:8080").await?</code> creates a TCP listener bound to port 8080. Notice the <code>.await</code> after <code>bind</code>. <code>TcpListener::bind(...).await</code> creates and registers the socket with Tokio. The operation is usually completed immediately and does not involve waiting for incoming network events.</p> <p>The <code>loop</code> continuously accepts new connections. listener.accept().await suspends the current task until a new TCP connection arrives. When one does, it returns a <code>(TcpStream, SocketAddr)</code>.</p> <p>Each connection is handled inside <code>tokio::spawn(async move { ... })</code>. This spawns a new lightweight task on the Tokio runtime. The task runs concurrently with all other tasks. Unlike <code>thread::spawn</code>, this does not create a new OS thread. The task is a state machine managed by the executor.</p> <p>Inside the spawned task, we loop, reading from the socket and writing back whatever we read. <code>socket.read(&amp;mut buf).await</code> reads bytes from the socket. If it returns <code>Ok(0)</code>, the connection was closed by the peer. <code>socket.write_all(&amp;buf[..n]).await</code> writes the same bytes back (echo). Note that both <code>read</code> and <code>write_all</code> are async methods from <code>AsyncReadExt</code> and <code>AsyncWriteExt</code>.</p> <p>A single thread with async I/O can often handle thousands of mostly idle network connections concurrently. The reactor multiplexes I/O events, and the executor switches between ready tasks. Tasks that are waiting for I/O consume almost no resources.</p> <h2 id="tokio-spawn-and-joinhandle">tokio::spawn and JoinHandle</h2> <p><code>tokio::spawn</code> returns a <code>JoinHandle&lt;T&gt;</code> where <code>T</code> is the output of the spawned future. This is the async counterpart of <code>thread::spawn</code> returning <code>thread::JoinHandle&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: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">main</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">async 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;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">async</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">time</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">sleep</span><span style="color: #9399B2;">(</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;">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 style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #FAB387;"> 42</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;Waiting for result...&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> handle</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;Got: </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>Now, let me explain what we just did.</p> <p>Unlike thread handles where you call <code>.join()</code>, you <code>.await</code> a tokio <code>JoinHandle</code>. This does not block the OS thread. It yields the current task until the spawned task completes. The current thread can do other work while waiting.</p> <p>The <code>.unwrap()</code> on <code>handle.await</code> handles the case where the spawned task panicked. Just like threads, if a task panics, the join handle captures the panic.</p> <h2 id="tokio-join-and-tokio-select">tokio::join! and tokio::select!</h2> <p>Sometimes you want to run multiple futures concurrently and wait for all of them. <code>tokio::join!</code> does 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;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">time</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span>sleep</span><span style="color: #9399B2;">,</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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> task_a</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: #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 style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;A&quot;</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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> task_b</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: #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;">2</span><span style="color: #9399B2;">))</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;B&quot;</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;">tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">main</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">async 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>a</span><span style="color: #9399B2;">,</span><span> b</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">join!</span><span style="color: #9399B2;">(</span><span style="color: #89B4FA;font-style: italic;">task_a</span><span style="color: #9399B2;">(),</span><span style="color: #89B4FA;font-style: italic;"> task_b</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> b</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #9399B2;">}</span></span></code></pre> <p>Both <code>task_a</code> and <code>task_b</code> run concurrently. The total time is about 2 seconds (the max), not 3 seconds (the sum). <code>tokio::join!</code> returns a tuple of the results in the same order as the futures passed.</p> <p><code>tokio::select!</code> is different. The losing futures are dropped. Whether that actually cancels the underlying operation depends on the future's implementation.</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;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">time</span><span style="color: #94E2D5;">::</span><span style="color: #9399B2;">{</span><span>sleep</span><span style="color: #9399B2;">,</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: #F9E2AF;font-style: italic;">#</span><span style="color: #9399B2;">[</span><span style="color: #F9E2AF;font-style: italic;">tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">main</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">async 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;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">select!</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> _</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;">2</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;Timer fired after 2 seconds&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;"> async_operation</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;Operation completed: </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> <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;">async fn</span><span style="color: #89B4FA;font-style: italic;"> async_operation</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: #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 style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;done&quot;</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>tokio::select!</code> runs both futures concurrently. <code>async_operation</code> finishes in 1 second. The timer still has 1 second left. The <code>async_operation</code> branch wins, prints its message, and the timer future is dropped. For Tokio's sleep future, dropping it effectively cancels the timer. This is the pattern for implementing timeouts, graceful shutdown signals, and racing multiple operations.</p> <h2 id="sharing-state-across-tasks">Sharing State Across Tasks</h2> <p>Just like threads, async tasks sometimes need to share data. The same core primitives we learned in the Thread Pool article still apply. <code>Arc&lt;T&gt;</code> is used for shared ownership, channels are used for message passing, and mutexes or read-write locks are used to coordinate access to shared mutable state.</p> <p>One important difference is how locking works. <code>std::sync::Mutex</code> blocks the underlying OS thread while waiting for a lock. In async applications, blocking a worker thread can prevent the runtime from making progress on other tasks scheduled on that thread. Tokio therefore provides <code>tokio::sync::Mutex</code>, whose <code>.lock().await</code> yields the current task instead of blocking the thread.</p> <p>That said, <code>std::sync::Mutex</code> is not forbidden in async code. If lock contention is low and the lock is not held across an <code>.await</code> point, it can be a perfectly reasonable choice. The important rule is to avoid blocking the runtime unnecessarily.</p> <p>For our HTTP server, we do not need any shared mutable state. Each connection is handled independently, and each task works with its own socket. The only shared data is the server's configuration, specifically the directory being served. We will use <code>Arc&lt;PathBuf&gt;</code> to share that configuration across all connection-handling tasks.</p> <h2 id="what-we-are-skipping">What We Are Skipping</h2> <p>We are not covering <code>Pin</code> in depth. The short version is: <code>Pin</code> guarantees that a value won't be moved in memory, which is required for self-referential types like the state machines generated by async functions. In practice you almost never interact with <code>Pin</code> directly. The compiler and the runtime handle it.</p> <p>We are not covering async streams, async traits, or async iterators. Those are more advanced async patterns.</p> <p>We are not covering <code>hyper</code>, <code>axum</code>, <code>actix-web</code>, or any HTTP framework. This project is about understanding how HTTP and async work at the lowest level in Rust. Once you understand this, frameworks make sense.</p> <p>We are not covering TLS/HTTPS. That requires <code>rustls</code> or OpenSSL and is a separate topic.</p> <p>We are not covering HTTP/2 or HTTP/3. We are building HTTP/1.1, which is the simplest and most common version.</p> <h2 id="the-project-async-http-1-1-server">The Project: Async HTTP/1.1 Server</h2> <p>Now that you understand futures, async/await, and Tokio, let's build an Async HTTP/1.1 Server from scratch.</p> <p>Our program will:</p> <ul> <li>Bind to a TCP port (default 8080)</li> <li>Accept connections concurrently using <code>tokio::spawn</code></li> <li>Parse raw HTTP/1.1 request lines and headers (method, path, headers)</li> <li>Route GET and HEAD requests to a static file server</li> <li>Detect Content-Type from file extensions</li> <li>Return proper status codes: 200, 400, 404, 405, 500</li> <li>Include Content-Length in every response</li> <li>Serve files from a configurable root directory</li> <li>Handle URL path traversal attacks (reject paths with <code>..</code>)</li> <li>Default directory index serving (serve <code>index.html</code> for <code>/</code> paths)</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 async_http</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">cd</span><span style="color: #A6E3A1;"> async_http</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;async_http&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>tokio</span><span style="color: #94E2D5;"> =</span><span style="color: #9399B2;"> {</span><span> version</span><span style="color: #94E2D5;"> =</span><span style="color: #A6E3A1;"> &quot;1&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;full&quot;</span><span style="color: #9399B2;">] }</span></span></code></pre> <p>The only dependency is Tokio with all features enabled. Everything else comes from the standard library.</p> <p>Open <code>src/main.rs</code> and delete everything. We will build the server from scratch.</p> <h3 id="the-request-struct">The Request Struct</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;">struct</span><span style="color: #F9E2AF;font-style: italic;"> Request</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> method</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> path</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> headers</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;"> String</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><code>Request</code> holds the parsed request data. The method is something like <code>GET</code> or <code>HEAD</code>. The path is the URL path like <code>/index.html</code> or <code>/images/cat.png</code>. The headers are key-value pairs like <code>Host: localhost:8080</code> and <code>Connection: keep-alive</code>. We store header keys in lowercase for case-insensitive lookup later.</p> <h3 id="the-response-struct">The Response 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;"> Response</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> status_code</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> u16</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> status_text</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> headers</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;"> String</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> body</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 style="color: #9399B2;">}</span></span></code></pre> <p><code>Response</code> holds everything needed to build an HTTP response. The status code is the numeric code like 200 or 404. The status text is the human-readable version like "OK" or "Not Found". Headers include at minimum <code>Content-Length</code>. The body is a byte vector because HTTP bodies can be binary (images, PDFs, etc.)</p> <h3 id="response-builder-methods">Response Builder Methods</h3> <p>Let's implement methods on <code>Response</code> to construct responses and serialize them to bytes:</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;"> Response</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;">status_code</span><span style="color: #94E2D5;">:</span><span style="color: #CBA6F7;"> u16</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> status_text</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: #F38BA8;"> Self</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> status_code</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> status_text</span><span style="color: #94E2D5;">:</span><span> status_text</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> headers</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> body</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> <span class="giallo-l"><span style="color: #CBA6F7;"> fn</span><span style="color: #89B4FA;font-style: italic;"> with_body</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> body</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 style="color: #EBA0AC;"> content_type</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: #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>headers</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Content-Length&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span><span> body</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: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>headers</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Content-Type&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span><span> content_type</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: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>body </span><span style="color: #94E2D5;">=</span><span> body</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</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;"> with_body_text</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">mut</span><span style="color: #F38BA8;"> self</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> body</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> String</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: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>headers</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Content-Length&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span><span> body</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: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>headers</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Content-Type&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span><span style="color: #A6E3A1;"> &quot;text/plain; charset=utf-8&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: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>body </span><span style="color: #94E2D5;">=</span><span> body</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into_bytes</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #F38BA8;"> self</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;"> to_bytes</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;"> 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 mut</span><span> response</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;HTTP/1.1 </span><span style="color: #9399B2;">{} {}</span><span style="color: #F5C2E7;">\r\n</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>status_code</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> self</span><span style="color: #94E2D5;">.</span><span>status_text</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> value</span><span style="color: #9399B2;">)</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>headers </span><span style="color: #9399B2;">{</span></span> <span class="giallo-l"><span> response</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: #F5C2E7;">\r\n</span><span style="color: #A6E3A1;">&quot;</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: #9399B2;"> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> response</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;Connection: close</span><span style="color: #F5C2E7;">\r\n</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> response</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;</span><span style="color: #F5C2E7;">\r\n</span><span style="color: #A6E3A1;">&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> bytes</span><span style="color: #94E2D5;"> =</span><span> response</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">into_bytes</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span> bytes</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">extend_from_slice</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span style="color: #F38BA8;">self</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">body</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> bytes</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>Response::new</code> creates a response with just a status code and text, no body and no headers yet. The body is an empty <code>Vec&lt;u8&gt;</code>.</p> <p><code>with_body</code> and <code>with_body_text</code> are builder-style methods. They consume <code>self</code> and return a new <code>Response</code> with the body and appropriate headers set. <code>with_body</code> takes a <code>Vec&lt;u8&gt;</code> and a content type string. This is for binary responses like images. <code>with_body_text</code> takes a <code>String</code> and sets <code>text/plain; charset=utf-8</code>. This is for error messages and simple text responses. Both methods set the <code>Content-Length</code> header automatically from the length of the body.</p> <p><code>to_bytes</code> serializes the response to a byte vector ready to write to the socket. It builds the status line (<code>HTTP/1.1 200 OK\r\n</code>), then each header (<code>Content-Length: 1234\r\n</code>), then a blank line to separate headers from body, then the body bytes.</p> <p>Every response includes <code>Connection: close</code>. For simplicity, the server closes the connection after each request. Real HTTP/1.1 servers often support keep-alive, which reuses the connection for multiple requests, but that adds significant complexity (parsing multiple requests from one stream, handling timeouts, etc). We are skipping keep-alive for now.</p> <h3 id="content-type-detection">Content Type Detection</h3> <p>We need to set the correct <code>Content-Type</code> header based on file extension:</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;"> guess_content_type</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">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; &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</span><span> ext</span><span style="color: #94E2D5;"> =</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: #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> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">extension</span><span style="color: #9399B2;">()</span></span> <span class="giallo-l"><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>e</span><span style="color: #94E2D5;">|</span><span> e</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: #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> <span class="giallo-l"><span style="color: #CBA6F7;"> match</span><span> ext</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;html&quot;</span><span style="color: #94E2D5;"> |</span><span style="color: #A6E3A1;"> &quot;htm&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;text/html; charset=utf-8&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;css&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;text/css; charset=utf-8&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;js&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;application/javascript; charset=utf-8&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;json&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;application/json&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;png&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;image/png&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;jpg&quot;</span><span style="color: #94E2D5;"> |</span><span style="color: #A6E3A1;"> &quot;jpeg&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;image/jpeg&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;gif&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;image/gif&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;svg&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;image/svg+xml&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;ico&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;image/x-icon&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;txt&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;text/plain; charset=utf-8&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;pdf&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;application/pdf&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;xml&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;application/xml; charset=utf-8&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;zip&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;application/zip&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;woff&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;font/woff&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;woff2&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;font/woff2&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;ttf&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;font/ttf&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;mp3&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;audio/mpeg&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;mp4&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;video/mp4&quot;</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;wasm&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #A6E3A1;"> &quot;application/wasm&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;application/octet-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></code></pre> <p>Now, let me explain what we just did.</p> <p><code>std::path::Path::new(path).extension()</code> extracts the file extension. <code>.and_then(|e| e.to_str())</code> converts the <code>OsStr</code> to a regular <code>&amp;str</code>. If there is no extension, we default to an empty string. The <code>match</code> maps known extensions to MIME types. Text-based formats get <code>charset=utf-8</code> appended. Everything else falls through to <code>application/octet-stream</code>, which tells the browser to download the file rather than try to display it.</p> <h3 id="request-parsing">Request Parsing</h3> <p>Now we need to parse raw HTTP bytes into a <code>Request</code> struct. HTTP/1.1 request format:</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;">GET</span><span style="color: #A6E3A1;"> /index.html HTTP/1.1</span><span style="color: #F5C2E7;">\r\n</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Host:</span><span style="color: #A6E3A1;"> localhost:8080</span><span style="color: #F5C2E7;">\r\n</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">User-Agent:</span><span style="color: #A6E3A1;"> curl/8.0</span><span style="color: #F5C2E7;">\r\n</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Accept:</span><span> *</span><span style="color: #A6E3A1;">/</span><span>*</span><span style="color: #F5C2E7;">\r\n</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">\r\n</span></span></code></pre> <p>The first line is the request line: METHOD, a space, the path, a space, <code>HTTP/1.1</code>, then <code>\r\n</code>. Each header is <code>Key: Value\r\n</code>. The headers end with a blank line <code>\r\n\r\n</code>. There may be a body after the blank line if <code>Content-Length</code> is present, but for our server we only care about GET and HEAD requests, which have no body.</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_request</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: #F9E2AF;font-style: italic;"> Option</span><span style="color: #89DCEB;">&lt;</span><span style="color: #F9E2AF;font-style: italic;">Request</span><span style="color: #89DCEB;">&gt;</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> text</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>data</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: #CBA6F7;"> let mut</span><span> lines</span><span style="color: #94E2D5;"> =</span><span> text</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> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Parse request line: METHOD PATH HTTP/1.1</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> request_line</span><span style="color: #94E2D5;"> =</span><span> lines</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: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> parts</span><span style="color: #94E2D5;"> =</span><span> request_line</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> method</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;">to_string</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> 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;">to_string</span><span style="color: #9399B2;">();</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> _version</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: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Parse headers</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> headers</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> line</span><span style="color: #CBA6F7;"> in</span><span style="color: #94E2D5;"> &amp;</span><span style="color: #CBA6F7;">mut</span><span> lines</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;">is_empty</span><span style="color: #9399B2;">() {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> break</span><span style="color: #9399B2;">;</span><span style="color: #9399B2;font-style: italic;"> // end of headers</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>key</span><span style="color: #9399B2;">,</span><span> value</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;">split_once</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">:</span><span style="color: #9399B2;">&#39;) {</span></span> <span class="giallo-l"><span> headers</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: #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_lowercase</span><span style="color: #9399B2;">(),</span><span> value</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> <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;">Request</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span> method</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> path</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> headers</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>std::str::from_utf8(data)</code> converts the raw bytes to a string slice. This parser assumes UTF-8 input for simplicity. Production HTTP servers operate on raw bytes and do not require requests to be valid UTF-8.</p> <p><code>text.lines()</code> splits the input on <code>\n</code> (and strips <code>\r</code> automatically). The first line is the request line. We split it on whitespace to extract the method, path, and HTTP version.</p> <p>The <code>for line in &amp;mut lines</code> loop reads header lines until we hit an empty line. <code>line.split_once(':')</code> splits on the first colon (header values can contain colons, so we only split on the first one). We store the key in lowercase for case-insensitive lookups. If a header is malformed (no colon), we skip it silently.</p> <h3 id="path-validation">Path Validation</h3> <p>HTTP clients can send malicious paths that attempt to escape the server's root directory. For example, <code>GET /../../../etc/passwd HTTP/1.1</code> should be 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;"> validate_path</span><span style="color: #9399B2;">(</span><span style="color: #EBA0AC;">raw_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;"> 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> path</span><span style="color: #94E2D5;"> =</span><span> raw_path</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">trim_start_matches</span><span style="color: #9399B2;">(&#39;</span><span style="color: #A6E3A1;">/</span><span style="color: #9399B2;">&#39;);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Reject paths with &quot;..&quot; to prevent directory traversal</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> path</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;..&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;"> None</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;"> // Default to index.html for directory requests</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> path</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">is_empty</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;">ends_with</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: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</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;">index.html&quot;</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 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>path</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.</p> <p>We strip the leading <code>/</code> because the path will be joined with the serve directory later. The <code>..</code> check catches obvious traversal attempts, but the canonicalization check later is the actual security boundary. An empty path (the root <code>/</code>) or a path ending in <code>/</code> is treated as a directory request and defaults to <code>index.html</code>. So <code>GET / HTTP/1.1</code> serves <code>/index.html</code> and <code>GET /blog/ HTTP/1.1</code> serves <code>/blog/index.html</code>.</p> <h3 id="the-file-server-function">The File Server Function</h3> <p>Now let's build the function that handles GET and HEAD requests. This function is async because it reads files from disk using Tokio's async filesystem:</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;">path</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">PathBuf</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> tokio</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;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">io</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">AsyncReadExt</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> serve_file</span><span style="color: #9399B2;">(</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> path</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;"> serve_dir</span><span style="color: #94E2D5;">: &amp;</span><span style="color: #F9E2AF;font-style: italic;">PathBuf</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #EBA0AC;"> head_only</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 style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> validated_path</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #89B4FA;font-style: italic;"> validate_path</span><span style="color: #9399B2;">(</span><span>path</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>p</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> p</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;"> let mut</span><span> resp</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">400</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Bad Request&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span> resp</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">with_body_text</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;400 Bad Request: Invalid path&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> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> file_path</span><span style="color: #94E2D5;"> =</span><span> serve_dir</span><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>validated_path</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Canonicalize the path and verify it stays within serve_dir</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> canonical</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> file_path</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">canonicalize</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>p</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> p</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;"> let mut</span><span> resp</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">404</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Not Found&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span> resp</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">with_body_text</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;404 Not Found&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> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> serve_dir_canonical</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> serve_dir</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">canonicalize</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>p</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> p</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;"> let mut</span><span> resp</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">500</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Internal Server Error&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span> resp</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">with_body_text</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;500 Internal Server Error&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> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span style="color: #94E2D5;"> !</span><span>canonical</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">starts_with</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>serve_dir_canonical</span><span style="color: #9399B2;">) {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> resp</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">403</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Forbidden&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span> resp</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">with_body_text</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;403 Forbidden&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> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> content_type</span><span style="color: #94E2D5;"> =</span><span style="color: #89B4FA;font-style: italic;"> guess_content_type</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>validated_path</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> if</span><span> head_only</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // For HEAD, we only need metadata, not the body</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> metadata</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;">metadata</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>canonical</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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>m</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> m</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;"> let mut</span><span> resp</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">404</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Not Found&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span> resp</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">with_body_text</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;404 Not Found&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> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> resp</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">200</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;OK&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> resp</span><span style="color: #94E2D5;">.</span><span>headers</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Content-Length&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span><span> metadata</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: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">());</span></span> <span class="giallo-l"><span> resp</span><span style="color: #94E2D5;">.</span><span>headers</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Content-Type&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span><span> content_type</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;"> return</span><span> resp</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;"> // For GET, read the file</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> file</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: #F9E2AF;font-style: italic;">File</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">open</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>canonical</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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>f</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> f</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;"> let mut</span><span> resp</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">404</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Not Found&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span> resp</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">with_body_text</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;404 Not Found&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> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> body</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;"> if let</span><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;"> =</span><span> file</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> body</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let mut</span><span> resp</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">500</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Internal Server Error&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> return</span><span> resp</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">with_body_text</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;500 Internal Server Error&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> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">200</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;OK&quot;</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">with_body</span><span style="color: #9399B2;">(</span><span>body</span><span style="color: #9399B2;">,</span><span> content_type</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>This function uses multiple layers of path validation. First, <code>validate_path</code> rejects paths with <code>..</code>. Then we join the validated path with the serve directory. Then we canonicalize both the requested path and the serve directory. <code>canonicalize</code> resolves symlinks and normalizes the path to an absolute form. We then check that the canonical requested path starts with the canonical serve directory. This is defense-in-depth: even if a crafted path somehow bypasses the <code>..</code> check, the canonicalization check catches it.</p> <p>The <code>head_only</code> parameter determines whether this is a GET or HEAD request. HEAD should return the same headers as GET would have returned, except without the message body. We return a 200 response with <code>Content-Length</code> set but no body. For GET, we open the file with Tokio's <code>fs::File::open</code>, read the entire contents into a <code>Vec&lt;u8&gt;</code> using <code>read_to_end</code>, and return a 200 response with the full body.</p> <p>Tokio exposes an async API for file operations. Internally these operations are often executed on a dedicated blocking thread pool. These yield the task while the disk I/O is in progress, allowing other connections to be handled.</p> <p>Note that <code>file_path.canonicalize()</code> and <code>serve_dir.canonicalize()</code> are blocking operations from <code>std</code>. For a simple server this is fine because canonicalization is fast. A production server might use Tokio's <code>spawn_blocking</code> for these.</p> <h3 id="the-connection-handler">The Connection Handler</h3> <p>Now we tie everything together. Each incoming connection is handled by this function:</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;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">io</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">AsyncWriteExt</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">use</span><span style="color: #F9E2AF;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">net</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">TcpStream</span><span style="color: #9399B2;">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> handle_connection</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">mut</span><span style="color: #EBA0AC;"> socket</span><span style="color: #94E2D5;">:</span><span style="color: #F9E2AF;font-style: italic;"> TcpStream</span><span style="color: #9399B2;">,</span><span style="color: #EBA0AC;"> serve_dir</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;">PathBuf</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> buf</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;">u8</span><span style="color: #9399B2;">;</span><span style="color: #FAB387;"> 8192</span><span style="color: #9399B2;">];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Read data from the socket</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> n</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> socket</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 style="color: #CBA6F7;">mut</span><span> buf</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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: #FAB387;">0</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #CBA6F7;"> return</span><span style="color: #9399B2;">,</span><span style="color: #9399B2;font-style: italic;"> // client closed immediately</span></span> <span class="giallo-l"><span style="color: #F9E2AF;font-style: italic;"> Ok</span><span style="color: #9399B2;">(</span><span>n</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> n</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;"> 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;"> // Parse the request</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> request</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span style="color: #89B4FA;font-style: italic;"> parse_request</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>buf</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: #F9E2AF;font-style: italic;"> Some</span><span style="color: #9399B2;">(</span><span>req</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> req</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;"> let</span><span> response</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">400</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Bad Request&quot;</span><span style="color: #9399B2;">)</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">with_body_text</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;400 Bad Request: Unable to parse request&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: #CBA6F7;"> let</span><span> _</span><span style="color: #94E2D5;"> =</span><span> socket</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">write_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>response</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_bytes</span><span style="color: #9399B2;">())</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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> <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;"> -&gt; </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> </span></span> <span class="giallo-l"><span> request</span><span style="color: #94E2D5;">.</span><span>method</span><span style="color: #9399B2;">,</span><span> </span></span> <span class="giallo-l"><span> request</span><span style="color: #94E2D5;">.</span><span>path</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span> request</span><span style="color: #94E2D5;">.</span><span>headers</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;host&quot;</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;">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> socket</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">local_addr</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: #9399B2;font-style: italic;"> // Route the request</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> response</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> request</span><span style="color: #94E2D5;">.</span><span>method</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;GET&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> serve_file</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>request</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">path</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>serve_dir</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> false</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</span><span style="color: #9399B2;">,</span></span> <span class="giallo-l"><span style="color: #A6E3A1;"> &quot;HEAD&quot;</span><span style="color: #94E2D5;"> =&gt;</span><span style="color: #89B4FA;font-style: italic;"> serve_file</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>request</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;">path</span><span style="color: #9399B2;">,</span><span style="color: #94E2D5;"> &amp;</span><span>serve_dir</span><span style="color: #9399B2;">,</span><span style="color: #F38BA8;"> true</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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 mut</span><span> resp</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> Response</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">new</span><span style="color: #9399B2;">(</span><span style="color: #FAB387;">405</span><span style="color: #9399B2;">,</span><span style="color: #A6E3A1;"> &quot;Method Not Allowed&quot;</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span> resp</span><span style="color: #94E2D5;">.</span><span>headers</span></span> <span class="giallo-l"><span style="color: #94E2D5;"> .</span><span style="color: #89B4FA;font-style: italic;">insert</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Allow&quot;</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_string</span><span style="color: #9399B2;">(),</span><span style="color: #A6E3A1;"> &quot;GET, HEAD&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> resp</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">with_body_text</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;405 Method Not Allowed&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> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Send the response</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> _</span><span style="color: #94E2D5;"> =</span><span> socket</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">write_all</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>response</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">to_bytes</span><span style="color: #9399B2;">())</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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>The function takes ownership of the <code>TcpStream</code> (consuming it so no one else can read or write to it) and an <code>Arc&lt;PathBuf&gt;</code> for the serve directory. The <code>Arc</code> lets us share the directory path across all connection tasks without cloning the string.</p> <p>We allocate a fixed-size buffer of 8 KiB on the stack. This should be enough for most HTTP requests (which are typically under 1 KiB). If a request is larger than 8 KiB, <code>read</code> will fill the buffer and the rest of the request stays in the socket's kernel buffer. For our simple server, we only need the request line and headers, which are always at the start, so 8 KiB is more than enough.</p> <p><code>socket.read(&amp;mut buf).await</code> reads whatever data is available into the buffer. This is the async version of the <code>read</code> we used in the thread pool article. If the client sends nothing (<code>Ok(0)</code>), we return immediately.</p> <p>We parse the request from the filled portion of the buffer. If parsing fails, we send a 400 Bad Request and return.</p> <p>We print a simple access log showing the method, path, host header, and local address of the connection.</p> <p>Finally, we route the request based on the HTTP method. GET and HEAD go to <code>serve_file</code>. Everything else gets a 405 Method Not Allowed with an <code>Allow</code> header listing supported methods.</p> <p>The response is serialized with <code>response.to_bytes()</code> and written back to the socket with <code>socket.write_all(...).await</code>. We ignore the result of <code>write_all</code> because if the client has disconnected, there is nothing we can do.</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;">use</span><span style="color: #F9E2AF;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">net</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">TcpListener</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;">tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">main</span><span style="color: #9399B2;">]</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">async fn</span><span style="color: #89B4FA;font-style: italic;"> main</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;"> -&gt;</span><span style="color: #F9E2AF;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;">io</span><span style="color: #94E2D5;">::</span><span style="color: #F9E2AF;font-style: italic;">Result</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: #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>port</span><span style="color: #9399B2;">,</span><span> serve_dir</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 style="color: #F9E2AF;font-style: italic;"> PathBuf</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">from</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>args</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: #9399B2;"> }</span><span style="color: #CBA6F7;"> else 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;"> ==</span><span style="color: #FAB387;"> 2</span><span style="color: #9399B2;"> {</span></span> <span class="giallo-l"><span style="color: #9399B2;font-style: italic;"> // Only port provided, serve from current directory</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 style="color: #F9E2AF;font-style: italic;"> PathBuf</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: #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;port&gt; [serve_directory]&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;Example: cargo run -- 8080 ./public&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: #9399B2;font-style: italic;"> // Ensure we have an absolute path for canonicalization</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> serve_dir</span><span style="color: #94E2D5;"> =</span><span style="color: #CBA6F7;"> match</span><span> serve_dir</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">canonicalize</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>p</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;"> =&gt;</span><span> p</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: Cannot access directory &#39;</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&#39;: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> serve_dir</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">display</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> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> serve_dir</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>serve_dir</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> addr</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;127.0.0.1:</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> port</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #CBA6F7;"> let</span><span> listener</span><span style="color: #94E2D5;"> =</span><span style="color: #F9E2AF;font-style: italic;"> TcpListener</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">bind</span><span style="color: #9399B2;">(</span><span style="color: #94E2D5;">&amp;</span><span>addr</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;Server listening on http://</span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> addr</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;Serving files from: </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> serve_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: #89B4FA;font-style: italic;"> println!</span><span style="color: #9399B2;">(</span><span style="color: #A6E3A1;">&quot;Press Ctrl+C to stop.</span><span style="color: #F5C2E7;">\n</span><span style="color: #A6E3A1;">&quot;</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> listener</span><span style="color: #94E2D5;">.</span><span style="color: #89B4FA;font-style: italic;">accept</span><span style="color: #9399B2;">()</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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>socket</span><span style="color: #9399B2;">,</span><span> addr</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> dir</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>serve_dir</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #F9E2AF;"> tokio</span><span style="color: #94E2D5;">::</span><span style="color: #89B4FA;font-style: italic;">spawn</span><span style="color: #9399B2;">(</span><span style="color: #CBA6F7;">async move</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;Connection accepted from </span><span style="color: #9399B2;">{}</span><span style="color: #A6E3A1;">&quot;</span><span style="color: #9399B2;">,</span><span> addr</span><span style="color: #9399B2;">);</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> handle_connection</span><span style="color: #9399B2;">(</span><span>socket</span><span style="color: #9399B2;">,</span><span> dir</span><span style="color: #9399B2;">)</span><span style="color: #94E2D5;">.</span><span style="color: #CBA6F7;">await</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;"> 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 accepting connection: </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: #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 parse command-line arguments. The first argument is the port number. The second (optional) argument is the directory to serve files from. If no directory is specified, we serve from the current directory.</p> <p>We canonicalize the serve directory immediately. This converts it to an absolute path (so we can validate that all requests stay within it) and also verifies that the directory exists and is accessible. If it is not, we print an error and exit.</p> <p>The serve directory is wrapped in <code>Arc::new(...)</code> for sharing across spawned tasks. Each connection handler gets its own <code>Arc::clone(&amp;serve_dir)</code>. We used this exact pattern in the Thread Pool article. The only difference is we are now sharing a <code>PathBuf</code> instead of an <code>Arc&lt;Mutex&lt;Receiver&lt;Job&gt;&gt;&gt;</code>.</p> <p>The main loop is identical in structure to the async echo server we wrote earlier. It calls <code>listener.accept().await</code> to wait for the next connection. When a connection arrives, it clones the <code>Arc</code> and spawns a new Tokio task to handle it. The spawned task runs <code>handle_connection</code>, which reads the request, routes it, and writes the response.</p> <p>The <code>loop</code> runs forever. To stop the server, press Ctrl+C. The Tokio runtime automatically handles the interrupt signal and shuts down.</p> <h3 id="static-file-serving-details">Static File Serving Details</h3> <p>Let's trace through an example request to understand the complete flow. A browser requests <code>http://localhost:8080/css/style.css</code> from a server serving the <code>./public</code> directory:</p> <ol> <li>TCP connection arrives. <code>listener.accept().await</code> returns a <code>(TcpStream, SocketAddr)</code>.</li> <li><code>tokio::spawn</code> creates a new lightweight task.</li> <li><code>handle_connection</code> reads from the socket. The raw bytes look like:<pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">GET</span><span style="color: #A6E3A1;"> /css/style.css HTTP/1.1</span><span style="color: #F5C2E7;">\r\n</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Host:</span><span style="color: #A6E3A1;"> localhost:8080</span><span style="color: #F5C2E7;">\r\n</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Connection:</span><span style="color: #A6E3A1;"> keep-alive</span><span style="color: #F5C2E7;">\r\n</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">\r\n</span></span></code></pre></li> <li><code>parse_request</code> extracts method <code>GET</code>, path <code>/css/style.css</code>, and headers.</li> <li><code>validate_path("/css/style.css")</code> strips the leading <code>/</code>, yielding <code>css/style.css</code>. No <code>..</code> detected. No trailing slash, so no <code>index.html</code> appended.</li> <li><code>serve_file</code> is called with <code>path = "/css/style.css"</code>, <code>serve_dir = "./public"</code>, <code>head_only = false</code>.</li> <li>The file path becomes <code>./public/css/style.css</code>.</li> <li>Both paths are canonicalized. If <code>./public</code> resolves to <code>/home/user/project/public</code> and <code>./public/css/style.css</code> resolves to <code>/home/user/project/public/css/style.css</code>, the prefix check passes.</li> <li><code>guess_content_type("css/style.css")</code> looks at the <code>css</code> extension and returns <code>text/css; charset=utf-8</code>.</li> <li><code>fs::File::open</code> opens the file. If it exists, <code>read_to_end</code> reads its contents into a <code>Vec&lt;u8&gt;</code>.</li> <li>A <code>Response</code> is built with status 200, <code>Content-Type: text/css; charset=utf-8</code>, <code>Content-Length: &lt;size&gt;</code>, and the body.</li> <li><code>to_bytes()</code> serializes everything and writes it back to the socket.</li> <li>The connection closes (because <code>Connection: close</code> is always sent).</li> </ol> <h2 id="running-the-project">Running the Project</h2> <p>Create a test directory with some 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;">mkdir</span><span style="color: #A6E3A1;"> -p www/css www/images</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">echo</span><span style="color: #A6E3A1;"> &#39;&lt;!DOCTYPE html&gt;&lt;html&gt;&lt;body&gt;&lt;h1&gt;Hello Async!&lt;/h1&gt;&lt;/body&gt;&lt;/html&gt;&#39;</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #A6E3A1;"> www/index.html</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">echo</span><span style="color: #A6E3A1;"> &#39;body { font-family: sans-serif; }&#39;</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #A6E3A1;"> www/css/style.css</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">echo</span><span style="color: #A6E3A1;"> &#39;Hello, World!&#39;</span><span style="color: #94E2D5;"> &gt;</span><span style="color: #A6E3A1;"> www/hello.txt</span></span></code></pre> <p>Now start the server:</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 style="color: #FAB387;"> 8080</span><span style="color: #A6E3A1;"> ./www</span></span></code></pre> <p>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;">Server</span><span style="color: #A6E3A1;"> listening on http://127.0.0.1:8080</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Serving</span><span style="color: #A6E3A1;"> files from: /Users/you/async_http/www</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Press</span><span style="color: #A6E3A1;"> Ctrl+C to stop.</span></span></code></pre><h3 id="testing-with-curl">Testing with curl</h3> <p>Open another terminal and test:</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;">curl</span><span style="color: #A6E3A1;"> -v http://localhost:8080/</span></span></code></pre> <p>Expected output:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #94E2D5;">*</span><span> Connected to localhost (</span><span style="color: #89B4FA;font-style: italic;">127.0.0.1</span><span>) port 8080</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&gt;</span><span> GET / HTTP/1.1</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&gt;</span><span> Host: localhost:8080</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&gt;</span><span> User-Agent: curl/8.0</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&gt;</span><span> Accept: </span><span style="color: #94E2D5;">*</span><span>/</span><span style="color: #94E2D5;">*</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&gt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span> HTTP/1.1 200 OK</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span> Content-Length: 62</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span> Content-Type: text/html</span><span style="color: #9399B2;">;</span><span> charset</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">utf-8</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span> Connection: close</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;!</span><span style="color: #89B4FA;font-style: italic;">DOCTYPE</span><span style="color: #A6E3A1;"> htm</span><span>l&gt;&lt;</span><span style="color: #A6E3A1;">htm</span><span>l&gt;&lt;</span><span style="color: #A6E3A1;">bod</span><span>y&gt;&lt;</span><span style="color: #A6E3A1;">h</span><span style="color: #94E2D5;">1&gt;</span><span style="color: #A6E3A1;">Hello Async!</span><span style="color: #94E2D5;">&lt;</span><span style="color: #A6E3A1;">/h</span><span>1&gt;&lt;</span><span style="color: #A6E3A1;">/bod</span><span>y&gt;&lt;</span><span style="color: #A6E3A1;">/htm</span><span>l</span><span style="color: #94E2D5;">&gt;</span></span></code></pre> <p>The server log shows:</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;">Connection</span><span style="color: #A6E3A1;"> accepted from 127.0.0.1:54321</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">GET</span><span style="color: #A6E3A1;"> / localhost:8080</span><span> -</span><span style="color: #94E2D5;">&gt;</span><span style="color: #A6E3A1;"> 127.0.0.1:8080</span></span></code></pre> <p>Test the CSS 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;">curl</span><span style="color: #A6E3A1;"> http://localhost:8080/css/style.css</span></span></code></pre> <p>Expected:</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;">body</span><span style="color: #A6E3A1;"> { font-family: sans-serif</span><span style="color: #9399B2;">;</span><span> }</span></span></code></pre> <p>Test an HTML 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;">curl</span><span style="color: #A6E3A1;"> http://localhost:8080/hello.txt</span></span></code></pre> <p>Expected:</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></code></pre> <p>Test a 404:</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;">curl</span><span style="color: #A6E3A1;"> -v http://localhost:8080/nonexistent.html</span></span></code></pre> <p>Expected:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span> HTTP/1.1 404 Not Found</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span> Content-Length: 14</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">404</span><span style="color: #A6E3A1;"> Not Found</span></span></code></pre> <p>Test a HEAD request:</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;">curl</span><span style="color: #A6E3A1;"> -I http://localhost:8080/</span></span></code></pre> <p>Expected:</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;">HTTP/1.1</span><span style="color: #FAB387;"> 200</span><span style="color: #A6E3A1;"> OK</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Content-Length:</span><span style="color: #FAB387;"> 62</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Content-Type:</span><span style="color: #A6E3A1;"> text/html</span><span style="color: #9399B2;">;</span><span> charset</span><span style="color: #94E2D5;">=</span><span style="color: #A6E3A1;">utf-8</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Connection:</span><span style="color: #A6E3A1;"> close</span></span></code></pre> <p>No body is returned. Only the headers.</p> <p>Test method not allowed:</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;">curl</span><span style="color: #A6E3A1;"> -v -X POST http://localhost:8080/</span></span></code></pre> <p>Expected:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span> HTTP/1.1 405 Method Not Allowed</span></span> <span class="giallo-l"><span style="color: #94E2D5;">&lt;</span><span> Allow: GET, HEAD</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">405</span><span style="color: #A6E3A1;"> Method Not Allowed</span></span></code></pre><h3 id="concurrent-connection-test">Concurrent Connection Test</h3> <p>Let's verify the server handles concurrent connections. In one terminal, create a small script to make parallel requests:</p> <pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;"><code data-lang="shellscript"><span class="giallo-l"><span style="color: #CBA6F7;">for</span><span> i</span><span style="color: #CBA6F7;"> in</span><span style="color: #9399B2;"> $(</span><span style="color: #89B4FA;font-style: italic;">seq</span><span style="color: #FAB387;"> 1 10</span><span style="color: #9399B2;">);</span><span style="color: #CBA6F7;"> do</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;"> curl</span><span style="color: #A6E3A1;"> -s -o /dev/null -w &quot;Request </span><span>$i</span><span style="color: #A6E3A1;">: HTTP %{http_code}\n&quot; http://localhost:8080/</span><span style="color: #9399B2;"> &amp;</span></span> <span class="giallo-l"><span style="color: #CBA6F7;">done</span></span> <span class="giallo-l"><span style="color: #F38BA8;font-style: italic;">wait</span></span></code></pre> <p>Or if you have <code>ab</code> (Apache Bench) installed:</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;">ab</span><span style="color: #A6E3A1;"> -n</span><span style="color: #FAB387;"> 1000</span><span style="color: #A6E3A1;"> -c</span><span style="color: #FAB387;"> 50</span><span style="color: #A6E3A1;"> http://localhost:8080/</span></span></code></pre> <p>All requests complete successfully. The server handles them concurrently on Tokio's worker threads. The access log shows interleaved connection messages:</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;">Connection</span><span style="color: #A6E3A1;"> accepted from 127.0.0.1:54322</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">GET</span><span style="color: #A6E3A1;"> / localhost:8080</span><span> -</span><span style="color: #94E2D5;">&gt;</span><span style="color: #A6E3A1;"> 127.0.0.1:8080</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Connection</span><span style="color: #A6E3A1;"> accepted from 127.0.0.1:54323</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">GET</span><span style="color: #A6E3A1;"> / localhost:8080</span><span> -</span><span style="color: #94E2D5;">&gt;</span><span style="color: #A6E3A1;"> 127.0.0.1:8080</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">Connection</span><span style="color: #A6E3A1;"> accepted from 127.0.0.1:54324</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">GET</span><span style="color: #A6E3A1;"> / localhost:8080</span><span> -</span><span style="color: #94E2D5;">&gt;</span><span style="color: #A6E3A1;"> 127.0.0.1:8080</span></span> <span class="giallo-l"><span style="color: #89B4FA;font-style: italic;">GET</span><span style="color: #A6E3A1;"> / localhost:8080</span><span> -</span><span style="color: #94E2D5;">&gt;</span><span style="color: #A6E3A1;"> 127.0.0.1:8080</span></span></code></pre> <p>Notice the interleaving: new connections are accepted while previous requests are still being processed. The async runtime multiplexes I/O across all concurrent connections.</p> <h2 id="how-it-all-fits-together">How It All Fits Together</h2> <p>Let's trace the lifecycle of a connection through the async runtime:</p> <ol> <li> <p><strong>Binding</strong>: <code>TcpListener::bind().await</code> registers the listening socket with the reactor. The reactor uses kqueue (macOS) or epoll (Linux) to watch for new connections.</p> </li> <li> <p><strong>Accepting</strong>: <code>listener.accept().await</code> yields the main task. The runtime can execute other ready tasks. When a TCP handshake completes, the reactor wakes the main task. It resumes and gets the new <code>TcpStream</code>.</p> </li> <li> <p><strong>Spawning</strong>: <code>tokio::spawn(async move { ... })</code> creates a new task. The task is placed in the executor's ready queue. The task does not run yet. The main loop goes back to waiting for the next connection.</p> </li> <li> <p><strong>Reading</strong>: When the executor picks up the spawned task, it runs it until it hits <code>.await</code> on <code>socket.read(...)</code>. The read future registers interest in the socket with the reactor and yields. The executor picks up another ready task.</p> </li> <li> <p><strong>Data arrives</strong>: The reactor detects that the socket has data. It wakes the waiting task. The executor puts it back in the ready queue. When the task runs again, <code>read</code> returns the bytes.</p> </li> <li> <p><strong>Parsing</strong>: Parsing the request is CPU-only work. There are no <code>.await</code> points, so the task continues running until it reaches the next async operation.</p> </li> <li> <p>File reading: <code>fs::File::open</code> and <code>read_to_end</code> expose an async API. Tokio typically executes the underlying file operations on a dedicated blocking thread pool while the task yields.</p> </li> <li> <p><strong>Writing</strong>: <code>socket.write_all(...).await</code> registers write interest with the reactor. When the socket is writable, the reactor wakes the task.</p> </li> <li> <p><strong>Completion</strong>: The spawned task finishes. The <code>TcpStream</code> is dropped, closing the socket. The <code>Connection: close</code> header informs the client that the connection will not be reused.</p> </li> </ol> <p>Throughout this whole process, there are only a few OS threads. On a 4-core machine, Tokio's default runtime uses 4 worker threads. But it can handle thousands of concurrent connections because most connections spend most of their time waiting for I/O, and during that wait the thread they were running on is free to run other tasks.</p> <p>Compare this to the Thread Pool article where we needed one OS thread per worker, and each worker could only handle one job at a time. For an HTTP server, the async model is dramatically more scalable.</p> <h2 id="what-we-skipped">What We Skipped</h2> <p>There are a few things I am intentionally skipping in this article:</p> <ul> <li><strong>HTTP keep-alive</strong>: Our server closes every connection after one response. Real web servers reuse connections for multiple requests. Implementing this requires buffered reading, timeout management, and tracking connection state across multiple requests. It adds significant complexity for a learning project.</li> <li><strong>Request body parsing</strong>: We only handle GET and HEAD. POST, PUT, and PATCH requests include a body. Handling bodies requires respecting <code>Content-Length</code> and <code>Transfer-Encoding: chunked</code>.</li> <li><strong>Streaming responses</strong>: For large files, reading the entire file into memory (as we do with <code>read_to_end</code>) is wasteful. A production server would use <code>tokio::io::copy</code> or <code>sendfile</code> to stream the file to the socket without loading it all into RAM.</li> <li><strong>Multipart and URL-encoded form parsing</strong>: Common patterns for web applications but out of scope for this article.</li> <li><strong>Async graceful shutdown</strong>: Our server stops when Ctrl+C is pressed, but it does not drain in-flight requests before exiting. Tokio provides <code>tokio::signal::ctrl_c()</code> and <code>CancellationToken</code> for this.</li> <li><strong>HTTPS/TLS</strong>: Setting up <code>rustls</code> with <code>tokio-rustls</code> is a separate topic.</li> <li><strong>HTTP routing</strong>: Real servers match paths against patterns and extract parameters. In our server, paths map directly to filesystem paths plus <code>index.html</code> for directories.</li> <li><strong>Custom error pages</strong>: We return plain text for all error responses. A real server would serve custom HTML pages.</li> </ul> <blockquote> <p>Everything we skipped in this article exists for a reason in real-world servers. Rather than introducing that complexity all at once, we focused on the async runtime, TCP networking, HTTP fundamentals, and static file serving. In the upcoming Rust backend series, we'll build production-style services with Axum and revisit many of these topics, including routing, request extraction, middleware, request bodies, graceful shutdown, and other features commonly used in modern web applications.</p> </blockquote> <h2 id="conclusion">Conclusion</h2> <p>In this post, you learned about async/await in Rust. You learned the difference between OS threads (preemptive concurrency) and async tasks (cooperative concurrency). You learned about futures (the <code>Future</code> trait and how the <code>poll</code> method works), async functions and blocks (which compile to state machines), and how <code>.await</code> yields control back to the runtime.</p> <p>You learned about the Tokio runtime: the reactor (which watches I/O events using kqueue/epoll) and the executor (which schedules ready tasks on a small pool of worker threads). You learned <code>#[tokio::main]</code>, <code>tokio::spawn</code>, <code>tokio::join!</code>, and <code>tokio::select!</code>.</p> <p>You built an Async HTTP/1.1 Server from scratch. The server listens on a TCP port using <code>tokio::net::TcpListener</code>, accepts connections concurrently with <code>tokio::spawn</code>, parses raw HTTP/1.1 request lines and headers manually (no framework), routes GET and HEAD requests to a static file server, detects Content-Type from file extensions, validates paths against directory traversal attacks, and returns proper HTTP status codes with Content-Length headers.</p> <p>This ties together everything from the Thread Pool article. Where threads give us preemptive multitasking at the OS level, async gives us cooperative multitasking within a single thread. The same primitives apply: <code>Arc</code> for shared ownership, <code>spawn</code> for concurrent execution, and channels for message passing (Tokio provides their async versions).</p> <p>In the next article, we will learn about SQLx and build a Book Library CLI with SQLite, compile-time checked queries, connection pooling, schema migrations, and full CRUD. 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> Fri, 12 Jun 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-rust-concurrency-by-building-a-thread-pool/ 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> Wed, 03 Jun 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-rust-smart-pointers-and-interior-mutability-by-building-git-commit-graph-viewer/ 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> Sat, 30 May 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-bevy-states-timers-by-building-snake/ 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> Thu, 28 May 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-rust-closures-by-building-a-tiny-linter/ 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> Tue, 19 May 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-hashmap-iterators-by-building-a-git-object-store-reader/ 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> Wed, 13 May 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-rust-lifetimes-by-building-a-lru-cache/ 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> Sat, 09 May 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-generics-traits-in-rust-by-building-blackjack-card-game-engine/ 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> Wed, 06 May 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-error-hanlding-in-rust/ 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> Wed, 29 Apr 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-rust-structs-enums-pattern-matching-by-building-a-json-parser/ 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> Sat, 18 Apr 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/crito/ 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> Fri, 17 Apr 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/apology/ 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> Mon, 13 Apr 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/euthyphro/ 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> Mon, 13 Apr 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/lessons-in-stoicism/ 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> Thu, 09 Apr 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-rust-ownership-by-building-mini-grep/ 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> Wed, 08 Apr 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/wtf-is-claude-mythos/ 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> Sun, 05 Apr 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/scalars-explained/ 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> Sat, 04 Apr 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/learn-rust-basics-by-building-a-brainfuck-interpreter/ 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> Tue, 31 Mar 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/wtf-is-a-supply-chain-attack/ 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> Fri, 20 Mar 2026 00:00:00 +0000 Unknown https://blog.sheerluck.dev/posts/welcome-to-mrsheerluck-blog/ https://blog.sheerluck.dev/posts/welcome-to-mrsheerluck-blog/ <p>Hi,</p>