Shakmaty

https://docs.rs/shakmaty/latest/
Admin
Shakmaty is a Rust library for chess variant rules and operations, providing functionalities like...
Tokens:321,331
Snippets:2,737
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Into Mirrored Example

Source: https://docs.rs/shakmaty/latest/src/shakmaty/setup.rs.html

Demonstrates creating a new `Setup` instance that is a vertically mirrored version of the original, without modifying the original `Setup`.

```rust
use shakmaty::{Bitboard, Board, Color, File, Rank, Setup, Square};

let setup = Setup::initial();
let mirrored_setup = setup.into_mirrored();

// Check if board is mirrored
assert_eq!(mirrored_setup.board.get(&Square::new(File::A, Rank::First)), Board::new().get(&Square::new(File::A, Rank::Eighth)));

// Check if turn is swapped
assert_eq!(mirrored_setup.turn, Color::Black);

// Check if castling rights are mirrored
assert_eq!(mirrored_setup.castling_rights, Bitboard::CORNERS.flip_vertical());
```

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

### Setup::initial() Constructor

Source: https://docs.rs/shakmaty/latest/src/shakmaty/setup.rs.html

Shows the creation of the initial chess board setup. This includes the standard starting piece positions and castling rights.

```rust
use shakmaty::{Bitboard, Board, Setup};

let setup = Setup::initial();

assert_eq!(setup.board, Board::new());
assert_eq!(setup.castling_rights, Bitboard::CORNERS);
assert_eq!(setup.turn, Color::White);
assert_eq!(setup.halfmoves, 0);
assert_eq!(setup.fullmoves.get(), 1);
```

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

### Into Swapped Turn Example

Source: https://docs.rs/shakmaty/latest/src/shakmaty/setup.rs.html

Shows how to create a new `Setup` instance with the turn swapped and en passant rights discarded, without modifying the original `Setup`.

```rust
use shakmaty::{Color, Setup};

let setup = Setup::default();
let initial_turn = setup.turn;

let swapped_setup = setup.into_swapped_turn();

assert_eq!(setup.turn, initial_turn);
assert_eq!(swapped_setup.turn, initial_turn.other());
assert_eq!(swapped_setup.ep_square, None);
```

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

### Setup Creation

Source: https://docs.rs/shakmaty/latest/shakmaty/struct.Setup.html

Methods for creating new Setup instances.

```APIDOC
## Setup::empty()

### Description
Creates a plain, empty board with no pieces. White is set to play.

### Method
`const fn`

### Returns
`Setup` - An empty board setup.
```

```APIDOC
## Setup::initial()

### Description
Creates a board with the default, initial chess setup.

### Method
`const fn`

### Returns
`Setup` - The default initial board setup.
```

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

### Position Conversion Example

Source: https://docs.rs/shakmaty/latest/src/shakmaty/setup.rs.html

Shows how to convert a `Setup` struct into a more specific position type using the `position` method. This requires the target type to implement `FromSetup`.

```rust
use shakmaty::{CastlingMode, Setup};
use shakmaty::fen::Fen;

let setup = Setup::default();
let fen_position = setup.position::<Fen>(CastlingMode::Standard).unwrap();

assert_eq!(fen_position.to_string(), "8/8/8/8/8/8/8/8 w - - 0 1");
```

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

### fn from_setup(setup: Setup, mode: CastlingMode) -> Result<Chess, PositionError<Chess>>

Source: https://docs.rs/shakmaty/latest/shakmaty/struct.Chess.html

Sets up a playable Chess position from a given setup configuration and castling mode.

```APIDOC
## fn from_setup(setup: Setup, mode: CastlingMode) -> Result<Chess, PositionError<Chess>>

### Description
Set up a playable `Position`.

### Parameters
#### Path Parameters
- **setup** (Setup) - Required - The setup configuration for the position.
- **mode** (CastlingMode) - Required - The castling mode to apply.

### Returns
- `Result<Chess, PositionError<Chess>>`: A `Chess` position if successful, or a `PositionError` otherwise.
```

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

### Get Setup from Fen

Source: https://docs.rs/shakmaty/latest/shakmaty/fen/struct.Fen.html

Returns a reference to the Setup struct contained within the Fen. This allows inspecting the board's configuration without consuming the Fen.

```rust
pub const fn as_setup(&self) -> &Setup
```

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

### Setup::empty() Constructor

Source: https://docs.rs/shakmaty/latest/src/shakmaty/setup.rs.html

Illustrates the creation of an empty board setup. This setup has no pieces, no castling rights, and it's White's turn to move.

```rust
use shakmaty::{Bitboard, Board, Color, NonZeroU32, Setup};

let setup = Setup::empty();

assert_eq!(setup.board, Board::empty());
assert_eq!(setup.pockets, None);
assert_eq!(setup.promoted, Bitboard::EMPTY);
assert_eq!(setup.turn, Color::White);
assert_eq!(setup.castling_rights, Bitboard::EMPTY);
assert_eq!(setup.ep_square, None);
assert_eq!(setup.remaining_checks, None);
assert_eq!(setup.halfmoves, 0);
assert_eq!(setup.fullmoves, NonZeroU32::MIN);
```

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

### Setup::initial

Source: https://docs.rs/shakmaty/latest/src/shakmaty/setup.rs.html

Creates the default initial board setup for a standard chess game. This is a constant function.

```APIDOC
## Setup::initial

### Description
Creates the default initial board setup for a standard chess game. This is a constant function.

### Signature
```rust
pub const fn initial() -> Setup
```

### Returns
A new `Setup` instance representing the initial chess board.
```

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

### Square::new Example

Source: https://docs.rs/shakmaty/latest/src/shakmaty/square.rs.html

Demonstrates how to get a `Square` from an integer index. This example is a placeholder and would typically show usage.

```rust
/// Gets a `Square` from an integer index.
///
/// # Panics
///
/// Panics if the index is not in the range `0..=63`.
///
/// # Examples
///
/// ```
```

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

### Setup FEN and Get Legal Moves

Source: https://docs.rs/shakmaty/latest/src/shakmaty/position.rs.html

Sets up a chess position from a FEN string and retrieves all legal moves. Asserts that all moves are pawn promotions.

```rust
let pos: Chess = setup_fen("3r3K/6PP/8/8/8/2k5/8/8 w - - 0 1");

        let moves = pos.legal_moves();
        assert!(moves.iter().all(|m| m.role() == Role::Pawn));
        assert!(moves.iter().all(|m| m.is_promotion()));
```

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

### Setup Antichess Position from Setup

Source: https://docs.rs/shakmaty/latest/shakmaty/variant/struct.Antichess.html

Sets up a playable Antichess position from a given Setup and CastlingMode. Returns a Result indicating success or a PositionError.

```rust
fn from_setup( setup: Setup, mode: CastlingMode, ) -> Result<Antichess, PositionError<Antichess>>
```

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

### Setup Conversion

Source: https://docs.rs/shakmaty/latest/shakmaty/struct.Setup.html

Methods for converting a Setup instance to other types or creating a Setup from other types.

```APIDOC
## Setup::position<P: FromSetup>(self, mode: CastlingMode) -> Result<P, PositionError<P>>

### Description
Converts the Setup into a position representation, potentially for use with other chess logic or data structures.

### Method
`self`

### Parameters
#### Query Parameters
- **mode** (`CastlingMode`) - Description of the castling mode to use during conversion.

### Returns
`Result<P, PositionError<P>>` - A Result containing the converted position of type `P` or a `PositionError`.
```

```APIDOC
## From<Epd> for Setup

### Description
Converts an `Epd` (Extended Position Description) string into a `Setup` object.

### Method
`from(epd: Epd)`

### Returns
`Setup` - The Setup object created from the Epd string.
```

```APIDOC
## From<Fen> for Setup

### Description
Converts a `Fen` (Forsyth-Edwards Notation) string into a `Setup` object.

### Method
`from(fen: Fen)`

### Returns
`Setup` - The Setup object created from the Fen string.
```

```APIDOC
## TryFrom<Setup> for Fen

### Description
Attempts to convert a `Setup` object into a `Fen` (Forsyth-Edwards Notation) string.

### Method
`try_from(setup: Setup)`

### Returns
`Result<Fen, LossyFenError<Fen>>` - A Result containing the Fen string or a `LossyFenError` if the conversion fails.
```

```APIDOC
## TryFrom<Setup> for Epd

### Description
Attempts to convert a `Setup` object into an `Epd` (Extended Position Description) string.

### Method
`try_from(setup: Setup)`

### Returns
`Result<Epd, LossyFenError<Epd>>` - A Result containing the Epd string or a `LossyFenError` if the conversion fails.
```

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

### Setup Manipulation

Source: https://docs.rs/shakmaty/latest/shakmaty/struct.Setup.html

Methods for modifying an existing Setup instance.

```APIDOC
## Setup::swap_turn(&mut self)

### Description
Swaps the current player's turn and discards any en passant rights. This is equivalent to playing a null move.

### Method
`&mut self`

### Returns
`()` - Modifies the Setup in place.
```

```APIDOC
## Setup::into_swapped_turn(self) -> Setup

### Description
Returns a new Setup instance with the turn swapped and en passant rights discarded.

### Method
`self`

### Returns
`Setup` - A new Setup instance with the turn swapped.
```

```APIDOC
## Setup::mirror(&mut self)

### Description
Mirrors the board vertically, swaps turns, and flips all piece colors. The resulting setup is equivalent to standard chess mirroring.
Move counters remain unchanged.

### Method
`&mut self`

### Returns
`()` - Modifies the Setup in place.
```

```APIDOC
## Setup::into_mirrored(self) -> Setup

### Description
Returns a new Setup instance that is a vertically mirrored version of the original, with turns swapped and piece colors flipped.

### Method
`self`

### Returns
`Setup` - A new, mirrored Setup instance.
```

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

### Setup::into_mirrored

Source: https://docs.rs/shakmaty/latest/src/shakmaty/setup.rs.html

Returns a new `Setup` instance that is a vertically mirrored version of the original, consuming the original instance.

```APIDOC
## Setup::into_mirrored

### Description
Returns a new `Setup` instance that is a vertically mirrored version of the original, consuming the original instance.

### Signature
```rust
#[must_use]
pub fn into_mirrored(mut self) -> Setup
```

### Parameters
- `self`: The `Setup` instance to consume.

### Returns
A new `Setup` instance representing the mirrored board.
```

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

### Example: Parsing a Standard FEN String

Source: https://docs.rs/shakmaty/latest/src/shakmaty/fen.rs.html

Demonstrates parsing a standard FEN string into a `Fen` object. This example shows successful parsing of the default starting position.

```rust
let fen = Fen::from_ascii(b"rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1")?;
assert_eq!(fen, Fen::default());
# Ok::<_, shakmaty::fen::ParseFenError>(())
```

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

### Fen::from(Setup)

Source: https://docs.rs/shakmaty/latest/shakmaty/fen/struct.Fen.html

Converts a Setup type into a Fen value.

```APIDOC
## Fen::from(Setup)

### Description
Converts a Setup type into a Fen value.

### Method
`from(fen: Fen) -> Setup`
```

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

### Example: Handling Invalid Castling Rights during FEN Conversion

Source: https://docs.rs/shakmaty/latest/src/shakmaty/fen.rs.html

Demonstrates how to handle errors when converting a `Setup` to a `Fen` due to invalid castling rights. It shows asserting the error kind and then using `ignore` to proceed with a potentially lossy conversion.

```rust
let mut setup = Setup::default();

// Too many castling rights
setup.castling_rights.add(Square::G1);
assert_eq!(Fen::try_from_setup(setup.clone()).unwrap_err().kinds(), LossyFenErrorKinds::CASTLING_RIGHTS);

// Proceed regardless (picks the first two castling rights that can be
// syntactically represented, even illegal ones)
let fen = Fen::try_from_setup(setup).unwrap_or_else(LossyFenError::ignore);
assert_eq!(fen.to_string(), "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w GQkq - 0 1");
```

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

### Fen::try_from_setup

Source: https://docs.rs/shakmaty/latest/shakmaty/fen/struct.Fen.html

Prepares the FEN representation for a given Setup, returning an error if the setup cannot be losslessly represented as FEN.

```APIDOC
## Fen::try_from_setup

### Description
Prepare the FEN representation for a given `Setup`.

### Signature
```rust
pub fn try_from_setup(setup: Setup) -> Result<Fen, LossyFenError<Fen>>
```

### Errors
Errors if the setup can not be losslessly represented as FEN:
  * More than two castling rights per side or castling rights not on the backrank.
  * More than 64 Crazyhouse pocket pieces.
  * Set of squares with promoted Crazyhouse pieces does not match the pieces on the board.

### Example
```rust
use shakmaty::{Setup, Square, fen::{Fen, LossyFenError, LossyFenErrorKinds}};

let mut setup = Setup::default();

// Too many castling rights
setup.castling_rights.add(Square::G1);
assert_eq!(Fen::try_from_setup(setup.clone()).unwrap_err().kinds(), LossyFenErrorKinds::CASTLING_RIGHTS);

// Proceed regardless (picks the first two castling rights that can be
// syntactically represented, even illegal ones)
let fen = Fen::try_from_setup(setup).unwrap_or_else(LossyFenError::ignore);
assert_eq!(fen.to_string(), "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w GQkq - 0 1");
```
```

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

### Packing a Standard Chess Setup

Source: https://docs.rs/shakmaty/latest/shakmaty/packed/struct.PackedSetup.html

Demonstrates how to pack a standard chess setup into a compact byte representation using `PackedSetup::pack_standard`.

```APIDOC
## Packing a Standard Chess Setup

This example shows how to convert a `Setup` object representing a standard chess position into its compact byte format using `PackedSetup::pack_standard`.

### Method

```rust
PackedSetup::pack_standard(setup: &Setup) -> Result<PackedSetup, PackSetupError>
```

### Parameters

*   `setup` (*Setup*) - The standard chess setup to pack.

### Returns

A `Result` containing the `PackedSetup` if successful, or a `PackSetupError` if the setup cannot be packed losslessly (e.g., due to invalid en passant squares, missing castling rights, or variant-specific issues in a standard context).

### Example

```rust
use shakmaty::{Chess, EnPassantMode, packed::PackedSetup, Position, Setup};

let pos = Chess::default();
let setup = pos.to_setup(EnPassantMode::Always);
let packed = PackedSetup::pack_standard(&setup)?;
let bytes = packed.as_bytes();
```
```

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

### Pack Standard Chess Setup

Source: https://docs.rs/shakmaty/latest/src/shakmaty/packed.rs.html

Constructs a compactly packed equivalent of a standard chess setup, including move counters. Errors can occur if the setup is invalid.

```rust
pub fn pack_standard(setup: &Setup) -> Result<PackedSetup, PackSetupError> {
        PackedSetup::pack_internal(setup, setup.halfmoves, setup.fullmoves, 0)
    }
```

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

### Position::from_setup

Source: https://docs.rs/shakmaty/latest/src/shakmaty/position.rs.html

Sets up a playable position from a given Setup configuration. It returns a Result which can be an error if the setup does not meet basic validity requirements.

```APIDOC
## Position::from_setup

### Description
Sets up a playable position from a given `Setup` configuration. It returns a `Result` which can be an error if the setup does not meet basic validity requirements.

### Method
`fn from_setup(setup: Setup, mode: CastlingMode) -> Result<Self, PositionError<Self>>`

### Parameters
* `setup` (Setup) - The setup configuration for the position.
* `mode` (CastlingMode) - The castling mode to apply.

### Returns
* `Result<Self, PositionError<Self>>` - A `Result` containing the created `Position` or a `PositionError`.

### Examples
```rust
use shakmaty::{CastlingMode, Chess, FromSetup, Setup, PositionError};

let setup = Setup::default();

let pos = Chess::from_setup(setup, CastlingMode::Standard)
    .or_else(PositionError::ignore_too_much_material)
    .or_else(PositionError::ignore_impossible_check)?;
```
```

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

### Setup::empty

Source: https://docs.rs/shakmaty/latest/src/shakmaty/setup.rs.html

Creates a plain, empty board with no pieces and White to move. This is a constant function for creating an empty setup.

```APIDOC
## Setup::empty

### Description
Creates a plain, empty board with no pieces and White to move. This is a constant function for creating an empty setup.

### Signature
```rust
pub const fn empty() -> Setup
```

### Returns
A new `Setup` instance representing an empty board.
```

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

### Unpacking a Standard Chess Setup

Source: https://docs.rs/shakmaty/latest/shakmaty/packed/struct.PackedSetup.html

Demonstrates how to unpack a compact byte representation back into a standard chess setup using `PackedSetup::unpack_standard`.

```APIDOC
## Unpacking a Standard Chess Setup

This example shows how to convert a `PackedSetup` byte representation back into a `Setup` object for a standard chess position using `PackedSetup::unpack_standard`.

### Method

```rust
PackedSetup::unpack_standard(&self) -> Result<Setup, UnpackSetupError>
```

### Parameters

*   `self` (*PackedSetup*) - The packed setup to unpack.

### Returns

A `Result` containing the `Setup` object if the unpacking is successful and the data represents a standard chess setup. Returns an `UnpackSetupError` if the encoding is invalid or if it does not represent a standard chess setup.

### Example

```rust
use shakmaty::{CastlingMode, FromSetup, packed::PackedSetup, Setup};

// Assuming 'bytes' is a valid PackedSetup byte representation
let packed = PackedSetup::try_from_bytes(bytes)?;
let setup = packed.unpack_standard()?;
let pos = Chess::from_setup(setup, CastlingMode::Chess960)?;
```
```

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

### Hashing and Setup

Source: https://docs.rs/shakmaty/latest/shakmaty/variant/struct.Chess.html

Methods related to Zobrist hashing and converting the position to a setup configuration.

```APIDOC
## update_zobrist_hash
### Description
Incrementally computes the Zobrist hash of the position after a move.
### Method
`update_zobrist_hash<V: ZobristValue>(&self, current: V, m: Move, _mode: EnPassantMode) -> Option<V>`
### Parameters
- **current** (`V`) - The current Zobrist hash value.
- **m** (`Move`) - The move that was played.
- **_mode** (`EnPassantMode`) - The en passant mode (unused in this context).
### Returns
An `Option` containing the updated Zobrist hash value, or `None` if the move is invalid for hashing.
```

```APIDOC
## to_setup
### Description
Converts the current position into a `Setup` configuration.
### Method
`to_setup(&self, mode: EnPassantMode) -> Setup`
### Parameters
- **mode** (`EnPassantMode`) - The en passant mode to consider for the setup.
### Returns
A `Setup` object representing the current board state.
```

```APIDOC
## zobrist_hash
### Description
Computes the Zobrist hash of the position from scratch. This hash includes the position but excludes halfmove clock and fullmove number.
### Method
`zobrist_hash<V: ZobristValue>(&self, mode: EnPassantMode) -> V`
### Parameters
- **mode** (`EnPassantMode`) - The en passant mode to consider for the hash calculation.
### Returns
The computed Zobrist hash value.
```

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

### Setup::into_swapped_turn

Source: https://docs.rs/shakmaty/latest/src/shakmaty/setup.rs.html

Returns a new `Setup` instance with the turn swapped and en passant rights discarded, consuming the original instance.

```APIDOC
## Setup::into_swapped_turn

### Description
Returns a new `Setup` instance with the turn swapped and en passant rights discarded, consuming the original instance.

### Signature
```rust
#[must_use]
pub const fn into_swapped_turn(mut self) -> Setup
```

### Parameters
- `self`: The `Setup` instance to consume.

### Returns
A new `Setup` instance with the turn swapped and en passant rights cleared.
```

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

### Fen::as_setup

Source: https://docs.rs/shakmaty/latest/shakmaty/fen/struct.Fen.html

Returns a reference to the Setup representation of the Fen.

```APIDOC
## Fen::as_setup

### Description
Returns a reference to the `Setup` representation of the `Fen`.

### Signature
```rust
pub const fn as_setup(&self) -> &Setup
```
```

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

### Examples for Getting Last Square

Source: https://docs.rs/shakmaty/latest/src/shakmaty/bitboard.rs.html

Illustrates retrieving the last square from an empty and a full bitboard.

```rust
use shakmaty::{Bitboard, Square};

assert_eq!(Bitboard::EMPTY.last(), None);
assert_eq!(Bitboard::FULL.last(), Some(Square::H8));
```

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

### Fen::into_setup

Source: https://docs.rs/shakmaty/latest/shakmaty/fen/struct.Fen.html

Consumes the Fen and returns its Setup representation.

```APIDOC
## Fen::into_setup

### Description
Consumes the `Fen` and returns its `Setup` representation.

### Signature
```rust
pub const fn into_setup(self) -> Setup
```
```

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

### ThreeCheck::from_setup

Source: https://docs.rs/shakmaty/latest/shakmaty/variant/struct.ThreeCheck.html

Sets up a playable ThreeCheck position from a given setup and castling mode.

```APIDOC
## ThreeCheck::from_setup

### Description
Set up a playable `Position`.

### Signature
```rust
pub fn from_setup( setup: Setup, mode: CastlingMode, ) -> Result<ThreeCheck, PositionError<ThreeCheck>>
```

### Parameters
- **setup**: `Setup` - The setup configuration for the position.
- **mode**: `CastlingMode` - The castling mode to apply.

### Returns
A `Result` containing either a `ThreeCheck` position on success or a `PositionError` on failure.
```

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

### Crazyhouse::from_setup() Implementation

Source: https://docs.rs/shakmaty/latest/shakmaty/variant/struct.Crazyhouse.html

Sets up a playable Crazyhouse position from a given setup and castling mode. Returns an error if the setup is invalid.

```rust
fn from_setup( setup: Setup, mode: CastlingMode, ) -> Result<Crazyhouse, PositionError<Crazyhouse>>
```

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

### Antichess Creation from Setup

Source: https://docs.rs/shakmaty/latest/src/shakmaty/position.rs.html

Creates an Antichess position from a Setup configuration. It validates en passant squares and castling rights, returning an error if the setup is invalid for Antichess rules.

```rust
fn from_setup(
            setup: Setup,
            mode: CastlingMode,
        ) -> Result<Antichess, PositionError<Antichess>> {
            let mut errors = PositionErrorKinds::empty();

            let ep_square = match EnPassant::from_setup(&setup) {
                Ok(ep_square) => ep_square,
                Err(()) => {
                    errors |= PositionErrorKinds::INVALID_EP_SQUARE;
                    None
                }
            };

            let pos = Antichess {
                board: setup.board,
                turn: setup.turn,
                castles: Castles::empty(mode),
                ep_square,
                halfmoves: setup.halfmoves,
                fullmoves: setup.fullmoves,
            };

            if setup.castling_rights.any() {
                errors |= PositionErrorKinds::INVALID_CASTLING_RIGHTS;
            }

            errors |= validate(&pos, ep_square)
                - PositionErrorKinds::MISSING_KING
                - PositionErrorKinds::TOO_MANY_KINGS
                - PositionErrorKinds::OPPOSITE_CHECK
                - PositionErrorKinds::IMPOSSIBLE_CHECK;

            PositionError { pos, errors }.strict()
        }
```

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

### Fen::try_from(Setup)

Source: https://docs.rs/shakmaty/latest/shakmaty/fen/struct.Fen.html

Attempts to convert a Setup type into a Fen value. Returns a LossyFenError if conversion fails.

```APIDOC
## Fen::try_from(Setup)

### Description
Performs the conversion from a Setup type to a Fen value. Returns a `LossyFenError<Fen>` in case of an error.

### Associated Type
`Error = LossyFenError<Fen>`

### Method
`try_from(setup: Setup) -> Result<Fen, LossyFenError<Fen>>`
```

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

### Convert Setup to Position with Castling Mode

Source: https://docs.rs/shakmaty/latest/src/shakmaty/fen.rs.html

Converts a setup configuration into a chess position, specifying the castling mode. This is useful when initializing a game state from a known setup.

```rust
pub fn into_position<P: FromSetup>(self, mode: CastlingMode) -> Result<P, PositionError<P>> {
        P::from_setup(self.into_setup(), mode)
    }
```

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

### Convert Setup to EPD

Source: https://docs.rs/shakmaty/latest/src/shakmaty/fen.rs.html

Attempts to convert a `Setup` struct into an `Epd` struct. This conversion can fail if the provided setup data is invalid for EPD representation.

```rust
impl TryFrom<Setup> for Epd {
    type Error = LossyFenError<Epd>;

    fn try_from(setup: Setup) -> Result<Epd, LossyFenError<Epd>> {
        Epd::try_from_setup(setup)
    }
}
```

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

### Create a Playable Position from Setup

Source: https://docs.rs/shakmaty/latest/src/shakmaty/position.rs.html

Use `from_setup` to create a playable `Position`. It returns a `Result` which can be handled with `or_else` to ignore specific `PositionError` types if the setup does not meet basic validity requirements.

```rust
use shakmaty::{CastlingMode, Chess, FromSetup, Setup, PositionError};

let setup = Setup::default();

let pos = Chess::from_setup(setup, CastlingMode::Standard)
    .or_else(PositionError::ignore_too_much_material)
    .or_else(PositionError::ignore_impossible_check)?;

# Ok::<_, PositionError<_>>(())
```

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

### Hashing and Setup Conversion

Source: https://docs.rs/shakmaty/latest/shakmaty/variant/struct.RacingKings.html

Methods for Zobrist hash calculation and converting the position to a setup configuration.

```APIDOC
## fn update_zobrist_hash<V: ZobristValue>( &self, current: V, m: Move, _mode: EnPassantMode, ) -> Option<V>

### Description
Incrementally computes the Zobrist hash of the position after playing a legal move `m`. It assumes `current` is the Zobrist hash of the current position.

### Method
POST (conceptual)

### Endpoint
N/A (Method call)

### Parameters
- **current** (V: ZobristValue) - The Zobrist hash of the current position.
- **m** (Move) - The legal move that was played.
- **_mode** (EnPassantMode) - The en passant mode.

### Request Body
- **current** (V: ZobristValue) - Required - The current Zobrist hash.
- **m** (Move) - Required - The legal move played.
- **_mode** (EnPassantMode) - Required - The en passant mode.

### Response
- **Option<V>** - The updated Zobrist hash, or `None` if the update fails.
```

```APIDOC
## fn to_setup(&self, mode: EnPassantMode) -> Setup

### Description
Converts the current position into a `Setup` object, which can be used for reconstructing or serializing the position state.

### Method
GET (conceptual)

### Endpoint
N/A (Method call)

### Parameters
- **mode** (EnPassantMode) - The en passant mode to consider during conversion.

### Response
- **Setup** - The `Setup` representation of the current position.
```

```APIDOC
## fn zobrist_hash<V: ZobristValue>(&self, mode: EnPassantMode) -> V

### Description
Computes the Zobrist hash of the position from scratch. This hash includes the position's pieces and turn, but excludes the halfmove clock and fullmove number.

### Method
GET (conceptual)

### Endpoint
N/A (Method call)

### Parameters
- **mode** (EnPassantMode) - The en passant mode to consider for hashing.

### Response
- **V** (V: ZobristValue) - The computed Zobrist hash.
```

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

### Create Chess Position from Setup

Source: https://docs.rs/shakmaty/latest/shakmaty/struct.Chess.html

Sets up a playable Chess position from a given Setup configuration and CastlingMode. Returns a Result indicating success or a PositionError.

```rust
fn from_setup( setup: Setup, mode: CastlingMode, ) -> Result<Chess, PositionError<Chess>>
```

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

### Packing Standard Setup Normalized

Source: https://docs.rs/shakmaty/latest/shakmaty/packed/struct.PackedSetup.html

Packs a standard chess setup, ignoring move counters.

```APIDOC
## Packing Standard Setup Normalized

Constructs a compactly packed equivalent of the given standard chess setup, ignoring move counters. This is useful when the move counters are not relevant for the packing.

### Method

```rust
PackedSetup::pack_standard_normalized(setup: &Setup) -> Result<PackedSetup, PackSetupError>
```

### Parameters

*   `setup` (*&Setup*) - The standard chess setup to pack.

### Returns

A `Result` containing the `PackedSetup` if successful, or a `PackSetupError` if the setup cannot be packed losslessly (similar conditions to `pack_standard`).

### Example

```rust
use shakmaty::{Chess, EnPassantMode, packed::PackedSetup, Position, Setup};

let pos = Chess::default();
let setup = pos.to_setup(EnPassantMode::Always);
let packed = PackedSetup::pack_standard_normalized(&setup)?;
```
```

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

### Packing a Standard Chess Setup

Source: https://docs.rs/shakmaty/latest/src/shakmaty/packed.rs.html

Demonstrates how to pack a standard chess position into a compact byte representation using `PackedSetup::pack_standard`. Ensure the setup is valid for packing.

```rust
use shakmaty::{Chess, EnPassantMode, packed::PackedSetup, Position};

let pos = Chess::default();
let setup = pos.to_setup(EnPassantMode::Always);
let packed = PackedSetup::pack_standard(&setup)?;
let bytes = packed.as_bytes();
assert!(bytes.len() <= PackedSetup::MAX_BYTES);
Ok::<_, shakmaty::packed::PackSetupError>(())
```

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

### Create ThreeCheck from setup

Source: https://docs.rs/shakmaty/latest/shakmaty/variant/struct.ThreeCheck.html

Sets up a playable ThreeCheck position from a given Setup and CastlingMode. Returns a Result which may contain a PositionError.

```rust
fn from_setup( setup: Setup, mode: CastlingMode, ) -> Result<ThreeCheck, PositionError<ThreeCheck>>
```

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

### Pack Variant Chess Setup

Source: https://docs.rs/shakmaty/latest/src/shakmaty/packed.rs.html

Constructs a compactly packed equivalent of a variant chess setup, including move counters. Errors occur if the variant setup cannot be packed losslessly.

```rust
#[cfg(feature = "variant")]
    pub fn pack_variant(setup: &Setup, variant: Variant) -> Result<PackedSetup, PackSetupError> {
        PackedSetup::pack_internal(
            setup,
            setup.halfmoves,
            setup.fullmoves,
            variant_to_byte(variant),
        )
    }
```

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

### Unpacking Variant Setup

Source: https://docs.rs/shakmaty/latest/shakmaty/packed/struct.PackedSetup.html

Unpacks a variant chess setup. Requires the `variant` feature.

```APIDOC
## Unpacking Variant Setup

Unpacks a variant setup into a `Setup` object and its corresponding `Variant`. This method is available only when the `variant` crate feature is enabled. It may fail if the encoding is invalid.

### Method

```rust
PackedSetup::unpack_variant(&self) -> Result<(Setup, Variant), UnpackSetupError>
```

### Parameters

*   `self` (*PackedSetup*) - The packed setup instance to unpack.

### Returns

A `Result` containing a tuple of (`Setup`, `Variant`) if the unpacking is successful, or an `UnpackSetupError` if the encoding is invalid.

### Example

```rust
use shakmaty::{packed::PackedSetup, Variant, Setup};

// Assuming 'packed_setup' is a valid PackedSetup instance for a variant
// let (setup, variant) = packed_setup.unpack_variant()?;
```
```

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

### Try Convert Setup to Epd

Source: https://docs.rs/shakmaty/latest/shakmaty/fen/struct.Epd.html

Attempts to convert a Setup type into an Epd struct. Returns a LossyFenError on failure.

```rust
fn try_from(setup: Setup) -> Result<Epd, LossyFenError<Epd>>
```

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

### Create Fen from Setup with error handling

Source: https://docs.rs/shakmaty/latest/shakmaty/fen/struct.Fen.html

Attempts to create a Fen from a Setup, returning an error if the setup cannot be losslessly represented as FEN. Handles specific errors like invalid castling rights or Crazyhouse piece counts.

```rust
use shakmaty::{Setup, Square, fen::{Fen, LossyFenError, LossyFenErrorKinds}};

let mut setup = Setup::default();

// Too many castling rights
setup.castling_rights.add(Square::G1);
assert_eq!(Fen::try_from_setup(setup.clone()).unwrap_err().kinds(), LossyFenErrorKinds::CASTLING_RIGHTS);

// Proceed regardless (picks the first two castling rights that can be
// syntactically represented, even illegal ones)
let fen = Fen::try_from_setup(setup).unwrap_or_else(LossyFenError::ignore);
assert_eq!(fen.to_string(), "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w GQkq - 0 1");
```

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

### Packing Variant Setup

Source: https://docs.rs/shakmaty/latest/shakmaty/packed/struct.PackedSetup.html

Packs a variant chess setup. Requires the `variant` feature to be enabled.

```APIDOC
## Packing Variant Setup

Constructs a compactly packed equivalent of the given variant setup. This method is available only when the `variant` crate feature is enabled.

### Method

```rust
PackedSetup::pack_variant(setup: &Setup, variant: Variant) -> Result<PackedSetup, PackSetupError>
```

### Parameters

*   `setup` (*&Setup*) - The variant chess setup to pack.
*   `variant` (*Variant*) - The `Variant` enum specifying the type of chess variant.

### Returns

A `Result` containing the `PackedSetup` if successful, or a `PackSetupError` if the setup cannot be packed losslessly (e.g., invalid en passant, castling rights, or variant-specific rules violations like Crazyhouse pockets).

### Example

```rust
use shakmaty::{packed::PackedSetup, Variant, Setup};

// Assuming 'variant_setup' and 'variant_type' are defined
// let packed = PackedSetup::pack_variant(&variant_setup, variant_type)?;
```
```

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

### Castles::from_setup

Source: https://docs.rs/shakmaty/latest/shakmaty/struct.Castles.html

Creates a Castles instance from a given board setup and castling mode.

```APIDOC
## Castles::from_setup

### Description
Creates a Castles instance from a given board setup and castling mode.

### Method
`fn from_setup(setup: &Setup, mode: CastlingMode) -> Result<Castles, Castles>`
```

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

### Unpacking a Packed Chess Setup

Source: https://docs.rs/shakmaty/latest/src/shakmaty/packed.rs.html

Shows how to unpack a compact byte representation back into a standard chess setup using `PackedSetup::try_from_bytes` and `PackedSetup::unpack_standard`. This allows reconstructing a `Chess` position.

```rust
# use shakmaty::{Chess, EnPassantMode, packed::PackedSetup, Position};
# 
# fn main() -> Result<(), Box<dyn core::error::Error>> {
#     let packed = PackedSetup::pack_standard(&Chess::default().to_setup(EnPassantMode::Always))?;
#     let bytes = packed.as_bytes();
use shakmaty::{CastlingMode, FromSetup};

let packed = PackedSetup::try_from_bytes(bytes)?;
let setup = packed.unpack_standard()?;
let pos = Chess::from_setup(setup, CastlingMode::Chess960)?;
assert_eq!(pos, Chess::default());
#     Ok(())
# }
```

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

### Board::new

Source: https://docs.rs/shakmaty/latest/src/shakmaty/board.rs.html

Initializes a new Board with the standard chess starting position.

```APIDOC
## Board::new

### Description
Initializes a new Board with the standard chess starting position.

### Method
Associated function (constructor)

### Signature
`pub const fn new() -> Board`

### Example
```rust
use shakmaty::Board;

let board = Board::new();
```
```

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

### Test Standard Setup Packing and Unpacking

Source: https://docs.rs/shakmaty/latest/src/shakmaty/packed.rs.html

Checks the serialization and deserialization of a standard chess setup, including size validation.

```rust
#[test]
    fn test_read_write_standard_setup() {
        let setup = Setup::default();

        let packed = PackedSetup::pack_standard(&setup).expect("representable");
        assert!(packed.as_bytes().len() == 24);

        let roundtripped = packed.unpack_standard().expect("roundtrip");
        assert_eq!(roundtripped, setup);
    }
```

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

### Try Create Epd from Setup

Source: https://docs.rs/shakmaty/latest/shakmaty/fen/struct.Epd.html

Attempts to create an Epd struct from a Setup type. This operation can fail and return a LossyFenError.

```rust
pub fn try_from_setup(setup: Setup) -> Result<Epd, LossyFenError<Epd>>
```

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

### Equality and Hashing

Source: https://docs.rs/shakmaty/latest/shakmaty/struct.Setup.html

Methods for comparing Setup instances and hashing them.

```APIDOC
## Setup::eq(&self, other: &Setup) -> bool

### Description
Tests if two `Setup` objects are equal. Used by the `==` operator.

### Method
`&self, other: &Setup`

### Returns
`bool` - `true` if the setups are equal, `false` otherwise.
```

```APIDOC
## Setup::ne(&self, other: &Rhs) -> bool

### Description
Tests if two `Setup` objects are not equal. Used by the `!=` operator.

### Method
`&self, other: &Rhs`

### Returns
`bool` - `true` if the setups are not equal, `false` otherwise.
```

```APIDOC
## Setup::hash<__H: Hasher>(&self, state: &mut __H)

### Description
Feeds the `Setup` object into a given `Hasher` to compute its hash value.

### Method
`&self, state: &mut __H`

### Returns
`()` - Modifies the hasher state.
```

```APIDOC
## Setup::hash_slice<H>(data: &[Self], state: &mut H)

### Description
Feeds a slice of `Setup` objects into a given `Hasher`.

### Method
`data: &[Self], state: &mut H`

### Returns
`()` - Modifies the hasher state.
```

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

### Convert Position to Setup

Source: https://docs.rs/shakmaty/latest/src/shakmaty/position.rs.html

The `to_setup` method converts the current `Position` into a `Setup` struct, capturing all relevant game state information like board, turn, castling rights, and en passant targets.

```rust
Setup {
    board: self.board().clone(),
    promoted: self.promoted(),
    pockets: self.pockets().copied(),
    turn: self.turn(),
    castling_rights: self.castles().castling_rights(),
    ep_square: self.ep_square(mode),
    remaining_checks: self.remaining_checks().copied(),
    halfmoves: self.halfmoves(),
    fullmoves: self.fullmoves(),
}
```

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

### Create Castles from Setup

Source: https://docs.rs/shakmaty/latest/src/shakmaty/setup.rs.html

Constructs a Castles struct from a given board setup, determining rook positions and attack paths for both standard and Chess960 modes.

```rust
impl Castles {
    pub fn from_setup(setup: &Setup, mode: CastlingMode) -> Result<Castles, Castles> {
        let mut castles = Castles::empty(mode);
        let rooks = setup.castling_rights & setup.board.rooks();

        for color in Color::ALL {
            if let Some(king) = setup.board.king_of(color) {
                if king.rank() != color.fold_wb(Rank::First, Rank::Eighth) {
                    continue;
                }

                let side = rooks & setup.board.by_color(color) & color.backrank();

                if let Some(a_side) = side.first().filter(|rook| rook.file() < king.file()) {
                    let rook_to = CastlingSide::QueenSide.rook_to(color);
                    let king_to = CastlingSide::QueenSide.king_to(color);
                    let chess960 = king.file() != File::E || a_side.file() != File::A;
                    if !chess960 || mode.is_chess960() {
                        castles.mask.add(a_side);
                        castles.rook.get_mut(color).queen_side = Some(a_side);
                        castles.path.get_mut(color).queen_side =
                            (attacks::between(a_side, rook_to).with(rook_to)
                                | attacks::between(king, king_to).with(king_to))
                            .without(king)
                            .without(a_side);
                    }
                }

                if let Some(h_side) = side.last().filter(|rook| king.file() < rook.file()) {
                    let rook_to = CastlingSide::KingSide.rook_to(color);
                    let king_to = CastlingSide::KingSide.king_to(color);
                    let chess960 = king.file() != File::E || h_side.file() != File::H;
                    if !chess960 || mode.is_chess960() {
                        castles.mask.add(h_side);
                        castles.rook.get_mut(color).king_side = Some(h_side);
                        castles.path.get_mut(color).king_side = (attacks::between(h_side, rook_to)
                            .with(rook_to)
                            | attacks::between(king, king_to).with(king_to))
                        .without(king)
                        .without(h_side);
                    }
                }
            }
        }

        if castles.castling_rights() == setup.castling_rights {
            Ok(castles)
        } else {

```

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

### Example Usage of from_setup for Chess

Source: https://docs.rs/shakmaty/latest/shakmaty/trait.FromSetup.html

Demonstrates how to use the from_setup method to create a Chess position. It includes error handling for material and check conditions.

```rust
use shakmaty::{CastlingMode, Chess, FromSetup, Setup, PositionError};

let setup = Setup::default();

let pos = Chess::from_setup(setup, CastlingMode::Standard)
    .or_else(PositionError::ignore_too_much_material)
    .or_else(PositionError::ignore_impossible_check)?;
```

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

### Convert Setup to FEN with Error Handling

Source: https://docs.rs/shakmaty/latest/src/shakmaty/fen.rs.html

Attempts to convert a chess setup into a FEN string, returning an error if the setup cannot be losslessly represented. Handles specific error kinds like castling rights, pocket pieces, and promoted pieces.

```rust
pub fn try_from_setup(setup: Setup) -> Result<Fen, LossyFenError<Fen>> {
        let mut errors = LossyFenErrorKinds::empty();

        let promoted = representable_promoted(&setup.board, setup.promoted);
        if promoted != setup.promoted {
            errors |= LossyFenErrorKinds::PROMOTED;
        }

        let pockets = setup.pockets.as_ref().map(representable_pockets);
        if pockets != setup.pockets {
            errors |= LossyFenErrorKinds::POCKETS;
        }

        let castling_rights = representable_castling_rights(setup.castling_rights);
        if castling_rights != setup.castling_rights {
            errors |= LossyFenErrorKinds::CASTLING_RIGHTS;
        }

        let fen = Fen::from_setup_unchecked(Setup {
            promoted,
            pockets,
            castling_rights,
            ..setup
        });

        if errors.is_empty() {
            Ok(fen)
        } else {
            Err(LossyFenError { fen, errors })
        }
    }
```

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

### Packing Variant Setup Normalized

Source: https://docs.rs/shakmaty/latest/shakmaty/packed/struct.PackedSetup.html

Packs a variant chess setup, ignoring move counters. Requires the `variant` feature.

```APIDOC
## Packing Variant Setup Normalized

Constructs a compactly packed equivalent of the given variant setup, ignoring move counters. This method requires the `variant` crate feature to be enabled.

### Method

```rust
PackedSetup::pack_variant_normalized(setup: &Setup, variant: Variant) -> Result<PackedSetup, PackSetupError>
```

### Parameters

*   `setup` (*&Setup*) - The variant chess setup to pack.
*   `variant` (*Variant*) - The `Variant` enum specifying the type of chess variant.

### Returns

A `Result` containing the `PackedSetup` if successful, or a `PackSetupError` if the setup cannot be packed losslessly (similar conditions to `pack_variant`).

### Example

```rust
use shakmaty::{packed::PackedSetup, Variant, Setup};

// Assuming 'variant_setup' and 'variant_type' are defined
// let packed = PackedSetup::pack_variant_normalized(&variant_setup, variant_type)?;
```
```

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

### Test ThreeCheck Setup Packing and Unpacking

Source: https://docs.rs/shakmaty/latest/src/shakmaty/packed.rs.html

Ensures correct packing and unpacking of a ThreeCheck variant setup from a FEN string.

```rust
"3r1r2/ppp2pk1/6R1/5R2/2P1p3/8/P1P3PP/7K b - - 0 27 +2+0"
            .parse::<Fen>()
            .expect("valid fen")
            .into_setup();

        let (roundtripped, variant) = PackedSetup::pack_variant(&setup, Variant::ThreeCheck)
            .expect("representable")
            .unpack_variant()
            .expect("roundtrip");

        assert_eq!(setup, roundtripped);
        assert_eq!(variant, Variant::ThreeCheck);
    }
```

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

### Pack Standard Chess Setup (Normalized)

Source: https://docs.rs/shakmaty/latest/src/shakmaty/packed.rs.html

Constructs a compactly packed equivalent of a standard chess setup, ignoring move counters. This is useful for creating canonical representations.

```rust
pub fn pack_standard_normalized(setup: &Setup) -> Result<PackedSetup, PackSetupError> {
        PackedSetup::pack_internal(setup, 0, NonZeroU32::MIN, 0)
    }
```

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

### Get Chess960 starting position

Source: https://docs.rs/shakmaty/latest/src/shakmaty/board.rs.html

Generates the `Board` for a Chess960 starting position based on Sharnagl's indexing scheme (0-959). Panics if the index is out of bounds.

```rust
pub const fn chess960(sharnagl: u32) -> Board {
        assert!(sharnagl < 960);

        let bw = sharnagl % 4;
        let n = sharnagl / 4;
        let bb = n % 4;
        let n = n / 4;
        let q = n % 6;
        let n = n / 6;

        let mut n1 = 0;
        let mut n2 = 0;
        while n1 < 4 {
```
Tokens:
Raw