Chess

https://jordanbray.github.io/chess/
Admin
Chess is a fast Rust move generation library designed for use in chess engines and UIs without...
Tokens:1,831,450
Snippets:10,175
Trust Score:9.7
Update:22 hours ago
Show doc for...
Tokens:
Raw
### Move Generation Example

Source: https://jordanbray.github.io/chess/chess/

Example demonstrating how to generate all legal moves from the starting chess position using the Board and MoveGen structs.

```APIDOC
## Move Generation Example

### Description
Generates all legal moves from the starting chess position and asserts the count is 20.

### Code Example
```rust
use chess::{Board, MoveGen};

let board = Board::default();
let movegen = MoveGen::new_legal(&board);
assert_eq!(movegen.len(), 20);
```

```

--------------------------------

### Create a Game with a specific starting board

Source: https://jordanbray.github.io/chess/chess/struct.Game.html

Creates a `Game` from a given `Board`. The example uses `Board::default()` and verifies the current position.

```rust
use chess::{Game, Board};

let game = Game::new_with_board(Board::default());
assert_eq!(game.current_position(), Board::default());
```

--------------------------------

### Set up a board with setup()

Source: https://jordanbray.github.io/chess/chess/struct.BoardBuilder.html

Pre-loads a board with pieces, side to move, castle rights, and en passant. The example sets up kings on A1 and H8, Black to move, no castle rights, and no en passant.

```rust
use chess::{BoardBuilder, Board, Square, Color, Piece, CastleRights};
use std::convert::TryInto;

let board: Board = BoardBuilder::setup(
        &[
            (Square::A1, Piece::King, Color::White),
            (Square::H8, Piece::King, Color::Black)
        ],
        Color::Black,
        CastleRights::NoRights,
        CastleRights::NoRights,
        None)
    .try_into()?;
```

--------------------------------

### my_castle_rights example

Source: https://jordanbray.github.io/chess/chess/struct.Board.html

Shows how to use Board::my_castle_rights to get the castle rights for the white player. The example removes castle rights for both colors and then asserts that my_castle_rights equals castle_rights(Color::White).

```rust
use chess::{Board, Color, CastleRights};

let mut board = Board::default();
board.remove_castle_rights(Color::White, CastleRights::KingSide);
board.remove_castle_rights(Color::Black, CastleRights::QueenSide);

assert_eq!(board.my_castle_rights(), board.castle_rights(Color::White));
```

--------------------------------

### Create a new Game with initial position

Source: https://jordanbray.github.io/chess/chess/struct.Game.html

Creates a `Game` with the standard starting position. The example asserts that the current position equals `Board::default()`.

```rust
use chess::{Game, Board};

let game = Game::new();
assert_eq!(game.current_position(), Board::default());
```

--------------------------------

### Get combined BitBoard with all pieces

Source: https://jordanbray.github.io/chess/chess/struct.Board.html

Demonstrates the combined method, which returns a BitBoard containing every piece on the board. The example uses Board::default() and asserts that the combined board equals the union of ranks First, Second, Seventh, and Eighth.

```rust
use chess::{Board, BitBoard, Rank, get_rank};

let board = Board::default();

let combined_should_be = get_rank(Rank::First) |
                         get_rank(Rank::Second) |
                         get_rank(Rank::Seventh) |
                         get_rank(Rank::Eighth);

assert_eq!(*board.combined(), combined_should_be);
```

--------------------------------

### Get side to move

Source: https://jordanbray.github.io/chess/chess/struct.Board.html

Returns the color of the side whose turn it is. The example shows that the default board starts with White to move.

```rust
use chess::{Board, Color};

let mut board = Board::default();
assert_eq!(board.side_to_move(), Color::White);
```

--------------------------------

### referenced_ty_params example: Get referenced type parameters

Source: https://jordanbray.github.io/chess/src/synstructure/lib.rs.html

Shows how to use BindingInfo::referenced_ty_params to get the type parameters referenced in a field's type. The example checks that the first binding of the first variant references the type parameter T.

```rust
/// # Example
/// ```
/// # use synstructure::*;
/// let di: syn::DeriveInput = syn::parse_quote! {
///     struct A<T, U> {
///         a: Option<T>,
///         b: U,
///     }
/// };
/// let mut s = Structure::new(&di);
///
/// assert_eq!(
///     s.variants()[0].bindings()[0].referenced_ty_params(),
///     &[&quote::format_ident!("T")]
/// );
/// ```
```

--------------------------------

### BoardBuilder::setup and From<Board> implementation

Source: https://jordanbray.github.io/chess/src/chess/board_builder.rs.html

Shows how to construct a BoardBuilder from a Board using setup, and provides a From<Board> implementation that delegates to the reference conversion.

```rust
BoardBuilder::setup(
    &pieces,
    board.side_to_move(),
    board.castle_rights(Color::White),
    board.castle_rights(Color::Black),
    board.en_passant().map(|sq| sq.get_file()),
)
}
}

impl From<Board> for BoardBuilder {
    fn from(board: Board) -> Self {
        (&board).into()
    }
}
```

--------------------------------

### side_to_move example

Source: https://jordanbray.github.io/chess/chess/struct.Game.html

Returns the color of the player whose turn it is to move. The example shows that a new game starts with White to move.

```rust
use chess::{Game, Color};

let game = Game::new();
assert_eq!(game.side_to_move(), Color::White);
```

--------------------------------

### BoardBuilder::setup

Source: https://jordanbray.github.io/chess/chess/struct.BoardBuilder.html

Sets up a board with everything pre-loaded, including pieces, side to move, castle rights, and en passant square.

```APIDOC
## BoardBuilder::setup

### Description
Set up a board with everything pre-loaded. This method allows specifying the initial pieces, side to move, castle rights for both players, and an optional en passant file.

### Method
`pub fn setup<'a>(pieces: impl IntoIterator<Item = &'a (Square, Piece, Color)>, side_to_move: Color, white_castle_rights: CastleRights, black_castle_rights: CastleRights, en_passant: Option<File>) -> BoardBuilder`

### Parameters
- `pieces` (impl IntoIterator<Item = &'a (Square, Piece, Color)>) - Required - An iterator over tuples of (Square, Piece, Color) representing the pieces to place on the board.
- `side_to_move` (Color) - Required - The color of the player whose turn it is.
- `white_castle_rights` (CastleRights) - Required - The castle rights for the white player.
- `black_castle_rights` (CastleRights) - Required - The castle rights for the black player.
- `en_passant` (Option<File>) - Required - The file on which an en passant capture is possible, if any.

### Returns
- `BoardBuilder` - A board builder with the specified configuration.

### Example
```rust
use chess::{BoardBuilder, Board, Square, Color, Piece, CastleRights};
use std::convert::TryInto;

let board: Board = BoardBuilder::setup(
        &[
            (Square::A1, Piece::King, Color::White),
            (Square::H8, Piece::King, Color::Black)
        ],
        Color::Black,
        CastleRights::NoRights,
        CastleRights::NoRights,
        None)
    .try_into()?;
```
```

--------------------------------

### Example using compat and with_context

Source: https://jordanbray.github.io/chess/failure/trait.ResultExt.html

Example demonstrating the compat method to wrap a custom error and then using with_context to add context, resulting in a formatted error message.

```rust
use std::error::Error;
struct CustomError;

impl Error for CustomError {
    fn description(&self) -> &str {
        "My custom error message"
    }

    fn cause(&self) -> Option<&Error> {
        None
    }
}

let x = (|| -> Result<(), failure::Error> {
    Err(CustomError).compat()?
})().with_context(|e| {
    format!("An error occured: {}", e)
}).unwrap_err();

let x = format!("{}", x);

assert_eq!(x, "An error occured: My custom error message");
```

--------------------------------

### referenced_ty_params example

Source: https://jordanbray.github.io/chess/src/synstructure/lib.rs.html

Shows how to use referenced_ty_params to get the type parameters referenced in non-filtered fields. The example filters out variant C and asserts that only T is returned.

```rust
/// Returns a list of the type parameters which are refrenced in the types
/// of non-filtered fields / variants.
///
/// # Caveat
///
/// If the struct contains any macros in type position, all parameters will
/// be considered bound. This is because we cannot determine which type
/// parameters are bound by type macros.
///
/// # Example
/// ```
/// # use synstructure::*;
/// let di: syn::DeriveInput = syn::parse_quote! {
///     enum A<T, U> {
///         B(T, i32),
///         C(Option<U>),
///     }
/// };
/// let mut s = Structure::new(&di);
///
/// s.filter_variants(|v| v.ast().ident != "C");
///
/// assert_eq!(
///     s.referenced_ty_params(),
///     &[&quote::format_ident!("T")]
/// );
/// ```
pub fn referenced_ty_params(&self) -> Vec<&'a Ident> {
    let mut flags = Vec::new();
    for variant in &self.variants {
        for binding in &variant.bindings {
            generics_fuse(&mut flags, &binding.seen_generics);
        }
    }
    fetch_generics(&flags, &self.ast.generics)
}
```

--------------------------------

### remove_their_castle_rights example

Source: https://jordanbray.github.io/chess/chess/struct.Board.html

Shows how to use Board::remove_their_castle_rights to remove castle rights for the black player. The example starts with both rights and removes the king-side right, then asserts the result is queen-side only.

```rust
use chess::{Board, CastleRights};

let mut board = Board::default();
assert_eq!(board.their_castle_rights(), CastleRights::Both);

board.remove_their_castle_rights(CastleRights::KingSide);
assert_eq!(board.their_castle_rights(), CastleRights::QueenSide);
```

--------------------------------

### Make move example with MoveGen

Source: https://jordanbray.github.io/chess/src/chess/game.rs.html

This example shows how to use the `make_move` method. It creates a new game, generates legal moves with `MoveGen::new_legal`, and makes the first legal move. The method returns false if the game is already over or the move is illegal.

```rust
    /// Make a chess move on the board
    ///
    /// ```
    /// use chess::{Game, MoveGen};
    ///
    /// let mut game = Game::new();
    ///
    /// let mut movegen = MoveGen::new_legal(&game.current_position());
    ///
    /// game.make_move(movegen.next().expect("At least one legal move"));
    /// ```
```

--------------------------------

### SquareAndBitBoard::new

Source: https://jordanbray.github.io/chess/src/chess/movegen/movegen.rs.html

Creates a new SquareAndBitBoard instance with the given square, bitboard, and promotion flag.

```APIDOC
## SquareAndBitBoard::new

### Description
Creates a new `SquareAndBitBoard` instance with the given square, bitboard, and promotion flag.

### Method
`pub fn new(sq: Square, bb: BitBoard, promotion: bool) -> SquareAndBitBoard`

### Parameters
- **sq** (Square) - Required - The square associated with the move.
- **bb** (BitBoard) - Required - The bitboard representing the destination squares.
- **promotion** (bool) - Required - Whether the move is a promotion.

### Returns
- **SquareAndBitBoard** - The constructed instance.

```

--------------------------------

### remove_my_castle_rights example

Source: https://jordanbray.github.io/chess/chess/struct.Board.html

Shows how to use Board::remove_my_castle_rights to remove castle rights for the white player. The example starts with both rights and removes the king-side right, then asserts the result is queen-side only.

```rust
use chess::{Board, CastleRights};

let mut board = Board::default();
assert_eq!(board.my_castle_rights(), CastleRights::Both);

board.remove_my_castle_rights(CastleRights::KingSide);
assert_eq!(board.my_castle_rights(), CastleRights::QueenSide);
```

--------------------------------

### BoardBuilder::setup - Pre-loaded board

Source: https://jordanbray.github.io/chess/src/chess/board_builder.rs.html

Sets up a board with pre-loaded pieces, side to move, castle rights, and en passant. The example creates a board with two kings, Black to move, no castle rights, and no en passant, then converts to Board.

```rust
use chess::{BoardBuilder, Board, Square, Color, Piece, CastleRights};
use std::convert::TryInto;

# use chess::Error;
# fn main() -> Result<(), Error> {
let board: Board = BoardBuilder::setup(
        &[
            (Square::A1, Piece::King, Color::White),
            (Square::H8, Piece::King, Color::Black)
        ],
        Color::Black,
        CastleRights::NoRights,
        CastleRights::NoRights,
        None)
    .try_into()?;
# Ok(())
# }

```

--------------------------------

### their_castle_rights example

Source: https://jordanbray.github.io/chess/chess/struct.Board.html

Shows how to use Board::their_castle_rights to get the castle rights for the black player. The example removes castle rights for both colors and then asserts that their_castle_rights equals castle_rights(Color::Black).

```rust
use chess::{Board, Color, CastleRights};

let mut board = Board::default();
board.remove_castle_rights(Color::White, CastleRights::KingSide);
board.remove_castle_rights(Color::Black, CastleRights::QueenSide);

assert_eq!(board.their_castle_rights(), board.castle_rights(Color::Black));
```

--------------------------------

### referenced_ty_params Example

Source: https://jordanbray.github.io/chess/src/synstructure/lib.rs.html

Shows how to use referenced_ty_params to get the type parameters referenced in a field's type. The example parses a struct definition and asserts that the first binding references the type parameter 'T'.

```rust
/// Returns a list of the type parameters which are referenced in this
/// field's type.
///
/// # Caveat
///
/// If the field contains any macros in type position, all parameters will
/// be considered bound. This is because we cannot determine which type
/// parameters are bound by type macros.
///
/// # Example
/// ```
/// # use synstructure::*;
/// let di: syn::DeriveInput = syn::parse_quote! {
///     struct A<T, U> {
///         a: Option<T>,
///         b: U,
///     }
/// };
/// let mut s = Structure::new(&di);
///
/// assert_eq!(
///     s.variants()[0].bindings()[0].referenced_ty_params(),
///     &[&quote::format_ident!("T")]
/// );
/// ```
    pub fn referenced_ty_params(&self) -> Vec<&'a Ident> {
        fetch_generics(&self.seen_generics, self.generics)
    }
}
```

--------------------------------

### castle_rights usage example

Source: https://jordanbray.github.io/chess/chess/struct.BoardBuilder.html

Shows how to set castle rights for a color using the builder pattern and directly on a mutable BoardBuilder. Demonstrates both NoRights and Both options.

```rust
use chess::{BoardBuilder, Color, CastleRights};
BoardBuilder::new()
             .castle_rights(Color::White, CastleRights::NoRights);

let mut bb = BoardBuilder::new();
bb.castle_rights(Color::Black, CastleRights::Both);
```

--------------------------------

### make_move example

Source: https://jordanbray.github.io/chess/chess/struct.Game.html

Makes a chess move on the board. The example creates a new game and makes the first legal move from the move generator.

```rust
use chess::{Game, MoveGen};

let mut game = Game::new();

let mut movegen = MoveGen::new_legal(&game.current_position());

game.make_move(movegen.next().expect("At least one legal move"));
```

--------------------------------

### Using split_for_impl in quote! macro

Source: https://jordanbray.github.io/chess/src/syn/generics.rs.html

Example from the split_for_impl method documentation showing how to split generics into impl generics, type generics, and where clause for use in a quote! macro. The example is a doctest with hidden setup lines.

```rust
let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();
quote! {
    impl #impl_generics MyTrait for #name #ty_generics #where_clause {
        // ...
    }
}
```

--------------------------------

### Using unicode_xid::UnicodeXID to check identifier start

Source: https://jordanbray.github.io/chess/src/unicode_xid/lib.rs.html

Example from the crate's documentation showing how to use the UnicodeXID trait to check if a character is a valid start of an identifier. Requires adding unicode-xid = "0.0.4" to Cargo.toml.

```rust
extern crate unicode_xid;

use unicode_xid::UnicodeXID;

fn main() {
    let ch = 'a';
    println!("Is {} a valid start of an identifier? {}", ch, UnicodeXID::is_xid_start(ch));
}
```

--------------------------------

### select

Source: https://jordanbray.github.io/chess/src/libc/unix/mod.rs.html

Waits for one or more file descriptors to become ready for I/O.

```APIDOC
## select

### Description
Waits for one or more file descriptors to become ready for I/O.

### Function Signature
```rust
pub fn select(nfds: ::c_int, readfs: *mut fd_set, writefds: *mut fd_set, errorfds: *mut fd_set, timeout: *mut timeval) -> ::c_int;
```

### Parameters
- **nfds** (::c_int) - Required - Highest-numbered file descriptor plus one.
- **readfs** (*mut fd_set) - Required - Set of descriptors to monitor for reading.
- **writefds** (*mut fd_set) - Required - Set of descriptors to monitor for writing.
- **errorfds** (*mut fd_set) - Required - Set of descriptors to monitor for errors.
- **timeout** (*mut timeval) - Required - Maximum wait time, or null for infinite.

### Return Value
- ::c_int - Number of ready descriptors, 0 on timeout, -1 on error.
```

--------------------------------

### Get capacity of ArrayString with ArrayString::capacity

Source: https://jordanbray.github.io/chess/arrayvec/struct.ArrayString.html

Returns the capacity of the ArrayString. The example creates an ArrayString with capacity 3 and asserts it.

```rust
use arrayvec::ArrayString;

let string = ArrayString::<[_; 3]>::new();
assert_eq!(string.capacity(), 3);
```

--------------------------------

### BoardBuilder usage example

Source: https://jordanbray.github.io/chess/chess/struct.BoardBuilder.html

Shows how to create a BoardBuilder, place pieces, index by square, convert to Board, and use the builder pattern. Note that BoardBuilder allows invalid positions, as demonstrated by the side_to_move example.

```rust
use chess::{BoardBuilder, Board, Square, Color, Piece};
use std::convert::TryFrom;
let mut position = BoardBuilder::new();
position.piece(Square::A1, Piece::King, Color::White);
position.piece(Square::A8, Piece::Rook, Color::Black);
position.piece(Square::D1, Piece::King, Color::Black);

// You can index the position by the square:
assert_eq!(position[Square::A1], Some((Piece::King, Color::White)));

// White is in check, but that's ok, it's white's turn to move.
assert!(Board::try_from(&position).is_ok());

// Now White is in check, but Black is ready to move.  This position is invalid.
position.side_to_move(Color::Black);
assert!(Board::try_from(position).is_err());

// One liners are possible with the builder pattern.
use std::convert::TryInto;

let res: Result<Board, _> = BoardBuilder::new()
                       .piece(Square::A1, Piece::King, Color::White)
                       .piece(Square::A8, Piece::King, Color::Black)
                       .try_into();
assert!(res.is_ok());
```

--------------------------------

### Example input for pub visibility parsing

Source: https://jordanbray.github.io/chess/src/syn/parse.rs.html

Input example showing a tuple struct with `pub(crate)` and `pub` visibilities, where parentheses can be part of the type. Used to illustrate the need for speculative parsing.

```rust
/// # struct A;
/// # struct B;
/// # struct C;
/// #
/// struct S(pub(crate) A, pub (B, C));
```

--------------------------------

### Doc comment interpolation fails - line comment

Source: https://jordanbray.github.io/chess/quote/macro.quote.html

This example deliberately fails to compile. Doc comments do not get interpolation behavior in quote!.

```rust
quote! {
    /// try to interpolate: #ident
    ///
    /// ...
}
```

--------------------------------

### BitBoard usage example

Source: https://jordanbray.github.io/chess/chess/struct.BitBoard.html

Shows how to create a BitBoard with value 7 (lower-left 3 squares) and iterate over its squares, counting them. Asserts the count equals 3.

```rust
use chess::{BitBoard, Square};

let bb = BitBoard(7); // lower-left 3 squares

let mut count = 0;

// Iterate over each square in the bitboard
for _ in bb {
    count += 1;
}

assert_eq!(count, 3);
```

--------------------------------

### Piece to_string example

Source: https://jordanbray.github.io/chess/chess/enum.Piece.html

Shows how to convert a piece with a color to a string. White pieces are uppercase, black pieces are lowercase.

```rust
use chess::{Piece, Color};

assert_eq!(Piece::King.to_string(Color::White), "K");
assert_eq!(Piece::Knight.to_string(Color::Black), "n");
```

--------------------------------

### Get castle rights with get_castle_rights()

Source: https://jordanbray.github.io/chess/chess/struct.BoardBuilder.html

Returns the CastleRights for a given color. The example checks that a default board gives White both castle rights.

```rust
use chess::{BoardBuilder, Board, CastleRights, Color};

let bb: BoardBuilder = Board::default().into();
assert_eq!(bb.get_castle_rights(Color::White), CastleRights::Both);
```

--------------------------------

### execle

Source: https://jordanbray.github.io/chess/libc/all.html

Executes a file with a list of arguments and environment. This is a libc function that can be called directly.

```APIDOC
## execle

### Description
Executes a file with a list of arguments and environment.

### Function
execle

### Parameters
No parameters documented.

### Return Value
Not documented.

### Example
Not provided.

```

--------------------------------

### Get the current player with get_side_to_move()

Source: https://jordanbray.github.io/chess/chess/struct.BoardBuilder.html

Returns the Color of the side to move. The example converts a default Board into a BoardBuilder and asserts the side is White.

```rust
use chess::{BoardBuilder, Board, Color};

let bb: BoardBuilder = Board::default().into();
assert_eq!(bb.get_side_to_move(), Color::White);
```

--------------------------------

### Get capacity of ArrayVec with capacity

Source: https://jordanbray.github.io/chess/arrayvec/struct.ArrayVec.html

Returns the capacity of the ArrayVec. The example creates an ArrayVec from an array and asserts the capacity equals the array length.

```rust
use arrayvec::ArrayVec;

let array = ArrayVec::from([1, 2, 3]);
assert_eq!(array.capacity(), 3);
```

--------------------------------

### Square::make_square example

Source: https://jordanbray.github.io/chess/chess/struct.Square.html

Creates a square from a rank and file, converts it to a bitboard, and verifies the conversion.

```rust
use chess::{Square, Rank, File, BitBoard};

// Make the A1 square
let sq = Square::make_square(Rank::First, File::A);

// Convert it to a bitboard
let bb = BitBoard::from_square(sq);

// loop over all squares in the bitboard (should be only one), and ensure that the square
// is what we created
for x in bb {
    assert_eq!(sq, x);
}
```

--------------------------------

### Default implementation example: create square on A1

Source: https://jordanbray.github.io/chess/chess/struct.Square.html

Shows how to use Square::default() to create a square on A1, and verifies it equals an explicitly constructed square using Square::make_square(Rank::First, File::A). Requires importing chess::{Square, Rank, File}.

```rust
use chess::{Square, Rank, File};

let explicit_sq = Square::make_square(Rank::First, File::A);
let implicit_sq = Square::default();

assert_eq!(explicit_sq, implicit_sq);
```

--------------------------------

### Get length of ArrayVec with len

Source: https://jordanbray.github.io/chess/arrayvec/struct.ArrayVec.html

Returns the number of elements in the ArrayVec. The example creates an ArrayVec from an array, pops an element, and asserts the length is 2.

```rust
use arrayvec::ArrayVec;

let mut array = ArrayVec::from([1, 2, 3]);
array.pop();
assert_eq!(array.len(), 2);
```

--------------------------------

### Doc comment interpolation fails - doc attribute

Source: https://jordanbray.github.io/chess/quote/macro.quote.html

This example deliberately fails to compile. String literals in doc attributes do not get interpolation behavior in quote!.

```rust
quote! {
    #[doc = "try to interpolate: #ident"]
}
```

--------------------------------

### posix_spawn_file_actions_init

Source: https://jordanbray.github.io/chess/libc/fn.posix_spawn_file_actions_init.html

Initializes a posix_spawn_file_actions_t object before use with posix_spawn or posix_spawnp. This function must be called before any other file action functions.

```APIDOC
## Function: posix_spawn_file_actions_init

### Description
Initializes a posix_spawn_file_actions_t object before use with posix_spawn or posix_spawnp. This function must be called before any other file action functions.

### Signature
```c
pub unsafe extern "C" fn posix_spawn_file_actions_init(
    actions: *mut posix_spawn_file_actions_t
) -> c_int
```

### Parameters
- **actions** (*mut posix_spawn_file_actions_t) - Required - Pointer to the file actions object to initialize.

### Return Value
- **c_int** - Returns 0 on success, or an error number on failure.

### Safety
This function is unsafe because it dereferences a raw pointer. The caller must ensure that the pointer is valid and properly aligned.
```

--------------------------------

### piece_on: Get piece on a square

Source: https://jordanbray.github.io/chess/chess/struct.Board.html

Returns the piece on a given square, or None if empty. Example shows a default board with a rook on A1 and no piece on D4.

```rust
use chess::{Board, Piece, Square};

let board = Board::default();

assert_eq!(board.piece_on(Square::A1), Some(Piece::Rook));
assert_eq!(board.piece_on(Square::D4), None);
```
Tokens:
Raw