Rust shogi crates: Core (rlib)

This crate defines fundamental types and functions for shogi (Japanese chess). The documentation of this crate may be used for the reference of detailed rules of shogi, although it is not intended for introduction to rules.

Supported use cases

This crate supports users that follow shogi rules or something stricter than them, such as shogi engines, capture-only variant shogi engines, mate solvers, helpmate solvers, stalemate solvers. This crate does not support fairy mate problems in general. One might be able to make use of this crate for such shogi variants, but it is not guaranteed.

Provided functionalities

This crate provides fundamental data types and functions used in shogi.

This crate does not provide legality checking. There are many ways to check legality, so it is responsibility of other crates.

This crate supports output of SFEN + moves format. This helps easy testing of positions. This crate does not support reading of SFEN + moves format because of its complexity. Other crates are responsible for this.

Dependencies

This crate depends only on core::* and alloc::*. This crate does not depend on std::*.

There are environments where depending on alloc is impossible. In order to support such environments, items in this crate depend only on core as much as possible, and items that must depend on alloc are separated by alloc feature.

This crate does not depend on any other crates.

Panicking

Functions in this crate that do not depend on alloc do not panic. Functions that depend on alloc can panic because they require memory allocation, which can fail due to out of memory. Otherwise, they do not panic.

Safety

This crate may provide unsafe items under the following conditions:

• Only bare minimum unsafe items are provided.
• Unsafe items contain _unchecked in their name so that unsafety of them is obvious.
• In the Safety section in the document, the conditions imposed on arguments for an unsafe item not to cause undefined behavior are described.
• For each unsafe item, this crate provides its safe counterpart.

Types

This crate defines types representing the following entities. An entity below can depend on entities above.

• player to move
• square
• piece
• piece + player to move
• move
• hand
• subset of all squares (bitboard)
• position (pieces on the board, player to move, moves made so far)
• position with information (moves can have additional information)
• kinds of illegal moves

Types are defined so that discriminant elision applies for as many types as possible. Some types even have guarantees about discriminant elision.

Trait implementations

Traits for comparison: Eq, PartialEq, Ord and PartialOrd

Eq and PartialEq are implemented for all types because we need equality testing in tests anyway, and because if we need equality testing in tests, there are assumed to be other use cases. Ord and PartialOrd are implemented when ord feature is enabled (which is disabled by default), so that types in this crate can be used as keys of e.g. BTreeMap.

Traits for copying: Clone and Copy

Clone is implemented for every type. Copy is implemented if we can assume that a type will be Copy forever. For example, player to move, square, piece and hand implement Copy, but position doesn't.

Hash

There are assumed to be two main use cases when one wants to take a hash value of data of shogi:

1. Accessing transposition table using hash values for fast shogi engines.
2. Using data structures like HashMap in order to casually create maps whose keys are positions.

For 1., it is not the place of implementations in the library because one needs to make their own hash function. For 2., some but not all users may need these implementations. They are made available if the hash feature is enabled.

Default

Bitboard and position implement Default. The other types don't implement Default because there are no values suitable for default.

Debug

Always implemented.

Display

Not implemented because there are multiple string representations and no canonical string representation among them. (For example, a pawn can be represented as 歩, FU, P or Pawn.) This crate defines the trait ToUsi which defines to_usi method, which handles conversion to string representations in USI format.

From, TryFrom

Implemented when necessary.

AsRef, AsMut

Not implemented.

Available features

• alloc: alloc-related functionalities are made available. Enabled by default.
• std: std-related functionalities are made available. Implies alloc. Enabled by default.
• hash: implements Hash for every type it exports.
• ord: implements PartialOrd and Ord for every type it exports.
• experimental: enables experimental functionalities. Items marked as experimental are considered exempt from semantic versioning, and subject to change or deletion without notice.