pgn2 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 963f48df8fbfe5d69097030a9434a05b82e211c235772273f03bd11178afb8a5
-  data.tar.gz: 6bc38e0387e7061e3649fe52d22e5f01dabdc7029f8c27294d56b62a3779a76c
+  metadata.gz: 33036a2920baf0e170efc5e1c387c2a53ae91fe19ad19cf745d4d6f049c9fe20
+  data.tar.gz: 93ccbe0289a72f4af5fb8367a4d1f5bdc0c1d5eb77f1a65e3381b7d17f5d3822
 SHA512:
-  metadata.gz: e81b88377f5d1ab6102a5b15d4d006feb4201647125b5b3d434b826dfa55cac60c82048fc8d4d2a4c8aa7d1600d6ba4edd472f27d063d258703d8e225c0832cc
-  data.tar.gz: 06cb00152b81f2124749fbc743356a25a7ee44e049c7779fb397660a84ebfefee8afcf4679f86ac633ff12b771db007123308cd5c65520ae8329e7334b340ab9
+  metadata.gz: 25ed517772982909d896b4b372308d235574db54aa44f3ff98f5201f9055120fc64d19fcd634c6676f7bfb66cf5e4de483a2a9ae13293b3162781339434bfac1
+  data.tar.gz: bf2a935f6aa4fedffb5976b0febc5eb351354165275d8b248eac99f7a713d74cf6acb3cb9e0be51c6030a55481663173ab5c9008cf5dfa67904bd09ac4e271f5

data/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 1.3.0 (2026-08-13)
+
+### Summary
+
+Replay (move-application) board-representation rewrite: `PGN::Board`
+internals move to the classic 0x88 scheme (a 128-cell array indexed by
+`rank*16+file`) and `PGN::MoveCalculator` works entirely in single-integer
+square indices, so the replay hot path no longer allocates `[file,rank]`
+coordinate arrays or square-name strings. No public API changes; serialized
+PGN/FEN output stays byte-identical.
+
+### Changed
+- **`PGN::Board`**: internals rewritten to a 0x88 array (`@cells`, 128
+  entries). The public file-major `squares` 8x8 API, `at` (string/coord
+  overloads), `update`, `change!`, `position_for`, `coordinates_for`, and
+  `dup` are preserved (computed/translated at the API boundary, off the
+  hot path). New internal 0x88 accessors `index_of`, `index_for`, `at_index`,
+  `update_index`, and `apply!` (integer-keyed batch update) serve the hot
+  path. `dup` copies the 128-cell array (cheaper than the prior column COW:
+  136 → 91 objects / 10336 → 3856 bytes per 45 dupes).
+- **`PGN::MoveCalculator`**: rewritten to address squares as 0x88 integer
+  indices throughout. `#compute_origin` returns an index; `#changes` is an
+  integer-keyed hash applied via `Board#apply!`; ray stepping (`first_piece`)
+  and off-board checks use a single integer add and the `(idx & 0x88).zero?`
+  bitmask (≈1.6x faster than a 0..7 four-integer bounds check, measured);
+  `castling_restrictions`/`en_passant_*` use integer corner indices. The
+  public `#origin` reader still returns an algebraic square string. Scan and
+  disambiguation algorithms are unchanged, so output is byte-identical.
+- **Plan B (piece-location index) — attempted, rejected**: a `piece → 0x88
+  indices` index maintained in `update`/`apply!`, used for O(1)
+  slider/leaper/king origin lookups, was implemented on top of the 0x88
+  board and passed all 182 specs, but regressed: replay 526 → 727 µs/i
+  (+38% slower), allocations 976 → 1591 objects (+63%). `Board#dup` (called
+  every move) must clone the index (≈12 piece arrays: Board#dup 91 → 676
+  objects), and every move pays per-update index maintenance that pawns —
+  the most common move type, whose origins are geometry-fixed and can't use
+  the index — pay for no benefit. The index helps move-*generation*
+  libraries (chess.js, python-chess) that enumerate all legal moves, but
+  not replay, which validates one given move where ray-scanning from the
+  destination is already cheap. Reverted; the 0x88 board alone is the
+  winner. Rationale recorded in `TODO.md`.
+- Performance vs 1.2.1 (immortal game, 45 plies; A/B batched median, 200
+  replies × 7, fresh process each): replay throughput 798 → 535 µs/i
+  (+49%); replay allocations 1571 → 976 objects (−38%) and 92440 → 62064
+  bytes (−33%). Full pipeline (`bench/profile_parse.rb`, 500 games):
+  parse+replay throughput 659 → 534 ms/i (+23%), allocations 1101586 →
+  831530 objects (−24.5%) and 62164136 → 47966112 bytes (−22.8%);
+  parse-only unchanged. 182 specs pass; byte-identical FEN/PGN output;
+  zero new rubocop offenses vs 1.2.1 (the rewrite is shorter on
+  ClassLength/AbcSize and leaves the same pre-existing metric offenses on
+  the same methods).
+
 ## 1.2.1 (2026-08-13)
 
 ### Summary

data/README.md

@@ -169,13 +169,13 @@ Move pipeline — immortal game, 45 plies (`bench/profile_moves.rb`):
 
 | Metric | original `pgn` | pgn2 | Δ |
 |---|---:|---:|---:|
-| Replay allocations (objects) | 5124 | 1710 | -3414 (-66.7%) |
-| Replay allocations (bytes) | 262608 | 103760 | -158848 (-60.5%) |
-| `Board#dup` x45 (objects) | 451 | 136 | -315 (-69.8%) |
-| `Board#dup` x45 (bytes) | 43096 | 10336 | -32760 (-76.0%) |
+| Replay allocations (objects) | 5124 | 976 | -4148 (-80.9%) |
+| Replay allocations (bytes) | 262608 | 62064 | -200544 (-76.4%) |
+| `Board#dup` x45 (objects) | 451 | 91 | -360 (-79.8%) |
+| `Board#dup` x45 (bytes) | 43096 | 3856 | -39240 (-91.1%) |
 | `Board#at(str)` x1000 (objects) | 6000 | 0 | -6000 (-100%) |
 | `Board#at(str)` x1000 (bytes) | 240000 | 0 | -240000 (-100%) |
-| Replay throughput | 841 µs/i | 766 µs/i | ~1.10x faster |
+| Replay throughput | 841 µs/i | 517 µs/i | ~1.63x faster |
 
 Parser — 500 immortal games (`bench/profile_parse.rb`):
 
@@ -183,10 +183,10 @@ Parser — 500 immortal games (`bench/profile_parse.rb`):
 |---|---:|---:|---:|
 | Parse-only allocations (objects) | 1248065 | 347037 | -901028 (-72.2%) |
 | Parse-only allocations (bytes) | 120370470 | 17977414 | -102393056 (-85.1%) |
-| Parse + replay allocations (objects) | 3778073 | 1170586 | -2607487 (-69.0%) |
-| Parse + replay allocations (bytes) | 249570048 | 67804136 | -181765912 (-72.8%) |
+| Parse + replay allocations (objects) | 3778073 | 831530 | -2946543 (-78.0%) |
+| Parse + replay allocations (bytes) | 249570048 | 47966112 | -201603936 (-80.8%) |
 | Parse-only throughput | 1461 ms/i | 305 ms/i | ~4.8x faster |
-| Parse + replay throughput | 1938 ms/i | 816 ms/i | ~2.4x faster |
+| Parse + replay throughput | 1938 ms/i | 534 ms/i | ~3.6x faster |
 
 What changed to get there:
 
@@ -216,6 +216,29 @@ What changed to get there:
     tuple, so the parser hot path now allocates only the single `[type, value]`
     array Racc requires per token. Cuts parse allocations ~42% (603537 → 347037
     objects for 500 games).
+13. `PGN::MoveCalculator#valid_square?` — integer bounds (`file >= 0 && file < 8`)
+    instead of `(0..7).include?` (≈3.4x faster per call, zero-alloc, in the
+    board-scan inner loops); `#compute_origin` — string `case` dispatch instead
+    of regex `/[brq]/i` matches; `#first_piece` — returns only the `[file, rank]`
+    square via a `piece_at` helper instead of a `[piece, square]` tuple. Replay
+    throughput +8.2% (766 → 741 µs/i), replay allocations −8% (1710 → 1571
+    objects). Board-scanning origin lookup is ~46% of replay CPU; the
+    piece-location-index rewrite that would cut it remains deferred.
+14. `PGN::Board` / `PGN::MoveCalculator` — 0x88 board representation. `Board`
+    internals are now a 128-cell array indexed by `rank*16+file` (the classic
+    0x88 scheme), and `MoveCalculator` works entirely in single-integer square
+    indices via `Board#at_index`/`#apply!`, so the replay hot path no longer
+    allocates `[file,rank]` coordinate arrays or square-name strings.
+    Off-board is a single bitmask (`(idx & 0x88).zero?`, ~1.6x faster than a
+    0..7 bounds check) and ray stepping is a single integer add. Algorithm
+    unchanged → byte-identical output. Replay throughput +49% (798 → 517 µs/i),
+    replay allocations −38% (1571 → 976 objects) / −33% (92440 → 62064 bytes),
+    parse+replay +21% throughput. A companion piece-location index (piece →
+    0x88 indices for O(1) origin/king lookups) was implemented on top, passed
+    all specs, but *regressed* (replay 526→727 µs/i, allocations +63%): `dup`
+    must clone the index every move and every move pays maintenance that pawns
+    (the common case, geometry-fixed origins) can't use — so it was rejected
+    and reverted. The 0x88 board alone is the winner.
 
 Public output (FEN, PGN) is byte-identical to the original gem; the full
 suite (182 examples) stays green. See `bench/IMPROVEMENTS.md` for the per-step

data/TODO.md

@@ -15,21 +15,33 @@
     `scan_one`'s `[type, m, discarded]` tuple to a single returned string
     (type/discarded stashed in ivars). The full `Token` is kept only for the
     `#tokens` spec helper. Parse allocations −42% (603537 → 347037 / 500 games).
-- Speed up replay via a board-representation rewrite (deferred "Approach B"):
-  per-line profiling shows the remaining replay allocations are architectural
-  — `MoveCalculator#first_piece` scan-return arrays (~5/ply, the #1 site) and
-  `Board#position_for` string joins (~3/ply). Do these as ONE coherent
-  rewrite (not separately, to avoid throwing away work):
-  (a) a piece-location index (piece → squares) so king/disambiguation/origin
-    lookups are O(1) instead of scanning 64 squares — kills `first_piece` scan
-    arrays AND the dominant replay compute (`valid_square?`/`at` ≈ 15/ply calls);
-  (b) a coordinate-only internal board (int square keys, no `"e4"` strings on
-    the hot path) — kills `position_for` strings + `changes` string keys.
-  Caveat: `change!`/`update`/`position_for`/`coordinates_for`/`squares` are
-  spec-tested public API, so the new representation must be additive (string
-  API kept). Realistic ceiling ~2× replay allocation + ~1.5–2× throughput;
-  medium-high risk (Board/MoveCalculator/Position/FEN). Only worth it given a
-  real hot-loop need (replay is already ~0.8 ms/ply).
+- Speed up replay via a board-representation rewrite ("Approach B"): done.
+  (b) ✓ (done in 1.3.0) Rewrote `Board` internals to the classic 0x88
+    representation (128-cell array indexed by `rank*16+file`) and rewrote
+    `MoveCalculator` to work entirely in single-integer square indices via
+    `Board#at_index`/`#apply!`, so the replay hot path no longer allocates
+    `[file,rank]` coordinate arrays or square-name strings. Off-board is a
+    single bitmask (`(idx & 0x88).zero?`, ~1.6x faster than a 0..7 bounds
+    check) and ray stepping is a single integer add. Algorithm unchanged, so
+    output is byte-identical. Measured (immortal game): replay 798→535 µs/i
+    (+49% throughput), allocations 1571→976 objects (−38%) / 92440→62064 bytes
+    (−33%); parse+replay +21% throughput. 182 specs green, 0 new rubocop
+    offenses vs main. The public string/coord API is preserved (additive).
+  (a) ✗ (attempted, rejected) A piece-location index (piece → 0x88 indices)
+    maintained in `update`/`apply!` and used for O(1) slider/leaper/king
+    origin lookups. Implemented on top of (b), all 182 specs green, but it
+    **regressed**: replay 526→727 µs/i (+38% slower), allocations 976→1591
+    objects (+63%). Root cause: `Board#dup` (called every move) must clone
+    the index (`transform_values(&:dup)` ≈ 12 piece arrays) — Board#dup went
+    91→676 objects — and every move pays per-update index maintenance
+    (`<<`/`delete`) that pawns (the most common move type, whose origins are
+    geometry-fixed and can't use the index) pay for no benefit. The index
+    helps sliders/leapers (minority of moves) but the dup + maintenance cost
+    is paid by every move. Conclusion: a global piece index is a loss for
+    replay (where only ONE given move is validated, so ray-scanning from the
+    destination is already cheap); it pays in move-*generation* libraries
+    (chess.js/python-chess) that enumerate ALL legal moves. Not worth a COW
+    variant either (maintenance + pawns). Reverted; (b) alone is the winner.
 - Replace the right-recursive `tag_section`/`variation_list` rules in
   `pgn_parser.y` with ordinary left-recursion plus one explicit `.reverse`
   at the point each list is consumed, so the legacy whittle-order

data/bench/baseline_moves.txt

@@ -1,12 +1,12 @@
 Workload: immortal game, 45 plies
 
 === 1. Replay allocations (45 plies, no parse) ===
-total_allocated objects: 1710
-total_allocated bytes:   103760
+total_allocated objects: 976
+total_allocated bytes:   62064
 
 === 2. Board#dup x45 (target of flat-board COW) ===
-total_allocated objects: 136
-total_allocated bytes:   10336
+total_allocated objects: 91
+total_allocated bytes:   3856
 
 === 3. Board#at(str) x1000 (target of coord-arithmetic at) ===
 total_allocated objects: 0
@@ -15,8 +15,8 @@ total_allocated bytes:   0
 === 4. Replay throughput (ips, excluding parse) ===
 ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +PRISM [x86_64-linux]
 Warming up --------------------------------------
-     replay immortal   112.000 i/100ms
+     replay immortal   193.000 i/100ms
 Calculating -------------------------------------
-     replay immortal      1.178k (± 4.6%) i/s  (848.64 μs/i) -      5.936k in   5.037516s
+     replay immortal      1.894k (± 2.9%) i/s  (528.02 μs/i) -      9.650k in   5.095389s
 
 Done. Compare this file against bench/baseline_moves.txt after optimizations.

data/bench/baseline_parse.txt

@@ -5,21 +5,21 @@ total_allocated objects: 347037
 total_allocated bytes:   17977414
 
 === 2. Parse + replay allocations (500 games) ===
-total_allocated objects: 1170586
-total_allocated bytes:   67804136
+total_allocated objects: 831530
+total_allocated bytes:   47966112
 
 === 3. Parse-only throughput (ips) ===
 ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +PRISM [x86_64-linux]
 Warming up --------------------------------------
      parse 500 games     1.000 i/100ms
 Calculating -------------------------------------
-     parse 500 games      4.086 (± 0.0%) i/s  (244.74 ms/i) -     21.000 in   5.139596s
+     parse 500 games      4.053 (± 0.0%) i/s  (246.70 ms/i) -     21.000 in   5.180770s
 
 === 4. Parse + replay throughput (ips) ===
 ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +PRISM [x86_64-linux]
 Warming up --------------------------------------
 parse+replay 500 games     1.000 i/100ms
 Calculating -------------------------------------
-parse+replay 500 games      1.472 (± 0.0%) i/s  (679.56 ms/i) -      8.000 in   5.436470s
+parse+replay 500 games      1.872 (± 0.0%) i/s  (534.26 ms/i) -     10.000 in   5.342615s
 
 Done. Compare this file against bench/baseline_parse.txt after optimizations.

data/lib/pgn/board.rb

@@ -50,7 +50,17 @@ module PGN
       nil => '_'
     }.freeze
 
-    attr_accessor :squares
+    # 0x88 board representation (see chess.js / the classic 0x88 move-generation
+    # algorithm). A square is addressed by a single integer index
+    # `rank * 16 + file`; the extra files/ranks make off-board detection a
+    # single bitmask test -- `(idx & 0x88) != 0` -- which is faster than the
+    # four-integer comparison a 0..7 bounds check needs, and lets ray
+    # stepping be a single integer add. The public `squares` 8x8 API is built
+    # from this array on demand (it is off the replay hot path), and the
+    # MoveCalculator hot path works entirely in integer indices.
+    #
+    #   file = idx & 0x0F   (0..7)
+    #   rank = idx >> 4      (0..7)
 
     # @return [PGN::Board] a board in the starting position
     #
@@ -75,7 +85,24 @@ module PGN
     #
     def initialize(squares)
       self.squares = squares
-      @owned = Array.new(8, false)
+    end
+
+    # @return [Array<Array<String>>] the board as a file-major 8x8 array
+    #   (squares[file][rank]). Built on demand from the 0x88 array; equality
+    #   with the START constant and other boards is preserved.
+    #
+    def squares
+      (0..7).map { |f| (0..7).map { |r| @cells[(r * 16) + f] } }
+    end
+
+    def squares=(squares)
+      @cells = Array.new(128)
+      8.times do |f|
+        8.times do |r|
+          @cells[(r * 16) + f] = squares[f][r]
+        end
+      end
+      @cells
     end
 
     # @overload at(str)
@@ -91,12 +118,10 @@ module PGN
     #   board.at(4,3)  #=> "P"
     #   board.at("e4") #=> "P"
     #
-    # String squares are parsed with getbyte arithmetic (a=0x61, '1'=0x31)
-    # so the common string lookup allocates nothing.
     def at(arg0, arg1 = nil)
-      return squares[arg0][arg1] unless arg1.nil?
+      return @cells[(arg1 * 16) + arg0] unless arg1.nil?
 
-      squares[file_of(arg0)][rank_of(arg0)]
+      @cells[(rank_of(arg0) * 16) + file_of(arg0)]
     end
 
     # @param changes [Hash<String, <String, nil>>] changes to make to the board
@@ -105,9 +130,7 @@ module PGN
     #   board.change!({"e2" => nil, "e4" => "P"})
     #
     def change!(changes)
-      changes.each do |square, piece|
-        update(square, piece)
-      end
+      changes.each { |square, piece| update(square, piece) }
       self
     end
 
@@ -117,16 +140,8 @@ module PGN
     # @example
     #   board.update("e4", "P")
     #
-    # Copy-on-write: clone only the column being mutated, and only once per
-    # instance, so unchanged columns stay shared with any board this one was
-    # duped from.
     def update(square, piece)
-      file = file_of(square)
-      unless @owned[file]
-        squares[file] = squares[file].dup
-        @owned[file] = true
-      end
-      squares[file][rank_of(square)] = piece
+      @cells[(rank_of(square) * 16) + file_of(square)] = piece
       self
     end
 
@@ -146,9 +161,7 @@ module PGN
     #
     def position_for(coordinates)
       file, rank = coordinates
-      file_chr = INDEX_TO_FILE[file]
-      rank_chr = INDEX_TO_RANK[rank]
-      [file_chr, rank_chr].join('')
+      INDEX_TO_FILE[file] + INDEX_TO_RANK[rank]
     end
 
     # @return [String] the board in human readable format with unicode
@@ -160,12 +173,66 @@ module PGN
       end.join("\n")
     end
 
-    # @return [PGN::Board] a copy of self. The outer array is copied; the
-    # 8 column arrays are shared and cloned lazily by #update on first
-    # mutation (copy-on-write).
+    # @return [PGN::Board] a copy of self. Copies the 128-cell 0x88 array;
+    #   mutations to the copy do not affect the original.
     #
     def dup
-      PGN::Board.new(squares.dup)
+      copy = PGN::Board.allocate
+      copy.instance_variable_set(:@cells, @cells.dup)
+      copy
+    end
+
+    # -- 0x88 hot-path API (integer indices) ---------------------------------
+
+    # The 0x88 index of an algebraic square name.
+    #
+    # @param square [String] e.g. "e4"
+    # @return [Integer] idx = rank * 16 + file
+    #
+    def index_of(square)
+      (rank_of(square) * 16) + file_of(square)
+    end
+
+    # The 0x88 index of zero-indexed file/rank coordinates.
+    #
+    # @return [Integer] idx = rank * 16 + file
+    #
+    def index_for(file, rank)
+      (rank * 16) + file
+    end
+
+    # Looks up a piece by 0x88 index. The caller is responsible for having
+    # already verified the index is on-board (`(idx & 0x88).zero?`); reading
+    # an off-board index simply returns nil.
+    #
+    # @param idx [Integer] a 0x88 square index
+    # @return [String, nil] the piece on that square
+    #
+    def at_index(idx)
+      @cells[idx]
+    end
+
+    # Places a piece on a 0x88 index. Returns self.
+    #
+    # @param idx [Integer] a 0x88 square index
+    # @param piece [String, nil]
+    # @return [self]
+    #
+    def update_index(idx, piece)
+      @cells[idx] = piece
+      self
+    end
+
+    # Applies a batch of integer-indexed changes. The replay hot path uses
+    # this so it never allocates square-name strings or `[file, rank]`
+    # coordinate arrays.
+    #
+    # @param changes [Hash<Integer, <String, nil>>]
+    # @return [self]
+    #
+    def apply!(changes)
+      changes.each { |idx, piece| @cells[idx] = piece }
+      self
     end
 
     private

data/lib/pgn/move_calculator.rb

@@ -6,88 +6,70 @@ module PGN
   # the board need to be updated, new castling restrictions, the en passant
   # square and whether to update fullmove and halfmove counters.
   #
+  # Squares are addressed as 0x88 integer indices (see {PGN::Board}); this
+  # keeps the replay hot path free of `[file, rank]` coordinate arrays and
+  # square-name string allocations. The public {#origin} reader still returns
+  # an algebraic square string for API compatibility.
+  #
   # @!attribute board
   #   @return [PGN::Board] the current board
   #
   # @!attribute move
   #   @return [PGN::Move] the current move
   #
-  # @!attribute origin
-  #   @return [String, nil] the origin square in SAN
-  #
   class MoveCalculator
-    # Specifies the movement of pieces who are allowed to move in a
-    # given direction until they reach an obstacle or the end of the
-    # board.
+    # 0x88 ray-step offsets for sliding pieces. A step is a single integer
+    # add; off-board is `(idx & 0x88) != 0`, which also catches file wraparound.
     #
-    DIRECTIONS = {
-      'b' => [[1, 1], [-1,  1], [-1, -1], [1, -1]],
-      'r' => [[-1, 0], [1,  0], [0, -1], [0,  1]],
-      'q' => [[1,  1], [-1,  1], [-1, -1], [1, -1],
-              [-1, 0], [1,  0], [0, -1], [0, 1]]
+    SLIDE = {
+      'b' => [-15, 15, -17, 17],
+      'r' => [-1, 1, -16, 16],
+      'q' => [-1, 1, -16, 16, -15, 15, -17, 17]
     }.freeze
 
-    # Specifies the movement of pieces that have a limited set of moves
-    # they are allowed to make.
+    # 0x88 single-step offsets for knight and king.
     #
-    MOVES = {
-      'k' => [[-1, -1], [0, -1], [1, -1], [1,  0],
-              [1,  1], [0,  1], [-1,  1], [-1, 0]],
-      'n' => [[-1, -2], [-1, 2], [1, -2], [1,  2],
-              [-2, -1], [2, -1], [-2, 1], [2,  1]]
+    STEP = {
+      'k' => [-1, 1, -16, 16, -15, 15, -17, 17],
+      'n' => [33, 31, -31, -33, 18, 14, -14, -18]
     }.freeze
 
-    # Specifies possible pawn movements. It may seem backwards since it is
-    # used to compute the origin square and not the destination.
+    # Possible pawn origins, expressed as offsets from the destination square
+    # (pawn moves are computed backwards from where the pawn landed).
     #
-    PAWN_MOVES = {
-      'P' => {
-        capture: [[-1, -1], [1, -1]],
-        normal: [[0, -1]],
-        double: [[0, -2]]
-      },
-      'p' => {
-        capture: [[-1, 1], [1, 1]],
-        normal: [[0,  1]],
-        double: [[0,  2]]
-      }
+    PAWN_OFFSETS = {
+      'P' => { capture: [-17, -15], normal: [-16], double: [-32] },
+      'p' => { capture: [15, 17], normal: [16], double: [32] }
     }.freeze
 
-    # The squares to update for each possible castling move.
+    # The squares to update for each castling move, keyed by 0x88 index.
     #
     CASTLING = {
-      'Q' => {
-        'a1' => nil,
-        'c1' => 'K',
-        'd1' => 'R',
-        'e1' => nil
-      },
-      'K' => {
-        'e1' => nil,
-        'f1' => 'R',
-        'g1' => 'K',
-        'h1' => nil
-      },
-      'q' => {
-        'a8' => nil,
-        'c8' => 'k',
-        'd8' => 'r',
-        'e8' => nil
-      },
-      'k' => {
-        'e8' => nil,
-        'f8' => 'r',
-        'g8' => 'k',
-        'h8' => nil
-      }
+      'Q' => { 0 => nil, 2 => 'K', 3 => 'R', 4 => nil },
+      'K' => { 4 => nil, 5 => 'R', 6 => 'K', 7 => nil },
+      'q' => { 112 => nil, 114 => 'k', 115 => 'r', 116 => nil },
+      'k' => { 116 => nil, 117 => 'r', 118 => 'k', 119 => nil }
     }.freeze
 
-    # Frozen rook-origin -> castling-restriction lookup, shared by both
-    # white ('R') and black ('r') since their rook origins (a1/h1, a8/h8)
-    # are distinct keys. Replaces a per-call hash literal.
-    ROOK_RESTRICTIONS = { 'a1' => 'Q', 'h1' => 'K', 'a8' => 'q', 'h8' => 'k' }.freeze
+    # Corner-square 0x88 indices, used for castling-restriction bookkeeping
+    # (a rook leaving or being captured on a corner drops the matching right).
+    #
+    A1 = 0
+    H1 = 7
+    A8 = 112
+    H8 = 119
+
+    # rook-origin (0x88 index) -> castling restriction it drops.
+    #
+    ROOK_RESTRICTIONS = { A1 => 'Q', H1 => 'K', A8 => 'q', H8 => 'k' }.freeze
+
+    # Castling-move characters by side, for the "castling occurs" restriction.
+    # Frozen so {Array#include?} does not allocate per call.
+    #
+    WHITE_CASTLE = %w[K Q].freeze
+    BLACK_CASTLE = %w[k q].freeze
 
-    attr_accessor :board, :move, :origin
+    attr_accessor :board, :move
 
     # @param board [PGN::Board] the current board
     # @param move [PGN::Move] the current move
@@ -95,14 +77,24 @@ module PGN
     def initialize(board, move)
       self.board = board
       self.move  = move
-      self.origin = compute_origin
+      @origin_idx = compute_origin
+    end
+
+    # @return [String, nil] the origin square in algebraic notation, for API
+    #   compatibility. Internally the calculator works with the 0x88 index
+    #   (see {#origin_idx}); this reader materialises the string on demand.
+    #
+    def origin
+      return nil if @origin_idx.nil?
+
+      board.position_for([@origin_idx & 0x0F, @origin_idx >> 4])
     end
 
     # @return [PGN::Board] the board after the move is made
     #
     def result_board
       new_board = board.dup
-      new_board.change!(changes)
+      new_board.apply!(changes)
 
       new_board
     end
@@ -112,25 +104,28 @@ module PGN
     def castling_restrictions
       restrict = []
 
-      # when a king or rook is moved
       case move.piece
       when 'K'
-        restrict += %w[K Q]
+        restrict << 'K' << 'Q'
       when 'k'
-        restrict += %w[k q]
+        restrict << 'k' << 'q'
       when 'R', 'r'
-        restrict << ROOK_RESTRICTIONS[origin]
+        restrict << ROOK_RESTRICTIONS[@origin_idx]
       end
 
       # when castling occurs
-      restrict += %w[K Q] if %w[K Q].include?(move.castle)
-      restrict += %w[k q] if %w[k q].include?(move.castle)
+      if WHITE_CASTLE.include?(move.castle)
+        restrict << 'K' << 'Q'
+      elsif BLACK_CASTLE.include?(move.castle)
+        restrict << 'k' << 'q'
+      end
 
       # when a rook is taken
-      restrict << 'Q' if move.destination == 'a1'
-      restrict << 'q' if move.destination == 'a8'
-      restrict << 'K' if move.destination == 'h1'
-      restrict << 'k' if move.destination == 'h8'
+      dest = dest_idx
+      restrict << 'Q' if dest == A1
+      restrict << 'q' if dest == A8
+      restrict << 'K' if dest == H1
+      restrict << 'k' if dest == H8
 
       restrict.empty? ? restrict : restrict.compact.uniq
     end
@@ -151,35 +146,31 @@ module PGN
     #
     def en_passant_square
       return nil if move.castle
+      return nil unless move.pawn? && ((origin_rank - dest_rank).abs == 2)
 
-      return unless move.pawn? && (origin[1].to_i - move.destination[1].to_i).abs == 2
-
-      if move.white?
-        "#{origin[0]}3"
-      else
-        "#{origin[0]}6"
-      end
+      Board::INDEX_TO_FILE[origin_file] + (move.white? ? '3' : '6')
     end
 
     private
 
+    # The integer-indexed changes to apply to the board. Keys are 0x88
+    # indices, so no square-name strings are allocated on the hot path.
+    #
     def changes
       changes = {}
       changes.merge!(CASTLING[move.castle]) if move.castle
-      changes.merge!(
-        origin => nil,
-        move.destination => move.piece,
-        en_passant_capture => nil
-      )
-      changes[move.destination] = move.promotion if move.promotion
+      changes[@origin_idx] = nil
+      changes[dest_idx] = move.piece
+      changes[en_passant_capture] = nil
+      changes[dest_idx] = move.promotion if move.promotion
 
-      changes.reject! { |key, _| key.nil? or key.empty? }
+      changes.reject! { |idx, _| idx.nil? }
 
       changes
     end
 
     # Using the current position and move, figure out where the piece
-    # came from.
+    # came from (as a 0x88 index).
     #
     def compute_origin
       return nil if move.castle
@@ -194,58 +185,55 @@ module PGN
 
       possibilities = disambiguate(possibilities) if possibilities.length > 1
 
-      board.position_for(possibilities.first)
+      possibilities.first
     end
 
-    # From the destination square, move in each direction stopping if we
-    # reach the end of the board. If we encounter a piece, add it to the
-    # list of origin possibilities if it is the moving piece, or else
-    # check the next direction.
+    # From the destination square, walk each slider direction until the first
+    # occupied square. If that piece is the moving piece, the square it sits
+    # on is a possible origin.
     #
     def direction_origins
-      directions    = DIRECTIONS[move.piece.downcase]
-      possibilities = []
+      offsets = SLIDE[move.piece.downcase]
+      dest    = dest_idx
 
-      directions.each do |dir|
-        square = first_piece(destination_coords, dir)
+      possibilities = []
+      offsets.each do |off|
+        square = first_piece(dest, off)
         possibilities << square if piece_at(square) == move.piece
       end
 
       possibilities
     end
 
-    # From the destination square, make each move. If it is a valid
-    # square and matches the moving piece, add it to the list of origin
-    # possibilities.
+    # From the destination square, apply each single-step offset. If the
+    # target square is on the board and holds the moving piece, it is a
+    # possible origin.
     #
-    def move_origins(moves = nil)
-      moves         ||= MOVES[move.piece.downcase]
-      possibilities   = []
-      file, rank      = destination_coords
+    def move_origins(offsets = STEP[move.piece.downcase])
+      dest = dest_idx
 
-      moves.each do |i, j|
-        f = file + i
-        r = rank + j
+      possibilities = []
+      offsets.each do |off|
+        target = dest + off
+        next unless (target & 0x88).zero? # rubocop:disable Style/BitwisePredicate
 
-        possibilities << [f, r] if valid_square?(f, r) && board.at(f, r) == move.piece
+        possibilities << target if board.at_index(target) == move.piece
       end
 
       possibilities
     end
 
-    # Computes the possbile pawn origins based on the destination square
+    # Computes the possible pawn origins based on the destination square
     # and whether or not the move is a capture.
     #
     def pawn_origins
-      _, rank     = destination_coords
-      double_rank = (rank == 3 && move.white?) || (rank == 4 && move.black?)
-
-      pawn_moves = PAWN_MOVES[move.piece]
+      double = (dest_rank == 3 && move.white?) || (dest_rank == 4 && move.black?)
 
-      moves = move.capture ? pawn_moves[:capture] : pawn_moves[:normal]
-      moves += pawn_moves[:double] if double_rank
+      pawn_moves = PAWN_OFFSETS[move.piece]
+      offsets = move.capture ? pawn_moves[:capture] : pawn_moves[:normal]
+      offsets += pawn_moves[:double] if double
 
-      move_origins(moves)
+      move_origins(offsets)
     end
 
     def disambiguate(possibilities)
@@ -259,36 +247,36 @@ module PGN
     # Try to disambiguate based on the standard algebraic notation.
     #
     def disambiguate_san(possibilities)
-      if move.disambiguation
-        possibilities.select { |p| board.position_for(p).match(move.disambiguation) }
-      else
-        possibilities
+      return possibilities unless move.disambiguation
+
+      possibilities.select do |idx|
+        board.position_for([idx & 0x0F, idx >> 4]).match(move.disambiguation)
       end
     end
 
-    # A pawn can't move two spaces if there is a pawn in front of it.
+    # A pawn can't move two spaces if there is a pawn in front of it. A
+    # double-push origin sits on rank 2 (white) or 7 (black); reject those
+    # candidates when more than one pawn could have reached the destination.
     #
     def disambiguate_pawns(possibilities)
-      if move.piece.match(/p/i) && !move.capture
-        possibilities.reject { |p| board.position_for(p).match(/2|7/) }
-      else
-        possibilities
-      end
+      return possibilities unless move.piece.match?(/p/i) && !move.capture
+
+      possibilities.reject { |idx| (idx >> 4) == 1 || (idx >> 4) == 6 }
     end
 
     # A piece can't move if it would result in a discovered check.
     #
     def disambiguate_discovered_check(possibilities)
-      king_pos = king_position
+      king_idx = king_position
 
-      DIRECTIONS.each do |attacking_piece, directions|
+      SLIDE.each do |attacking_piece, offsets|
         attacking_piece = attacking_piece.upcase if move.black?
 
-        directions.each do |dir|
-          square = first_piece(king_pos, dir)
+        offsets.each do |off|
+          square = first_piece(king_idx, off)
           next unless piece_at(square) == move.piece && possibilities.include?(square)
 
-          next_square = first_piece(square, dir)
+          next_square = first_piece(square, off)
           possibilities.reject! { |p| p == square } if piece_at(next_square) == attacking_piece
         end
       end
@@ -296,62 +284,69 @@ module PGN
       possibilities
     end
 
-    # Walks from `from` in `direction` until it reaches the edge of the board
-    # or the first occupied square. Returns that square's `[file, rank]`
-    # coordinates, or `nil` if no piece was encountered before the edge. The
-    # caller reads the piece off the board itself, so this avoids allocating
-    # the `[piece, square]` wrapper tuple per direction scan.
+    # Walks from `idx` in the 0x88 direction `off` until it reaches the edge
+    # of the board or the first occupied square. Returns that square's 0x88
+    # index, or nil if no piece was encountered before the edge.
     #
-    def first_piece(from, direction)
-      file, rank = from
-      i,    j    = direction
+    def first_piece(idx, off)
+      idx += off
+      while (idx & 0x88).zero? # rubocop:disable Style/BitwisePredicate
+        square = board.at_index(idx)
+        return idx if square
 
-      loop do
-        file += i
-        rank += j
-        return nil if file.negative? || file > 7 || rank.negative? || rank > 7
-
-        square = [file, rank]
-        return square if board.at(file, rank)
+        idx += off
       end
+      nil
     end
 
-    # Reads the piece on a square, tolerating a nil square (returned by
-    # {#first_piece} when the scan ran off the edge). Kept as a helper so the
-    # callers read the piece once instead of unpacking a `[piece, square]`
-    # tuple per direction scan.
+    # Reads the piece at a 0x88 index, returning nil for an off-board (nil)
+    # index. Keeps {#disambiguate_discovered_check} within the configured
+    # complexity limits.
     #
-    def piece_at(square)
-      square && board.at(square[0], square[1])
+    def piece_at(idx)
+      idx && board.at_index(idx)
     end
 
-    # If the move is a capture and there is no piece on the
-    # destination square, it must be an en passant capture.
+    # If the move is a capture and there is no piece on the destination
+    # square, it must be an en passant capture. The captured pawn sits on the
+    # destination file and the moving pawn's origin rank.
     #
     def en_passant_capture
       return nil if move.castle
+      return nil unless move.capture && board.at_index(dest_idx).nil?
 
-      move.destination[0] + origin[1] if !board.at(move.destination) && move.capture
+      (origin_rank * 16) + (dest_idx & 0x0F)
     end
 
     def king_position
       king = move.white? ? 'K' : 'k'
 
-      0.upto(7) do |file|
-        0.upto(7) do |rank|
-          return [file, rank] if board.at(file, rank) == king
+      0.upto(7) do |rank|
+        0.upto(7) do |file|
+          idx = (rank * 16) + file
+          return idx if board.at_index(idx) == king
         end
       end
 
       nil
     end
 
-    def valid_square?(file, rank)
-      file >= 0 && file < 8 && rank >= 0 && rank < 8
+    # -- 0x88 index helpers --------------------------------------------------
+
+    def dest_idx
+      @dest_idx ||= move.destination && board.index_of(move.destination)
+    end
+
+    def origin_file
+      @origin_idx & 0x0F
+    end
+
+    def origin_rank
+      @origin_idx >> 4
     end
 
-    def destination_coords
-      @destination_coords ||= board.coordinates_for(move.destination)
+    def dest_rank
+      dest_idx >> 4
     end
   end
 end

data/lib/pgn/version.rb

@@ -1,3 +1,3 @@
 module PGN
-  VERSION = '1.2.1'.freeze
+  VERSION = '1.3.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgn2
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - Stacey Touset