Document Year 2021 Day 25

Author: maneatingape

src/year2021/day25.rs

@@ -1,5 +1,23 @@
+//! # Sea Cucumber
+//!
+//! To speed things up we compute an entire row at a time for each direction, storing `across`
+//! and `down` sea cucumbers as bits in a 256 bit wide variable.
+//!
+//! For example `...>>>>>...` is represented as `00011111000`.
+//! To compute the movement the steps are:
+//! * Rotate right by one `00001111100`
+//! * Invert existing cucumbers `11100000111`
+//! * Bitwise AND together to find cucumbers that can move `00000000100`
+//! * Rotate `00000001000` left by one, invert `11111110111` then bitwise AND with original
+//!   cucumbers to remove moving cucumbers from static `00011110000`
+//! * Finally bitwise OR static and moving cucumbers together for the final result
+//!   `00011110000 | 00000000100 = 00011110100`
+//!
+//! In the actual implementation `across` and `down` are stored separately so that we know
+//! which cucumbers turn it is to move. We bitwise OR both together to calculate any blockers.
 use std::ops::{BitAnd, BitOr, Not};
 
+/// Duct tape two `u128` together to make a 256 bit wide integer.
 #[derive(Clone, Copy, Default)]
 pub struct U256 {
     left: u128,
@@ -19,6 +37,7 @@ impl U256 {
         self.left != 0 || self.right != 0
     }
 
+    /// Perform a `rotate_left` where the width can be different from 256 bits.
     fn left_roll(&self, width: usize) -> U256 {
         if width <= 128 {
             let mask = !(1 << width);
@@ -32,6 +51,7 @@ impl U256 {
         }
     }
 
+    /// Perform a `rotate_right` where the width can be different from 256 bits.
     fn right_roll(&self, width: usize) -> U256 {
         if width <= 128 {
             let right = (self.right >> 1) | ((self.right & 1) << (width - 1));
@@ -44,6 +64,7 @@ impl U256 {
     }
 }
 
+/// Implement operator bitswise logic so that we can use the regular `&`, `|` and `!` notation.
 impl BitAnd for U256 {
     type Output = U256;
 
@@ -76,6 +97,7 @@ pub struct State {
     down: Vec<U256>,
 }
 
+/// Parse the sea cucumbers as individual bits into separate `across` and `down` arrays.
 pub fn parse(input: &str) -> State {
     let raw: Vec<&[u8]> = input.lines().map(str::as_bytes).collect();
     let width = raw[0].len();
@@ -111,6 +133,8 @@ pub fn part1(input: &State) -> usize {
         changed = false;
         count += 1;
 
+        // Use the bitwise logic described above to process an entire row across at a time.
+        // Direction is reflected due to the parsing so we rotate left instead of right.
         for i in 0..height {
             let candidates = across[i].left_roll(width);
             let moved = candidates & !(across[i] | down[i]);
@@ -119,6 +143,7 @@ pub fn part1(input: &State) -> usize {
             across[i] = moved | stay;
         }
 
+        // Use a similar approach to handle an entire row down at a time.
         let last_mask = across[0] | down[0];
         let mut moved = down[height - 1] & !last_mask;