🎄 Advent of Code 2023

Solutions for Advent of Code in Rust.

2023 Results

Day	Part 1	Part 2
Day 1	⭐	⭐
Day 2	⭐	⭐
Day 3	⭐	⭐
Day 4	⭐	⭐
Day 5	⭐	⭐
Day 6	⭐	⭐
Day 7	⭐	⭐
Day 8	⭐	⭐
Day 9	⭐	⭐
Day 10	⭐	⭐
Day 11	⭐	⭐
Day 12	⭐	⭐
Day 13	⭐	⭐
Day 14	⭐	⭐
Day 15	⭐	⭐
Day 16	⭐	⭐
Day 17	⭐	⭐
Day 18	⭐	⭐

Benchmarks

Day	Part 1	Part 2
Day 11	96.0µs	95.8µs
Day 12	358.8µs	770.0µs
Day 13	412.9µs	894.6µs
Day 14	39.9µs	26.5ms
Day 15	50.9µs	1.2ms
Day 16	73.4µs	8.7ms
Day 17	24.6ms	89.6ms
Day 18	43.9µs	58.5µs
Day 19	1.2ms	964.4µs
Day 20	2.6ms	10.4ms
Day 21	140.5ms	142.3ms
Day 22	174.0ms	187.1ms
Day 23	1.0ms	1.6ms
Day 24	386.0µs	83.6µs
Day 25	4.1ms	-

Total: 819.73ms

---

Usage

➡️ Scaffold a day

# example: `cargo scaffold 1`
cargo scaffold <day>

# output:
# Created module file "src/bin/01.rs"
# Created empty input file "data/inputs/01.txt"
# Created empty example file "data/examples/01.txt"
# ---
# 🎄 Type `cargo solve 01` to run your solution.

Individual solutions live in the ./src/bin/ directory as separate binaries. Inputs and examples live in the the ./data directory.

Every solution has tests referencing its example file in ./data/examples. Use these tests to develop and debug your solutions against the example input. In VS Code, rust-analyzer will display buttons for running / debugging these unit tests above the unit test blocks.

Tip

If a day has different example inputs for both parts, you can use the read_file_part() helper in your tests instead of read_file(). For example, if this applies to day 1, you can create a second example file 01-2.txt and invoke the helper like let result = part_two(&advent_of_code::template::read_file_part("examples", DAY, 2)); to read it in test_part_two.

➡️ Download input for a day

Important

This requires installing the aoc-cli crate.

You can automatically download puzzle input and description by either appending the --download flag to scaffold (e.g. cargo scaffold 4 --download) or with the separate download command:

# example: `cargo download 1`
cargo download <day>

# output:
# [INFO  aoc] 🎄 aoc-cli - Advent of Code command-line tool
# [INFO  aoc_client] 🎅 Saved puzzle to 'data/puzzles/01.md'
# [INFO  aoc_client] 🎅 Saved input to 'data/inputs/01.txt'
# ---
# 🎄 Successfully wrote input to "data/inputs/01.txt".
# 🎄 Successfully wrote puzzle to "data/puzzles/01.md".

➡️ Run solutions for a day

# example: `cargo solve 01`
cargo solve <day>

# output:
#     Finished dev [unoptimized + debuginfo] target(s) in 0.13s
#     Running `target/debug/01`
# Part 1: 42 (166.0ns)
# Part 2: 42 (41.0ns)

The solve command runs your solution against real puzzle inputs. To run an optimized build of your code, append the --release flag as with any other rust program.

By default, solve executes your code once and shows the execution time. If you append the --time flag to the command, the runner will run your code between 10 and 10.000 times (depending on execution time of first execution) and print the average execution time.

For example, running a benchmarked, optimized execution of day 1 would look like cargo solve 1 --release --time. Displayed timings show the raw execution time of your solution without overhead like file reads.

Submitting solutions

Important

This requires installing the aoc-cli crate.

In order to submit part of a solution for checking, append the --submit <part> option to the solve command.

➡️ Run all solutions

cargo all

# output:
#     Running `target/release/advent_of_code`
# ----------
# | Day 01 |
# ----------
# Part 1: 42 (19.0ns)
# Part 2: 42 (19.0ns)
# <...other days...>
# Total: 0.20ms

This runs all solutions sequentially and prints output to the command-line. Same as for the solve command, the --release flag runs an optimized build and the --time flag outputs benchmarks.

➡️ Update readme benchmarks

The template can write benchmark times to the README via the cargo time command.

By default, this command checks for missing benchmarks, runs those solutions, and then updates the table. If you want to (re-)time all solutions, run cargo time --all. If you want to (re-)time one specific solution, run cargo time <day>.

Please note that these are not scientific benchmarks, understand them as a fun approximation. 😉 Timings, especially in the microseconds range, might change a bit between invocations.

➡️ Run all tests

cargo test

To run tests for a specific day, append --bin <day>, e.g. cargo test --bin 01. You can further scope it down to a specific part, e.g. cargo test --bin 01 part_one.

➡️ Format code

cargo fmt

➡️ Lint code

cargo clippy

➡️ Read puzzle description

Important

This command requires installing the aoc-cli crate.

# example: `cargo read 1`
cargo read <day>

# output:
# Loaded session cookie from "/Users/<snip>/.adventofcode.session".
# Fetching puzzle for day 1, 2022...
# ...the input...

➡️ Scaffold, download & read the current aoc day

Important

This command requires installing the aoc-cli crate.

During december, the today shorthand command can be used to:

• scaffold a solution for the current day
• download its input
• and read the puzzle

in one go.

# example: `cargo today` on December 1st
cargo today

# output:
# Created module file "src/bin/01.rs"
# Created empty input file "data/inputs/01.txt"
# Created empty example file "data/examples/01.txt"
# ---
# 🎄 Type `cargo solve 01` to run your solution.
# [INFO  aoc] 🎄 aoc-cli - Advent of Code command-line tool
# [INFO  aoc_client] 🎅 Saved puzzle to 'data/puzzles/01.md'
# [INFO  aoc_client] 🎅 Saved input to 'data/inputs/01.txt'
# ---
# 🎄 Successfully wrote input to "data/inputs/01.txt".
# 🎄 Successfully wrote puzzle to "data/puzzles/01.md".
#
# Loaded session cookie from "/Users/<snip>/.adventofcode.session".
# Fetching puzzle for day 1, 2022...
# ...the input...

Optional template features

Configure aoc-cli integration

1. Install aoc-cli via cargo: cargo install aoc-cli --version 0.12.0
2. Create an .adventofcode.session file in your home directory and paste your session cookie. To retrieve the session cookie, press F12 anywhere on the Advent of Code website to open your browser developer tools. Look in Cookies under the Application or Storage tab, and copy out the session cookie value. ¹

Once installed, you can use the download command, the read command, and automatically submit solutions via the --submit flag.

Automatically track ⭐️ progress in the readme

This template includes a Github action that automatically updates the readme with your advent of code progress.

To enable it, complete the following steps:

1. Create a private leaderboard

Go to the leaderboard page of the year you want to track and click Private Leaderboard. If you have not created a leaderboard yet, create one by clicking Create It. Your leaderboard should be accessible under https://adventofcode.com/{year}/leaderboard/private/view/{aoc_user_id}.

2. Set repository secrets

Go to the Secrets tab in your repository settings and create the following secrets:

• AOC_USER_ID: Go to this page and copy your user id. It's the number behind the # symbol in the first name option. Example: 3031.
• AOC_YEAR: the year you want to track. Example: 2021.
• AOC_SESSION: an active session² for the advent of code website. To get this, press F12 anywhere on the Advent of Code website to open your browser developer tools. Look in your Cookies under the Application or Storage tab, and copy out the session cookie.

Go to the Variables tab in your repository settings and create the following variable:

• AOC_ENABLED: This variable controls whether the workflow is enabled. Set it to true to enable the progress tracker. After you complete AoC or no longer work on it, you can set this to false to disable the CI.

✨ You can now run this action manually via the Run workflow button on the workflow page. If you want the workflow to run automatically, uncomment the schedule section in the readme-stars.yml workflow file or add a push trigger.

Check code formatting / clippy lints in CI

Uncomment the respective sections in the ci.yml workflow.

Use DHAT to profile heap allocations

If you are not only interested in the runtime of your solution, but also its memory allocation profile, you can use the template's DHAT integration to analyze it. In order to activate DHAT, call the solve command with the --dhat flag.

cargo solve 1 --dhat

# output:
#     Running `target/dhat/1`
# dhat: Total:     276 bytes in 3 blocks
# dhat: At t-gmax: 232 bytes in 2 blocks
# dhat: At t-end:  0 bytes in 0 blocks
# dhat: The data has been saved to dhat-heap.json, and is viewable with dhat/dh_view.html
# Part 1: 9001 (4.1ms)

The command will output some basic stats to the command-line and generate a dhat-heap.json report in the repo root directory.

You can pass the report a tool like dh-view to view a detailed breakdown of heap allocations.

Use VS Code to debug your code

1. Install rust-analyzer and CodeLLDB.
2. Set breakpoints in your code. ³
3. Click Debug next to the unit test or the main function. ⁴
4. The debugger will halt your program at the specific line and allow you to inspect the local stack. ⁵

Useful crates

• itertools: Extends iterators with extra methods and adaptors. Frequently useful for aoc puzzles.
• regex: Official regular expressions implementation for Rust.

A curated list of popular crates can be found on blessred.rs.

Do you have aoc-specific crate recommendations? Share them!

Common pitfalls

• Integer overflows: This template uses 32-bit integers by default because it is generally faster - for example when packed in large arrays or structs - than using 64-bit integers everywhere. For some problems, solutions for real input might exceed 32-bit integer space. While this is checked and panics in debug mode, integers wrap in release mode, leading to wrong output when running your solution.

Footnotes

Footnotes

1. The session cookie might expire after a while (~1 month) which causes the downloads to fail. To fix this issue, refresh the .adventofcode.session file. ↩

2. The session cookie might expire after a while (~1 month) which causes the automated workflow to fail. To fix this issue, refresh the AOC_SESSION secret. ↩

3. ↩
4. ↩
5. ↩