[board] Implement a PositionBuilder; refactor piece bitboards into a PieceBitBoards struct

This makes Position immutable, even if declared mut. I think this will also make
it easier to build positions going forward.

Moving to a PieceBitBoards struct also required a lot of places that return owned
BitBoards to return refs. This is basically fine except for adding a few more &
here and there.

This was a huge refactoring project. All the move generators and a bunch of
BitBoard stuff needed to be updated.

board/src/bitboard/bitboard.rs

@@ -53,7 +53,7 @@ impl BitBoard {
     }
 
     pub fn is_set(self, sq: Square) -> bool {
-        !(self & sq.into()).is_empty()
+        !(self & &sq.into()).is_empty()
     }
 
     pub fn set_square(&mut self, sq: Square) {
@@ -180,11 +180,15 @@ macro_rules! assign_op {
 }
 
 infix_op!(BitAnd, bitand, BitBoard, BitBoard);
+infix_op!(BitAnd, bitand, BitBoard, &BitBoard);
+infix_op!(BitAnd, bitand, &BitBoard, &BitBoard);
 
 assign_op!(BitAndAssign, bitand_assign, BitBoard);
 assign_op!(BitOrAssign, bitor_assign, BitBoard);
 
 infix_op!(BitOr, bitor, BitBoard, BitBoard);
+infix_op!(BitOr, bitor, BitBoard, &BitBoard);
+infix_op!(BitOr, bitor, &BitBoard, &BitBoard);
 
 impl Not for BitBoard {
     type Output = BitBoard;

board/src/bitboard/library.rs

@@ -165,13 +165,13 @@ impl MoveLibrary {
     }
 
     #[inline]
-    fn generate_ray(sq: BitBoard, shift: fn(BitBoard) -> BitBoard) -> BitBoard {
+    fn generate_ray(sq: BitBoard, shift: fn(&BitBoard) -> BitBoard) -> BitBoard {
         let mut ray = BitBoard::empty();
 
-        let mut iter = shift(sq);
+        let mut iter = shift(&sq);
         while !iter.is_empty() {
             ray |= iter;
-            iter = shift(iter);
+            iter = shift(&iter);
         }
 
         ray

board/src/bitboard/shifts.rs

@@ -7,58 +7,58 @@ impl BitBoard {
     const NOT_H_FILE: u64 = 0x7f7f7f7f7f7f7f7f;
 
     #[inline]
-    pub fn shift_north(self, n: u8) -> BitBoard {
+    pub fn shift_north(&self, n: u8) -> BitBoard {
         BitBoard(self.0 << (8 * n))
     }
 
     #[inline]
-    pub fn shift_north_one(self) -> BitBoard {
+    pub fn shift_north_one(&self) -> BitBoard {
         BitBoard(self.0 << 8)
     }
 
     #[inline]
-    pub fn shift_north_east_one(self) -> BitBoard {
+    pub fn shift_north_east_one(&self) -> BitBoard {
         BitBoard(self.0 << 9 & BitBoard::NOT_A_FILE)
     }
 
     #[inline]
-    pub fn shift_east(self, n: u8) -> BitBoard {
+    pub fn shift_east(&self, n: u8) -> BitBoard {
         // TODO: Implement a bounds check here.
         BitBoard(self.0 << n)
     }
 
     #[inline]
-    pub fn shift_east_one(self) -> BitBoard {
+    pub fn shift_east_one(&self) -> BitBoard {
         BitBoard(self.0 << 1 & BitBoard::NOT_A_FILE)
     }
 
     #[inline]
-    pub fn shift_south_east_one(self) -> BitBoard {
+    pub fn shift_south_east_one(&self) -> BitBoard {
         BitBoard(self.0 >> 7 & BitBoard::NOT_A_FILE)
     }
 
     #[inline]
-    pub fn shift_south(self, n: u8) -> BitBoard {
+    pub fn shift_south(&self, n: u8) -> BitBoard {
         BitBoard(self.0 >> (8 * n))
     }
 
     #[inline]
-    pub fn shift_south_one(self) -> BitBoard {
+    pub fn shift_south_one(&self) -> BitBoard {
         BitBoard(self.0 >> 8)
     }
 
     #[inline]
-    pub fn shift_south_west_one(self) -> BitBoard {
+    pub fn shift_south_west_one(&self) -> BitBoard {
         BitBoard(self.0 >> 9 & BitBoard::NOT_H_FILE)
     }
 
     #[inline]
-    pub fn shift_west_one(self) -> BitBoard {
+    pub fn shift_west_one(&self) -> BitBoard {
         BitBoard(self.0 >> 1 & BitBoard::NOT_H_FILE)
     }
 
     #[inline]
-    pub fn shift_north_west_one(self) -> BitBoard {
+    pub fn shift_north_west_one(&self) -> BitBoard {
         BitBoard(self.0 << 7 & BitBoard::NOT_H_FILE)
     }
 }

board/src/lib.rs

@@ -13,8 +13,9 @@ pub mod position;
 mod sight;
 mod square;
 
-pub use position::Position;
+pub use piece::{Color, Piece};
-pub use r#move::{Move, MoveBuilder};
+pub use position::{Position, PositionBuilder};
+pub use r#move::{MakeMoveError, Move, MoveBuilder};
 pub use square::{File, Rank, Square};
 
 pub(crate) use bitboard::BitBoard;

board/src/move_generator/bishop.rs

@@ -21,8 +21,7 @@ impl<'pos> MoveGeneratorInternal for ClassicalMoveGenerator<'pos> {
 
         let blockers = position.occupied_squares();
         let empty_squares = !blockers;
-        let friendly_pieces = position.bitboard_for_color(color);
+        let (friendly_pieces, opposing_pieces) = position.all_pieces();
-        let opposing_pieces = position.bitboard_for_color(color.other());
 
         let mut all_moves = BitBoard::empty();
 
@@ -63,20 +62,18 @@ impl<'pos> MoveGeneratorInternal for ClassicalMoveGenerator<'pos> {
 mod tests {
     use super::*;
     use crate::{
+        piece,
         piece::{Color, Piece},
+        position,
         position::DiagramFormatter,
         BitBoard, Position, Square,
     };
 
     #[test]
     fn classical_single_bishop_bitboard() {
-        let mut pos = Position::empty();
+        let pos = position![
-        [(Piece::bishop(Color::White), Square::A1)]
+            White Bishop on A1,
-            .into_iter()
+        ];
-            .for_each(|(p, sq)| {
-                pos.place_piece(p, sq)
-                    .expect(&format!("Unable to place {:?} on {}", &p, &sq))
-            });
 
         let generator = ClassicalMoveGenerator::new(&pos, Color::White);
 
@@ -91,16 +88,10 @@ mod tests {
     /// Test that a bishop can move up to, but not onto, a friendly piece.
     #[test]
     fn classical_single_bishop_with_same_color_blocker_bitboard() {
-        let mut pos = Position::empty();
+        let pos = position![
-        [
+            White Bishop on A1,
-            (Piece::bishop(Color::White), Square::A1),
+            White Knight on E5,
-            (Piece::knight(Color::White), Square::E5),
+        ];
-        ]
-        .into_iter()
-        .for_each(|(p, sq)| {
-            pos.place_piece(p, sq)
-                .expect(&format!("Unable to place {} on {}", p, sq))
-        });
 
         println!("{}", DiagramFormatter::new(&pos));
 
@@ -117,16 +108,10 @@ mod tests {
     /// Test that a rook can move up to, and then capture, an enemy piece.
     #[test]
     fn classical_single_bishop_with_opposing_color_blocker_bitboard() {
-        let mut pos = Position::empty();
+        let mut pos = position![
-        [
+            White Bishop on A1,
-            (Piece::bishop(Color::White), Square::A1),
+            Black Knight on C3,
-            (Piece::knight(Color::Black), Square::C3),
+        ];
-        ]
-        .into_iter()
-        .for_each(|(p, sq)| {
-            pos.place_piece(p, sq)
-                .expect(&format!("Unable to place {} on {}", p, sq))
-        });
 
         let generator = ClassicalMoveGenerator::new(&pos, Color::White);
 
@@ -140,13 +125,9 @@ mod tests {
 
     #[test]
     fn classical_single_bishop_in_center() {
-        let mut pos = Position::empty();
+        let mut pos = position![
-        [(Piece::bishop(Color::White), Square::E4)]
+            White Bishop on E4,
-            .into_iter()
+        ];
-            .for_each(|(p, sq)| {
-                pos.place_piece(p, sq)
-                    .expect(&format!("Unable to place {} on {}", p, sq))
-            });
 
         println!("{}", DiagramFormatter::new(&pos));
 

board/src/move_generator/king.rs

@@ -76,23 +76,18 @@ impl<'pos> MoveGeneratorInternal for KingMoveGenerator<'pos> {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::{piece, piece::Piece, Position, Square};
+    use crate::Square;
     use std::collections::HashSet;
 
     #[test]
     fn one_king() {
-        let mut pos = Position::empty();
+        let pos = position![White King on E4];
-        pos.place_piece(Piece::king(Color::White), Square::E4)
-            .expect("Failed to place king on e4");
 
         let generator = KingMoveGenerator::new(&pos, Color::White);
 
-        let bb = generator.bitboard();
         assert_eq!(
-            bb,
+            generator.bitboard(),
-            BitBoard::new(
+            bitboard![E5, F5, F4, F3, E3, D3, D4, D5]
-                0b00000000_00000000_00000000_00111000_00101000_00111000_00000000_00000000
-            )
         );
 
         let expected_moves = [
@@ -125,18 +120,16 @@ mod tests {
 
     #[test]
     fn one_king_corner() {
-        let mut pos = Position::empty();
+        let pos = position![White King on A1];
-        pos.place_piece(Piece::king(Color::White), Square::A1)
-            .expect("Failed to place king on a1");
 
         let generator = KingMoveGenerator::new(&pos, Color::White);
 
-        let bb = generator.bitboard();
+        let generated_bitboard = generator.bitboard();
+        let expected_bitboard = bitboard![A2, B2, B1];
         assert_eq!(
-            bb,
+            generator.bitboard(),
-            BitBoard::new(
+            bitboard![A2, B2, B1],
-                0b00000000_00000000_00000000_00000000_00000000_00000000_00000011_00000010
+            "Generated:\n{generated_bitboard}\nExpected:\n{expected_bitboard}"
-            )
         );
 
         let expected_moves = [

board/src/move_generator/knight.rs

@@ -40,14 +40,14 @@ impl<'pos> MoveGeneratorInternal for KnightMoveGenerator<'pos> {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::{piece, Move, Square};
+    use crate::{piece, position, Move, Square};
     use std::collections::HashSet;
 
     #[test]
     fn one_knight() {
-        let mut pos = Position::empty();
+        let pos = position![
-        pos.place_piece(Piece::knight(Color::White), Square::E4)
+            White Knight on E4,
-            .expect("Failed to place knight on e4");
+        ];
 
         let generator = KnightMoveGenerator::new(&pos, Color::White);
 

board/src/move_generator/pawn.rs

@@ -17,9 +17,9 @@ struct MoveIterator(usize, usize);
 struct MoveGenerationParameters {
     starting_rank: BitBoard,
     promotion_rank: BitBoard,
-    push_shift: fn(BitBoard) -> BitBoard,
+    push_shift: fn(&BitBoard) -> BitBoard,
-    left_capture_shift: fn(BitBoard) -> BitBoard,
+    left_capture_shift: fn(&BitBoard) -> BitBoard,
-    right_capture_shift: fn(BitBoard) -> BitBoard,
+    right_capture_shift: fn(&BitBoard) -> BitBoard,
 }
 
 pub(super) struct PawnMoveGenerator<'pos> {
@@ -105,7 +105,7 @@ impl<'pos> PawnMoveGenerator<'pos> {
 
         let legal_1square_pushes = (parameters.push_shift)(bb) & empty_squares;
         let legal_2square_pushes =
-            (parameters.push_shift)(legal_1square_pushes & BitBoard::rank(2)) & empty_squares;
+            (parameters.push_shift)(&(legal_1square_pushes & BitBoard::rank(2))) & empty_squares;
 
         self.pushes = legal_1square_pushes | legal_2square_pushes;
     }
@@ -146,7 +146,7 @@ impl<'pos> PawnMoveGenerator<'pos> {
         for from_sq in bb.occupied_squares() {
             let pawn: BitBoard = from_sq.into();
 
-            let push = (parameters.push_shift)(pawn);
+            let push = (parameters.push_shift)(&pawn);
             if !(push & empty_squares).is_empty() {
                 let to_sq = push.occupied_squares().next().unwrap();
 
@@ -161,7 +161,7 @@ impl<'pos> PawnMoveGenerator<'pos> {
                 }
 
                 if !(pawn & parameters.starting_rank).is_empty() {
-                    let push = (parameters.push_shift)(push);
+                    let push = (parameters.push_shift)(&push);
                     if !(push & empty_squares).is_empty() {
                         let to_sq = push.occupied_squares().next().unwrap();
                         self.quiet_move_list()
@@ -171,8 +171,8 @@ impl<'pos> PawnMoveGenerator<'pos> {
             }
 
             for attack in [
-                (parameters.left_capture_shift)(pawn),
+                (parameters.left_capture_shift)(&pawn),
-                (parameters.right_capture_shift)(pawn),
+                (parameters.right_capture_shift)(&pawn),
             ] {
                 if !(attack & black_pieces).is_empty() {
                     let to_sq = attack.occupied_squares().next().unwrap();
@@ -245,17 +245,13 @@ impl<'pos> Iterator for PawnMoveGenerator<'pos> {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::piece::PlacedPiece;
     use crate::position::DiagramFormatter;
     use crate::{piece, Position, Square};
     use std::collections::HashSet;
 
     #[test]
     fn one_2square_push() {
-        let mut pos = Position::empty();
+        let pos = position![White Pawn on E2];
-
-        pos.place_piece(piece!(White Pawn), Square::E2)
-            .expect("Failed to place pawn on e2");
 
         let generator = PawnMoveGenerator::new(&pos, Color::White);
 
@@ -271,10 +267,7 @@ mod tests {
 
     #[test]
     fn one_1square_push() {
-        let mut pos = Position::empty();
+        let mut pos = position![White Pawn on E3];
-
-        pos.place_piece(Piece::pawn(Color::White), Square::E3)
-            .expect("Failed to place pawn on e3");
 
         let generator = PawnMoveGenerator::new(&pos, Color::White);
 
@@ -292,12 +285,10 @@ mod tests {
 
     #[test]
     fn one_obstructed_2square_push() {
-        let mut pos = Position::empty();
+        let pos = position![
-
+            White Pawn on E2,
-        pos.place_piece(Piece::pawn(Color::White), Square::E2)
+            White Knight on E4,
-            .expect("Failed to place pawn on e2");
+        ];
-        pos.place_piece(Piece::knight(Color::White), Square::E4)
-            .expect("Failed to place knight on e4");
 
         println!("{}", DiagramFormatter::new(&pos));
 
@@ -317,13 +308,10 @@ mod tests {
 
     #[test]
     fn one_obstructed_1square_push() {
-        let mut pos = Position::empty();
+        let mut pos = position![
-
+            White Pawn on E2,
-        pos.place_piece(Piece::pawn(Color::White), Square::E2)
+            White Knight on E3,
-            .expect("Failed to place pawn on e2");
+        ];
-        pos.place_piece(Piece::knight(Color::White), Square::E3)
-            .expect("Failed to place knight on e4");
-
         println!("{}", DiagramFormatter::new(&pos));
 
         let generator = PawnMoveGenerator::new(&pos, Color::White);
@@ -335,25 +323,21 @@ mod tests {
 
     #[test]
     fn one_attack() {
-        let mut pos = Position::empty();
+        let pos = position![
-        pos.place_piece(Piece::pawn(Color::White), Square::E4)
+            White Pawn on E4,
-            .expect("Failed to place pawn on e4");
+            White Bishop on E5,
-        pos.place_piece(Piece::bishop(Color::White), Square::E5)
+            Black Knight on D5,
-            .expect("Failed to place pawn on e4");
+        ];
-        pos.place_piece(Piece::knight(Color::Black), Square::D5)
-            .expect("Failed to place knight on d5");
-
         println!("{}", DiagramFormatter::new(&pos));
 
         let generator = PawnMoveGenerator::new(&pos, Color::White);
 
-        let expected_moves = HashSet::from_iter([MoveBuilder::new(
+        let expected_moves =
-            Piece::pawn(Color::White),
+            HashSet::from_iter(
-            Square::E4,
+                [MoveBuilder::new(piece!(White Pawn), Square::E4, Square::D5)
-            Square::D5,
+                    .capturing(piece!(Black Knight on D5))
-        )
+                    .build()],
-        .capturing(piece!(Black Knight on D5))
+            );
-        .build()]);
 
         let generated_moves: HashSet<Move> = generator.collect();
 
@@ -362,16 +346,12 @@ mod tests {
 
     #[test]
     fn one_double_attack() {
-        let mut pos = Position::empty();
+        let pos = position![
-        pos.place_piece(Piece::pawn(Color::White), Square::E4)
+            White Pawn on E4,
-            .expect("Failed to place pawn on e4");
+            White Bishop on E5,
-        pos.place_piece(Piece::bishop(Color::White), Square::E5)
+            Black Knight on D5,
-            .expect("Failed to place pawn on e4");
+            Black Queen on F5,
-        pos.place_piece(Piece::knight(Color::Black), Square::D5)
+        ];
-            .expect("Failed to place knight on d5");
-        pos.place_piece(Piece::queen(Color::Black), Square::F5)
-            .expect("Failed to place knight on f5");
-
         println!("{}", DiagramFormatter::new(&pos));
 
         let generator = PawnMoveGenerator::new(&pos, Color::White);

board/src/move_generator/queen.rs

@@ -66,27 +66,20 @@ impl<'pos> MoveGeneratorInternal for ClassicalMoveGenerator<'pos> {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::{
+    use crate::{piece, position, position::DiagramFormatter, BitBoard, Color};
-        piece::{Color, Piece},
-        position::DiagramFormatter,
-        BitBoard, Position, Square,
-    };
 
     #[test]
     fn classical_single_queen_bitboard() {
-        let mut pos = Position::empty();
+        let pos = position![White Queen on B2];
-        [(Piece::queen(Color::White), Square::A1)]
-            .into_iter()
-            .for_each(|(p, sq)| {
-                pos.place_piece(p, sq)
-                    .expect(&format!("Unable to place {:?} on {}", &p, &sq))
-            });
 
         let generator = ClassicalMoveGenerator::new(&pos, Color::White);
         let bitboard = generator.bitboard();
-        let expected = BitBoard::new(
+        let expected = bitboard![
-            0b10000001_01000001_00100001_00010001_00001001_00000101_00000011_11111110,
+            A2, C2, D2, E2, F2, G2, H2, // Rank
-        );
+            B1, B3, B4, B5, B6, B7, B8, // File
+            A1, C3, D4, E5, F6, G7, H8, // Diagonal
+            C1, A3 // Anti-diagonal
+        ];
 
         assert_eq!(
             bitboard, expected,
@@ -98,16 +91,10 @@ mod tests {
     /// Test that a rook can move up to, but not onto, a friendly piece.
     #[test]
     fn classical_single_queen_with_same_color_blocker_bitboard() {
-        let mut pos = Position::empty();
+        let pos = position![
-        [
+            White Queen on A1,
-            (Piece::queen(Color::White), Square::A1),
+            White Knight on E1,
-            (Piece::knight(Color::White), Square::E1),
+        ];
-        ]
-        .into_iter()
-        .for_each(|(p, sq)| {
-            pos.place_piece(p, sq)
-                .expect(&format!("Unable to place {} on {}", p, sq))
-        });
 
         println!("{}", DiagramFormatter::new(&pos));
 
@@ -127,44 +114,40 @@ mod tests {
     /// Test that a rook can move up to, and then capture, an enemy piece.
     #[test]
     fn classical_single_queen_with_opposing_color_blocker_bitboard() {
-        let mut pos = Position::empty();
+        let pos = position![
-        [
+            White Queen on B2,
-            (Piece::queen(Color::White), Square::A1),
+            Black Knight on E5,
-            (Piece::knight(Color::Black), Square::E5),
+        ];
-        ]
+        println!("{}", DiagramFormatter::new(&pos));
-        .into_iter()
-        .for_each(|(p, sq)| {
-            pos.place_piece(p, sq)
-                .expect(&format!("Unable to place {} on {}", p, sq))
-        });
 
         let generator = ClassicalMoveGenerator::new(&pos, Color::White);
 
         assert_eq!(
             generator.bitboard(),
-            BitBoard::new(
+            bitboard![
-                0b00000001_00000001_00000001_00010001_00001001_00000101_00000011_11111110,
+                A2, C2, D2, E2, F2, G2, H2, // Rank
-            )
+                B1, B3, B4, B5, B6, B7, B8, // File
+                A1, C3, D4, E5, // Diagonal
+                C1, A3 // Anti-diagonal
+            ]
         );
     }
 
     #[test]
     fn classical_single_queen_in_center() {
-        let mut pos = Position::empty();
+        let pos = position![White Queen on D3];
-        [(Piece::queen(Color::White), Square::E4)]
+        println!("{}", DiagramFormatter::new(&pos));
-            .into_iter()
-            .for_each(|(p, sq)| {
-                pos.place_piece(p, sq)
-                    .expect(&format!("Unable to place {} on {}", p, sq))
-            });
 
         let generator = ClassicalMoveGenerator::new(&pos, Color::White);
 
         assert_eq!(
             generator.bitboard(),
-            BitBoard::new(
+            bitboard![
-                0b00010001_10010010_01010100_00111000_11101111_00111000_01010100_10010010
+                A3, B3, C3, E3, F3, G3, H3, // Rank
-            )
+                D1, D2, D4, D5, D6, D7, D8, // File
+                B1, C2, E4, F5, G6, H7, // Diagonal
+                F1, E2, C4, B5, A6, // Anti-diagonal
+            ]
         );
     }
 }

board/src/move_generator/rook.rs

@@ -63,44 +63,29 @@ impl<'pos> MoveGeneratorInternal for ClassicalMoveGenerator<'pos> {
 mod tests {
     use super::*;
     use crate::{
-        piece::{Color, Piece},
+        piece::Piece, position, position::DiagramFormatter, BitBoard, Color, Position, Square,
-        position::DiagramFormatter,
-        BitBoard, Position, Square,
     };
 
     #[test]
     fn classical_single_rook_bitboard() {
-        let mut pos = Position::empty();
+        let pos = position![White Rook on A2];
-        [(Piece::rook(Color::White), Square::A1)]
+        println!("{}", DiagramFormatter::new(&pos));
-            .into_iter()
-            .for_each(|(p, sq)| {
-                pos.place_piece(p, sq)
-                    .expect(&format!("Unable to place {:?} on {}", &p, &sq))
-            });
 
         let generator = ClassicalMoveGenerator::new(&pos, Color::White);
 
         assert_eq!(
             generator.bitboard(),
-            BitBoard::new(
+            bitboard![A1, A3, A4, A5, A6, A7, A8, B2, C2, D2, E2, F2, G2, H2]
-                0b00000001_00000001_00000001_00000001_00000001_00000001_00000001_11111110
-            )
         );
     }
 
     /// Test that a rook can move up to, but not onto, a friendly piece.
     #[test]
     fn classical_single_rook_with_same_color_blocker_bitboard() {
-        let mut pos = Position::empty();
+        let mut pos = position![
-        [
+            White Rook on A1,
-            (Piece::rook(Color::White), Square::A1),
+            White Knight on E1,
-            (Piece::knight(Color::White), Square::E1),
+        ];
-        ]
-        .into_iter()
-        .for_each(|(p, sq)| {
-            pos.place_piece(p, sq)
-                .expect(&format!("Unable to place {} on {}", p, sq))
-        });
 
         println!("{}", DiagramFormatter::new(&pos));
 
@@ -117,44 +102,28 @@ mod tests {
     /// Test that a rook can move up to, and then capture, an enemy piece.
     #[test]
     fn classical_single_rook_with_opposing_color_blocker_bitboard() {
-        let mut pos = Position::empty();
+        let pos = position![
-        [
+            White Rook on A1,
-            (Piece::rook(Color::White), Square::A1),
+            Black Knight on E1,
-            (Piece::knight(Color::Black), Square::E1),
+        ];
-        ]
-        .into_iter()
-        .for_each(|(p, sq)| {
-            pos.place_piece(p, sq)
-                .expect(&format!("Unable to place {} on {}", p, sq))
-        });
 
         let generator = ClassicalMoveGenerator::new(&pos, Color::White);
 
         assert_eq!(
             generator.bitboard(),
-            BitBoard::new(
+            bitboard![A2, A3, A4, A5, A6, A7, A8, B1, C1, D1, E1]
-                0b00000001_00000001_00000001_00000001_00000001_00000001_00000001_00011110
-            )
         );
     }
 
     #[test]
     fn classical_single_rook_in_center() {
-        let mut pos = Position::empty();
+        let pos = position![White Rook on D4];
-        [(Piece::rook(Color::White), Square::E4)]
-            .into_iter()
-            .for_each(|(p, sq)| {
-                pos.place_piece(p, sq)
-                    .expect(&format!("Unable to place {} on {}", p, sq))
-            });
 
         let generator = ClassicalMoveGenerator::new(&pos, Color::White);
 
         assert_eq!(
             generator.bitboard(),
-            BitBoard::new(
+            bitboard![A4, B4, C4, E4, F4, G4, H4, D1, D2, D3, D5, D6, D7, D8]
-                0b00010000_00010000_00010000_00010000_11101111_00010000_00010000_00010000
-            )
         );
     }
 }

board/src/piece.rs

@@ -122,11 +122,6 @@ impl fmt::Display for Shape {
     }
 }
 
-#[derive(Debug, Eq, PartialEq)]
-pub enum PiecePlacementError {
-    ExistsOnSquare,
-}
-
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 pub struct Piece {
     color: Color,
@@ -252,6 +247,12 @@ impl fmt::Display for PlacedPiece {
     }
 }
 
+impl From<(&Square, &Piece)> for PlacedPiece {
+    fn from(value: (&Square, &Piece)) -> Self {
+        PlacedPiece::new(*value.1, *value.0)
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

board/src/position/builders.rs

@@ -0,0 +1,83 @@
+// Eryn Wells <eryn@erynwells.me>
+
+use super::{flags::Flags, piece_sets::PieceBitBoards};
+use crate::{
+    piece::{PlacedPiece, Shape},
+    square::Rank,
+    BitBoard, Color, MakeMoveError, Move, Piece, Position, Square,
+};
+use std::collections::BTreeMap;
+
+#[derive(Clone)]
+pub struct Builder {
+    player_to_move: Color,
+    flags: Flags,
+    pieces: BTreeMap<Square, Piece>,
+    kings: [Square; 2],
+}
+
+impl Builder {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn place_piece(&mut self, piece: PlacedPiece) -> &mut Self {
+        let square = piece.square();
+
+        if piece.shape() == Shape::King {
+            let color_index: usize = piece.color() as usize;
+            self.pieces.remove(&self.kings[color_index]);
+            self.kings[color_index] = square;
+        }
+
+        self.pieces.insert(square, piece.piece());
+
+        self
+    }
+
+    pub fn build(&self) -> Position {
+        let pieces = PieceBitBoards::from_iter(
+            self.pieces
+                .iter()
+                .map(PlacedPiece::from)
+                .filter(Self::is_piece_placement_valid),
+        );
+
+        Position::new(self.player_to_move, self.flags, pieces, None)
+    }
+}
+
+impl Builder {
+    fn is_piece_placement_valid(piece: &PlacedPiece) -> bool {
+        if piece.shape() == Shape::Pawn {
+            // Pawns cannot be placed on the first (back) rank of their side,
+            // and cannot be placed on the final rank without a promotion.
+            let rank = piece.square().rank();
+            return rank != Rank::One && rank != Rank::Eight;
+        }
+
+        true
+    }
+}
+
+impl Default for Builder {
+    fn default() -> Self {
+        let pieces = BTreeMap::from_iter([
+            (
+                Square::KING_STARTING_SQUARES[Color::White as usize],
+                piece!(White King),
+            ),
+            (
+                Square::KING_STARTING_SQUARES[Color::Black as usize],
+                piece!(Black King),
+            ),
+        ]);
+
+        Self {
+            player_to_move: Color::White,
+            flags: Flags::default(),
+            pieces: pieces,
+            kings: Square::KING_STARTING_SQUARES,
+        }
+    }
+}

board/src/position/diagram_formatter.rs

@@ -42,7 +42,7 @@ impl<'a> fmt::Display for DiagramFormatter<'a> {
 mod tests {
     use super::*;
     use crate::piece::{Color, Piece};
-    use crate::Position;
+    use crate::{Position, PositionBuilder};
 
     #[test]
     fn empty() {
@@ -53,13 +53,9 @@ mod tests {
 
     #[test]
     fn one_king() {
-        let mut pos = Position::empty();
+        let pos = PositionBuilder::new()
-        pos.place_piece(
+            .place_piece(piece!(Black King on H3))
-            Piece::king(Color::Black),
+            .build();
-            Square::from_algebraic_str("h3").expect("h3"),
-        )
-        .expect("Unable to place piece");
-
         let diagram = DiagramFormatter(&pos);
         println!("{}", diagram);
     }

board/src/position/mod.rs

@@ -1,10 +1,13 @@
 // Eryn Wells <eryn@erynwells.me>
 
+mod builders;
 mod diagram_formatter;
 mod flags;
+mod piece_sets;
 mod pieces;
 mod position;
 
+pub use builders::Builder as PositionBuilder;
 pub use diagram_formatter::DiagramFormatter;
 pub use pieces::Pieces;
 pub use position::Position;

board/src/position/piece_sets.rs

@@ -0,0 +1,149 @@
+// Eryn Wells <eryn@erynwells.me>
+
+use crate::{
+    piece::{Piece, PlacedPiece},
+    BitBoard, Color, Square,
+};
+
+#[derive(Debug, Eq, PartialEq)]
+pub enum PlacePieceStrategy {
+    Replace,
+    PreserveExisting,
+}
+
+#[derive(Debug, Eq, PartialEq)]
+pub enum PlacePieceError {
+    ExisitingPiece,
+}
+
+impl Default for PlacePieceStrategy {
+    fn default() -> Self {
+        Self::Replace
+    }
+}
+
+#[derive(Clone, Debug, Default, Eq, Hash, PartialEq)]
+pub(super) struct PieceBitBoards {
+    by_color: ByColor,
+    by_color_and_shape: ByColorAndShape,
+}
+
+#[derive(Clone, Debug, Default, Eq, Hash, PartialEq)]
+struct ByColor(BitBoard, [BitBoard; 2]);
+
+#[derive(Clone, Debug, Default, Eq, Hash, PartialEq)]
+struct ByColorAndShape([[BitBoard; 6]; 2]);
+
+impl PieceBitBoards {
+    pub(super) fn new(pieces: [[BitBoard; 6]; 2]) -> Self {
+        let white_pieces = pieces[Color::White as usize]
+            .iter()
+            .fold(BitBoard::empty(), std::ops::BitOr::bitor);
+        let black_pieces = pieces[Color::White as usize]
+            .iter()
+            .fold(BitBoard::empty(), std::ops::BitOr::bitor);
+        let all_pieces = white_pieces | black_pieces;
+
+        Self {
+            by_color: ByColor(all_pieces, [white_pieces, black_pieces]),
+            by_color_and_shape: ByColorAndShape(pieces),
+        }
+    }
+
+    pub(super) fn all_pieces(&self) -> &BitBoard {
+        self.by_color.all()
+    }
+
+    pub(super) fn all_pieces_of_color(&self, color: Color) -> &BitBoard {
+        self.by_color.bitboard(color)
+    }
+
+    pub(super) fn bitboard_for_color(&self, color: Color) -> &BitBoard {
+        self.by_color.bitboard(color)
+    }
+
+    pub(super) fn bitboard_for_color_mut(&mut self, color: Color) -> &mut BitBoard {
+        self.by_color.bitboard_mut(color)
+    }
+
+    pub(super) fn bitboard_for_piece(&self, piece: Piece) -> &BitBoard {
+        self.by_color_and_shape.bitboard_for_piece(piece)
+    }
+
+    pub(super) fn bitboard_for_piece_mut(&mut self, piece: Piece) -> &mut BitBoard {
+        self.by_color_and_shape.bitboard_for_piece_mut(piece)
+    }
+
+    pub(super) fn place_piece(&mut self, piece: PlacedPiece) -> Result<(), PlacePieceError> {
+        self.place_piece_with_strategy(piece, Default::default())
+    }
+
+    pub(super) fn place_piece_with_strategy(
+        &mut self,
+        piece: PlacedPiece,
+        strategy: PlacePieceStrategy,
+    ) -> Result<(), PlacePieceError> {
+        let color = piece.color();
+        let square = piece.square();
+
+        if self.by_color.bitboard(color).is_set(piece.square()) {
+            match strategy {
+                PlacePieceStrategy::Replace => todo!(),
+                PlacePieceStrategy::PreserveExisting => {
+                    return Err(PlacePieceError::ExisitingPiece)
+                }
+            }
+        }
+
+        self.by_color.set_square(square, color);
+        self.bitboard_for_piece_mut(piece.piece())
+            .set_square(square);
+
+        Ok(())
+    }
+}
+
+impl FromIterator<PlacedPiece> for PieceBitBoards {
+    fn from_iter<T: IntoIterator<Item = PlacedPiece>>(iter: T) -> Self {
+        let mut pieces = Self::default();
+
+        for piece in iter {
+            let _ = pieces.place_piece(piece);
+        }
+
+        pieces
+    }
+}
+
+impl ByColor {
+    fn all(&self) -> &BitBoard {
+        &self.0
+    }
+
+    pub(super) fn bitboard(&self, color: Color) -> &BitBoard {
+        &self.1[color as usize]
+    }
+
+    pub(super) fn bitboard_mut(&mut self, color: Color) -> &mut BitBoard {
+        &mut self.1[color as usize]
+    }
+
+    fn set_square(&mut self, square: Square, color: Color) {
+        self.0.set_square(square);
+        self.1[color as usize].set_square(square)
+    }
+}
+
+impl ByColorAndShape {
+    fn bitboard_for_piece(&self, piece: Piece) -> &BitBoard {
+        &self.0[piece.color() as usize][piece.shape() as usize]
+    }
+
+    fn bitboard_for_piece_mut(&mut self, piece: Piece) -> &mut BitBoard {
+        &mut self.0[piece.color() as usize][piece.shape() as usize]
+    }
+
+    fn set_square(&mut self, square: Square, piece: Piece) {
+        self.bitboard_for_piece_mut(piece).set_square(square);
+    }
+}

board/src/position/pieces.rs

@@ -38,7 +38,7 @@ impl<'a> Iterator for Pieces<'a> {
         }
 
         let mut current_shape: Option<Shape> = None;
-        let mut next_nonempty_bitboard: Option<BitBoard> = None;
+        let mut next_nonempty_bitboard: Option<&BitBoard> = None;
 
         while let Some(shape) = self.shape_iterator.next() {
             let piece = Piece::new(self.color, *shape);
@@ -76,15 +76,10 @@ impl<'a> Iterator for Pieces<'a> {
 mod tests {
     use super::*;
     use crate::piece::{Color, Piece, Shape};
-    use crate::Position;
     use crate::Square;
+    use crate::{Position, PositionBuilder};
     use std::collections::HashSet;
 
-    fn place_piece_in_position(pos: &mut Position, piece: Piece, sq: Square) {
-        pos.place_piece(piece, sq)
-            .expect("Unable to place {piece:?} queen on {sq}");
-    }
-
     #[test]
     fn empty() {
         let pos = Position::empty();
@@ -94,40 +89,45 @@ mod tests {
 
     #[test]
     fn one() {
-        let sq = Square::E4;
+        let pos = PositionBuilder::new()
-
+            .place_piece(piece!(White Queen on E4))
-        let mut pos = Position::empty();
+            .build();
-        place_piece_in_position(&mut pos, Piece::new(Color::White, Shape::Queen), Square::E4);
+        println!("{:#?}", &pos);
-        println!("{:?}", &pos);
 
         let mut pieces = pos.pieces(Color::White);
-        assert_eq!(
+        assert_eq!(pieces.next(), Some(piece!(White Queen on E4)));
-            pieces.next(),
+        assert_eq!(pieces.next(), Some(piece!(White King on E1)));
-            Some(PlacedPiece::new(Piece::new(Color::White, Shape::Queen), sq))
-        );
         assert_eq!(pieces.next(), None);
     }
 
     #[test]
     fn multiple_pieces() {
-        let mut pos = Position::empty();
+        let pos = PositionBuilder::new()
-
+            .place_piece(piece!(White Queen on E4))
-        place_piece_in_position(&mut pos, Piece::new(Color::White, Shape::Queen), Square::E4);
+            .place_piece(piece!(White King on A1))
-        place_piece_in_position(&mut pos, Piece::new(Color::White, Shape::King), Square::E1);
+            .place_piece(piece!(White Pawn on B2))
-        place_piece_in_position(&mut pos, Piece::new(Color::White, Shape::Pawn), Square::B2);
+            .place_piece(piece!(White Pawn on C2))
-        place_piece_in_position(&mut pos, Piece::new(Color::White, Shape::Pawn), Square::C2);
+            .build();
-
+        println!("{}", crate::position::DiagramFormatter::new(&pos));
-        println!("{:?}", &pos);
 
         let expected_placed_pieces = HashSet::from([
-            PlacedPiece::new(Piece::new(Color::White, Shape::Queen), Square::E4),
+            piece!(White Queen on E4),
-            PlacedPiece::new(Piece::new(Color::White, Shape::King), Square::E1),
+            piece!(White King on A1),
-            PlacedPiece::new(Piece::new(Color::White, Shape::Pawn), Square::B2),
+            piece!(White Pawn on B2),
-            PlacedPiece::new(Piece::new(Color::White, Shape::Pawn), Square::C2),
+            piece!(White Pawn on C2),
         ]);
 
         let placed_pieces = HashSet::from_iter(pos.pieces(Color::White));
 
-        assert_eq!(placed_pieces, expected_placed_pieces);
+        assert_eq!(
+            placed_pieces,
+            expected_placed_pieces,
+            "{:#?}",
+            placed_pieces
+                .symmetric_difference(&expected_placed_pieces)
+                .into_iter()
+                .map(|pp| format!("{}", pp))
+                .collect::<Vec<String>>()
+        );
     }
 }

board/src/position/position.rs

@@ -1,11 +1,11 @@
 // Eryn Wells <eryn@erynwells.me>
 
-use super::{flags::Flags, Pieces};
+use super::{flags::Flags, piece_sets::PieceBitBoards, Pieces};
 use crate::{
     move_generator::Moves,
-    piece::{Color, Piece, PiecePlacementError, PlacedPiece, Shape},
+    piece::{Color, Piece, PlacedPiece, Shape},
     sight::Sight,
-    BitBoard, Square,
+    BitBoard, Move, Square,
 };
 use std::cell::OnceCell;
 
@@ -21,15 +21,8 @@ pub(crate) enum BoardSide {
 pub struct Position {
     color_to_move: Color,
     flags: Flags,
-
+    pieces: PieceBitBoards,
-    /// Composite bitboards for all the pieces of a particular color.
-    pieces_per_color: [BitBoard; 2],
-
-    /// Bitboards representing positions of particular piece types per color.
-    pieces_per_type: [[BitBoard; 6]; 2],
-
     en_passant_square: Option<Square>,
-
     sight: [OnceCell<BitBoard>; 2],
 }
 
@@ -38,32 +31,14 @@ impl Position {
         Position {
             color_to_move: Color::White,
             flags: Default::default(),
-            pieces_per_color: [BitBoard::empty(); 2],
+            pieces: PieceBitBoards::default(),
-            pieces_per_type: [
-                [
-                    BitBoard::empty(),
-                    BitBoard::empty(),
-                    BitBoard::empty(),
-                    BitBoard::empty(),
-                    BitBoard::empty(),
-                    BitBoard::empty(),
-                ],
-                [
-                    BitBoard::empty(),
-                    BitBoard::empty(),
-                    BitBoard::empty(),
-                    BitBoard::empty(),
-                    BitBoard::empty(),
-                    BitBoard::empty(),
-                ],
-            ],
             en_passant_square: None,
             sight: [OnceCell::new(), OnceCell::new()],
         }
     }
 
     /// Return a starting position.
-    pub fn starting() -> Position {
+    pub fn starting() -> Self {
         let white_pieces = [
             BitBoard::new(0x00FF000000000000),
             BitBoard::new(0x4200000000000000),
@@ -82,19 +57,19 @@ impl Position {
             BitBoard::new(0x0008),
         ];
 
-        Position {
+        Self {
             color_to_move: Color::White,
-            flags: Default::default(),
+            flags: Flags::default(),
-            pieces_per_color: [
+            pieces: PieceBitBoards::new([white_pieces, black_pieces]),
-                white_pieces.iter().fold(BitBoard::empty(), |a, b| a | *b),
-                black_pieces.iter().fold(BitBoard::empty(), |a, b| a | *b),
-            ],
-            pieces_per_type: [white_pieces, black_pieces],
             en_passant_square: None,
             sight: [OnceCell::new(), OnceCell::new()],
         }
     }
 
+    pub fn player_to_move(&self) -> Color {
+        self.color_to_move
+    }
+
     /// Returns true if the player has the right to castle on the given side of
     /// the board.
     ///
@@ -112,39 +87,28 @@ impl Position {
         self.flags.player_has_right_to_castle(color, side)
     }
 
-    pub fn place_piece(&mut self, piece: Piece, square: Square) -> Result<(), PiecePlacementError> {
-        let type_bb = self.bitboard_for_piece_mut(piece);
-
-        if type_bb.is_set(square) {
-            return Err(PiecePlacementError::ExistsOnSquare);
-        }
-
-        type_bb.set_square(square);
-
-        self.bitboard_for_color_mut(piece.color())
-            .set_square(square);
-
-        Ok(())
-    }
-
     pub fn moves(&self) -> Moves {
         Moves::new(self, self.color_to_move)
     }
 
     /// Return a BitBoard representing the set of squares containing a piece.
     #[inline]
-    pub(crate) fn occupied_squares(&self) -> BitBoard {
+    pub(crate) fn occupied_squares(&self) -> &BitBoard {
-        self.pieces_per_color[Color::White as usize] | self.pieces_per_color[Color::Black as usize]
+        &self.pieces.all_pieces()
     }
 
     #[inline]
-    pub(crate) fn friendly_pieces(&self) -> BitBoard {
+    pub(crate) fn friendly_pieces(&self) -> &BitBoard {
-        self.bitboard_for_color(self.color_to_move)
+        self.pieces.all_pieces_of_color(self.color_to_move)
     }
 
     #[inline]
-    pub(crate) fn opposing_pieces(&self) -> BitBoard {
+    pub(crate) fn opposing_pieces(&self) -> &BitBoard {
-        self.bitboard_for_color(self.color_to_move.other())
+        self.pieces.all_pieces_of_color(self.color_to_move.other())
+    }
+
+    pub(crate) fn all_pieces(&self) -> (&BitBoard, &BitBoard) {
+        (self.friendly_pieces(), self.opposing_pieces())
     }
 
     /// Return a BitBoard representing the set of squares containing a piece.
@@ -154,28 +118,11 @@ impl Position {
         !self.occupied_squares()
     }
 
-    pub(crate) fn bitboard_for_piece(&self, piece: Piece) -> BitBoard {
-        self.pieces_per_type[piece.color() as usize][piece.shape() as usize]
-    }
-
-    fn bitboard_for_piece_mut(&mut self, piece: Piece) -> &mut BitBoard {
-        &mut self.pieces_per_type[piece.color() as usize][piece.shape() as usize]
-    }
-
-    pub(crate) fn bitboard_for_color(&self, color: Color) -> BitBoard {
-        self.pieces_per_color[color as usize]
-    }
-
-    fn bitboard_for_color_mut(&mut self, color: Color) -> &mut BitBoard {
-        &mut self.pieces_per_color[color as usize]
-    }
-
     pub fn piece_on_square(&self, sq: Square) -> Option<PlacedPiece> {
         for color in Color::iter() {
             for shape in Shape::iter() {
                 let piece = Piece::new(color, *shape);
-                let bb = self.bitboard_for_piece(piece);
+                if self.pieces.bitboard_for_piece(piece).is_set(sq) {
-                if bb.is_set(sq) {
                     return Some(PlacedPiece::new(piece, sq));
                 }
             }
@@ -206,11 +153,49 @@ impl Position {
     }
 
     fn king_square(&self) -> Square {
-        self.bitboard_for_piece(Piece::king(self.color_to_move))
+        self.pieces
+            .bitboard_for_piece(Piece::king(self.color_to_move))
             .occupied_squares()
             .next()
             .unwrap()
     }
+
+    pub(crate) fn move_is_legal(&self, mv: Move) -> bool {
+        true
+    }
+}
+
+// crate::position methods
+impl Position {
+    pub(super) fn new(
+        player_to_move: Color,
+        flags: Flags,
+        pieces: PieceBitBoards,
+        en_passant_square: Option<Square>,
+    ) -> Self {
+        Self {
+            color_to_move: player_to_move,
+            flags,
+            en_passant_square,
+            pieces,
+            sight: [OnceCell::new(), OnceCell::new()],
+        }
+    }
+
+    pub(super) fn flags(&self) -> Flags {
+        self.flags
+    }
+}
+
+// crate methods
+impl Position {
+    pub(crate) fn bitboard_for_color(&self, color: Color) -> &BitBoard {
+        self.pieces.bitboard_for_color(color)
+    }
+
+    pub(crate) fn bitboard_for_piece(&self, piece: Piece) -> &BitBoard {
+        self.pieces.bitboard_for_piece(piece)
+    }
 }
 
 #[cfg(test)]
@@ -226,46 +211,9 @@ impl Default for Position {
     }
 }
 
-impl FromIterator<PlacedPiece> for Position {
-    fn from_iter<T: IntoIterator<Item = PlacedPiece>>(iter: T) -> Self {
-        let mut position = Position::empty();
-        for placed_piece in iter {
-            _ = position.place_piece(placed_piece.piece(), placed_piece.square());
-        }
-
-        position
-    }
-}
-
 #[cfg(test)]
 mod tests {
-    use super::*;
+    use crate::position;
-    use crate::piece::Shape;
-
-    #[test]
-    fn place_piece() {
-        let mut position = Position::empty();
-
-        let piece = Piece::new(Color::White, Shape::Queen);
-        let square = Square::E4;
-
-        position
-            .place_piece(piece, square)
-            .expect("Unable to place white queen on e4");
-
-        assert_eq!(
-            position.bitboard_for_color(piece.color()).clone(),
-            BitBoard::new(1 << 28)
-        );
-        assert_eq!(
-            position.bitboard_for_piece(piece).clone(),
-            BitBoard::new(1 << 28)
-        );
-
-        position
-            .place_piece(piece, square)
-            .expect_err("Placed white queen on e4 a second time?!");
-    }
 
     #[test]
     fn king_is_in_check() {