Overview
SquareSet is an immutable set of squares, implemented as a 64-bit bitboard split into two 32-bit numbers (lo and hi). It provides efficient set operations for chess square manipulation.
import { SquareSet } from 'chessops';
const squares = SquareSet.fromSquare(0).union(SquareSet.fromSquare(7));
console.log(squares.size()); // 2
Constructor
Lower 32 bits (squares 0-31)
Higher 32 bits (squares 32-63)
const squares = new SquareSet(0xff, 0); // First rank
Properties
Lower 32 bits representing squares 0-31
Higher 32 bits representing squares 32-63
Static Factory Methods
fromSquare
static fromSquare(square: Square): SquareSet
Creates a SquareSet containing a single square.
The square to include (0-63)
const e4 = SquareSet.fromSquare(28);
fromRank
static fromRank(rank: number): SquareSet
Creates a SquareSet containing all squares of a given rank.
Rank number (0-7, where 0 is the first rank)
const firstRank = SquareSet.fromRank(0);
fromFile
static fromFile(file: number): SquareSet
Creates a SquareSet containing all squares of a given file.
File number (0-7, where 0 is the a-file)
const aFile = SquareSet.fromFile(0);
empty
static empty(): SquareSet
Creates an empty SquareSet.
const empty = SquareSet.empty();
full
Creates a SquareSet containing all 64 squares.
const allSquares = SquareSet.full();
corners
static corners(): SquareSet
Creates a SquareSet containing the four corner squares (a1, h1, a8, h8).
const corners = SquareSet.corners();
center
static center(): SquareSet
Creates a SquareSet containing the four center squares (d4, e4, d5, e5).
const center = SquareSet.center();
backranks
static backranks(): SquareSet
Creates a SquareSet containing both first and eighth ranks.
const backranks = SquareSet.backranks();
backrank
static backrank(color: Color): SquareSet
Creates a SquareSet containing the backrank for the given color.
Either ‘white’ or ‘black’
const whiteBackrank = SquareSet.backrank('white'); // First rank
const blackBackrank = SquareSet.backrank('black'); // Eighth rank
lightSquares
static lightSquares(): SquareSet
Creates a SquareSet containing all light squares.
const lightSquares = SquareSet.lightSquares();
darkSquares
static darkSquares(): SquareSet
Creates a SquareSet containing all dark squares.
const darkSquares = SquareSet.darkSquares();
Set Operations
complement
Returns the complement (bitwise NOT) of this set.
const occupied = SquareSet.fromSquare(0);
const empty = occupied.complement();
xor
xor(other: SquareSet): SquareSet
Returns the symmetric difference (XOR) of this set and another.
The other set to XOR with
const a = SquareSet.fromSquare(0);
const b = SquareSet.fromSquare(1);
const result = a.xor(b); // Contains both squares
union
union(other: SquareSet): SquareSet
Returns the union (OR) of this set and another.
The other set to union with
const a = SquareSet.fromSquare(0);
const b = SquareSet.fromSquare(1);
const both = a.union(b);
intersect
intersect(other: SquareSet): SquareSet
Returns the intersection (AND) of this set and another.
The other set to intersect with
const whitePieces = board.white;
const pawns = board.pawn;
const whitePawns = whitePieces.intersect(pawns);
diff
diff(other: SquareSet): SquareSet
Returns the difference of this set and another (elements in this but not in other).
const allSquares = SquareSet.full();
const occupied = board.occupied;
const empty = allSquares.diff(occupied);
intersects
intersects(other: SquareSet): boolean
Checks if this set has any squares in common with another.
if (lightSquares.intersects(bishops)) {
console.log('Has light-squared bishop');
}
isDisjoint
isDisjoint(other: SquareSet): boolean
Checks if this set has no squares in common with another.
if (whiteSquares.isDisjoint(blackSquares)) {
console.log('No overlap');
}
supersetOf
supersetOf(other: SquareSet): boolean
Checks if this set contains all squares from another set.
if (occupied.supersetOf(whitePieces)) {
console.log('All white pieces are on occupied squares');
}
subsetOf
subsetOf(other: SquareSet): boolean
Checks if all squares in this set are contained in another set.
if (whitePawns.subsetOf(whitePieces)) {
console.log('Valid subset');
}
Bitwise Operations
shr64
shr64(shift: number): SquareSet
Shifts the bitboard right by the specified number of bits.
Number of bits to shift (0-64)
const shifted = squares.shr64(8); // Shift down one rank
shl64
shl64(shift: number): SquareSet
Shifts the bitboard left by the specified number of bits.
Number of bits to shift (0-64)
const shifted = squares.shl64(8); // Shift up one rank
bswap64
Byte-swaps the 64-bit value.
const swapped = squares.bswap64();
rbit64
Reverses the bits in the 64-bit value.
const reversed = squares.rbit64();
minus64
minus64(other: SquareSet): SquareSet
Subtracts another set as a 64-bit integer.
const result = a.minus64(b);
Comparison Methods
equals
equals(other: SquareSet): boolean
Checks if two sets are exactly equal.
if (set1.equals(set2)) {
console.log('Sets are identical');
}
Query Methods
size
Returns the number of squares in the set.
const count = squares.size();
isEmpty
Checks if the set contains no squares.
if (squares.isEmpty()) {
console.log('No squares in set');
}
nonEmpty
Checks if the set contains at least one square.
if (squares.nonEmpty()) {
console.log('Has squares');
}
has
has(square: Square): boolean
Checks if the set contains a specific square.
The square to check (0-63)
if (occupied.has(28)) {
console.log('e4 is occupied');
}
moreThanOne
Checks if the set contains more than one square.
if (squares.moreThanOne()) {
console.log('Multiple squares present');
}
Modification Methods
set
set(square: Square, on: boolean): SquareSet
Adds or removes a square based on the boolean flag.
The square to add or remove (0-63)
If true, adds the square; if false, removes it
const updated = squares.set(28, true); // Add e4
const removed = squares.set(28, false); // Remove e4
with
with(square: Square): SquareSet
Returns a new set with the specified square added.
const withE4 = squares.with(28);
without
without(square: Square): SquareSet
Returns a new set with the specified square removed.
The square to remove (0-63)
const withoutE4 = squares.without(28);
toggle
toggle(square: Square): SquareSet
Returns a new set with the specified square toggled (added if absent, removed if present).
The square to toggle (0-63)
const toggled = squares.toggle(28);
Iteration Methods
first
first(): Square | undefined
Returns the first (lowest numbered) square in the set, or undefined if empty.
const firstSquare = squares.first();
if (firstSquare !== undefined) {
console.log('First square:', firstSquare);
}
last
last(): Square | undefined
Returns the last (highest numbered) square in the set, or undefined if empty.
const lastSquare = squares.last();
singleSquare
singleSquare(): Square | undefined
Returns the square if the set contains exactly one square, otherwise undefined.
const king = board.pieces('white', 'king').singleSquare();
if (king !== undefined) {
console.log('White king is on square', king);
}
withoutFirst
withoutFirst(): SquareSet
Returns a new set with the first square removed.
const rest = squares.withoutFirst();
[Symbol.iterator]
[Symbol.iterator](): Iterator<Square>
Iterates through all squares in ascending order.
for (const square of squares) {
console.log(square);
}
// Or use spread operator
const squareArray = [...squares];
reversed
reversed(): Iterable<Square>
Iterates through all squares in descending order.
for (const square of squares.reversed()) {
console.log(square);
}
Examples
Finding Attacked Squares
import { SquareSet } from 'chessops';
import { attacks } from 'chessops/attacks';
const piece = { role: 'queen', color: 'white' };
const square = 28; // e4
const occupied = board.occupied;
const attacked = attacks(piece, square, occupied);
console.log(`Queen on e4 attacks ${attacked.size()} squares`);
Filtering Squares by Color
const bishops = board.bishop;
const lightSquareBishops = bishops.intersect(SquareSet.lightSquares());
const darkSquareBishops = bishops.intersect(SquareSet.darkSquares());
console.log('Light bishops:', lightSquareBishops.size());
console.log('Dark bishops:', darkSquareBishops.size());
Building Custom Square Sets
// Create a set of center files (c, d, e, f)
let center = SquareSet.empty();
for (let file = 2; file <= 5; file++) {
center = center.union(SquareSet.fromFile(file));
}
// Find pieces in the center
const centerPieces = board.occupied.intersect(center);
console.log('Pieces in center:', centerPieces.size());
Iterating with Condition
const pawns = board.pawn.intersect(board.white);
const promotableRank = SquareSet.fromRank(6);
for (const pawn of pawns) {
if (promotableRank.has(pawn)) {
console.log('Pawn ready to promote on square', pawn);
}
}