Struct ZobristTable 

pub struct ZobristTable { /* private fields */ }

Zobrist hash table for O(1) incremental state hashing (Zobrist 1970).

Used by ZobristSnapshotter for efficient entropy detection. Instead of computing SHA-256 every frame (O(N)), we can update the hash incrementally when state changes (O(1)).

Theory

Per Zobrist (1970): “A hash value can be updated incrementally by XORing out the old value and XORing in the new value.”

Per Tridgell (1999): “Rolling checksums enable efficient delta detection without full state comparison.”

Examples

use jugar_web::trace::ZobristTable;

let table = ZobristTable::new(42);
let state = [0u8; 32];
let hash = table.hash_bytes(&state);

// Incremental update is O(1)
let new_hash = table.update_hash(hash, 0, 0, 255);
assert_ne!(hash, new_hash);

Implementations

impl ZobristTable

pub fn new(seed: u64) -> Self

Create table with deterministic RNG (for reproducibility).

Uses xorshift64 for fast, deterministic random generation. Table is heap-allocated (65KB) to avoid stack overflow.

Panics

Cannot panic - the Vec-to-array conversion is guaranteed to succeed because we create exactly NUM_ZOBRIST_FIELDS elements.

pub fn hash_bytes(&self, bytes: &[u8]) -> u64

Compute Zobrist hash for byte slice (O(N) - used once per state).

pub fn update_hash( &self, hash: u64, field: usize, old_byte: u8, new_byte: u8, ) -> u64

Update hash incrementally when single byte changes (O(1)).

This is the key optimization - no need to rehash entire state.

pub const fn entropy(hash1: u64, hash2: u64) -> u32

Calculate entropy as Hamming distance between two hashes.

Returns number of differing bits (0-64).

Trait Implementations

impl Clone for ZobristTable

fn clone(&self) -> ZobristTable

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ZobristTable

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ZobristTable

fn default() -> Self

Returns the “default value” for a type.