Skip to main content

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

lo
number
required
Lower 32 bits (squares 0-31)
hi
number
required
Higher 32 bits (squares 32-63)
const squares = new SquareSet(0xff, 0); // First rank

Properties

lo
number
Lower 32 bits representing squares 0-31
hi
number
Higher 32 bits representing squares 32-63

Static Factory Methods

fromSquare

static fromSquare(square: Square): SquareSet
Creates a SquareSet containing a single square.
square
Square
required
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
required
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
required
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

static full(): SquareSet
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.
color
Color
required
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

complement(): SquareSet
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.
other
SquareSet
required
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.
other
SquareSet
required
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.
other
SquareSet
required
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).
other
SquareSet
required
The set to subtract
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.
other
SquareSet
required
The other set to check
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.
other
SquareSet
required
The other set to check
if (whiteSquares.isDisjoint(blackSquares)) {
  console.log('No overlap');
}

supersetOf

supersetOf(other: SquareSet): boolean
Checks if this set contains all squares from another set.
other
SquareSet
required
The potential subset
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.
other
SquareSet
required
The potential superset
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.
shift
number
required
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.
shift
number
required
Number of bits to shift (0-64)
const shifted = squares.shl64(8); // Shift up one rank

bswap64

bswap64(): SquareSet
Byte-swaps the 64-bit value.
const swapped = squares.bswap64();

rbit64

rbit64(): SquareSet
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.
other
SquareSet
required
The set to subtract
const result = a.minus64(b);

Comparison Methods

equals

equals(other: SquareSet): boolean
Checks if two sets are exactly equal.
other
SquareSet
required
The other set to compare
if (set1.equals(set2)) {
  console.log('Sets are identical');
}

Query Methods

size

size(): number
Returns the number of squares in the set.
const count = squares.size();

isEmpty

isEmpty(): boolean
Checks if the set contains no squares.
if (squares.isEmpty()) {
  console.log('No squares in set');
}

nonEmpty

nonEmpty(): boolean
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.
square
Square
required
The square to check (0-63)
if (occupied.has(28)) {
  console.log('e4 is occupied');
}

moreThanOne

moreThanOne(): boolean
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.
square
Square
required
The square to add or remove (0-63)
on
boolean
required
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.
square
Square
required
The square to add (0-63)
const withE4 = squares.with(28);

without

without(square: Square): SquareSet
Returns a new set with the specified square removed.
square
Square
required
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).
square
Square
required
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);
  }
}

Build docs developers (and LLMs) love