Struct tokyodoves::BoardBuilder

pub struct BoardBuilder { /* private fields */ }

A builder of Board.

This struct provides a variety of ways to construct Board. It creates Board in two steps:

1. Create a BoardBuilder object. Edit it if necessary.
2. Call a method to build Board.

In the first step, all information required to create Board has to be prepared. The following methods to create BoardBuilder are supported:

• new
  … creates the builder for the board at the begnining
• empty
  … creates the builder for the board without any doves (edit needed after construction!)
• from_str
  … creates the builder based on string expression.
• try_from_4x4_matrix
  … creates the builder based on 4x4 matrix (array of array)
• from_u16_bits
  … creates the builder based on u16 values representing positions of doves
• from_u64_bits
  … creates the builder based on u64 values representing positions of doves

The following methods are for editing BoardBuilder:

• put_dove
  … puts a dove on a position
• remove_dove
  … removes a dove at a position
• trim_outside_4x4
  … removes all doves outside 4x4 region

In the second step, BoardBuilder creates Board by one of the following methods:

• build
  … creates Board with checking the board to be created are legal. It needs unwrapping to extract Board.
• build_unchecked
  … creates Board without legality check.

See documentations and examples given to each method for more instructions.

Implementations

impl BoardBuilder

pub fn new() -> Self

Creates the builder to build the board at the beginning of the game.

Examples

use tokyodoves::{Board, BoardBuilder};

let board0 = Board::new();
let board1 = BoardBuilder::new().build()?;
let board2 = BoardBuilder::default().build()?;
assert_eq!(board0, board1);
assert_eq!(board0, board2);

pub fn empty() -> Self

Creates the builder to build the empty board.

It fails to build unless the status is editted.

Examples

use tokyodoves::{Board, BoardBuilder, Color, Dove};

let mut builder = BoardBuilder::empty();
assert!(builder.build().is_err());
builder
    .put_dove(0, 0, Color::Green, Dove::B)
    .put_dove(1, 0, Color::Red, Dove::B);
let board = builder.build()?;
assert_eq!(board, Board::new());

pub fn from_u64_bits(positions: [[u64; 6]; 2]) -> Self

Creates BoardBuilder by indicating positions of doves by one-hot values of u64.

It is faster than the method from_u16_bits because u64 is more direct expression for internal implementation. It does not, however, ensure that all doves are included in the 4x4 region.

Each of elements of position indicates the position of each dove. The below shows which value represents the position of what kinds of dove.

positions = [
    ['B', 'A', 'Y', 'M', 'T', 'H'],
    ['b', 'a', 'y', 'm', 't', 'h']
]

Each position is expressed by a one-hot value, i.e., the value in binary that contains only one “1” bit. The diagram below shows what value should be used.

+------+------+------+------+
| 1<<0 | 1<<1 | 1<<2 | 1<<3 |
+------+------+------+------+
| 1<<8 | 1<<9 | 1<<10| 1<<11|
+------+------+------+------+
| 1<<16| 1<<17| 1<<18| 1<<19|
+------+------+------+------+
| 1<<24| 1<<25| 1<<26| 1<<27|
+------+------+------+------+

Values not shown in the above are outside the 4x4 region. If the dove is not on the board, set 0.

Note that it does NOT panic even if some element of position is not one-hot or out of the 4x4 region. Instead, the build method will return Err without any treatment.

Examples

use tokyodoves::{Board, BoardBuilder};

let bits = [[1 << 8, 0, 0, 0, 0, 0], [1, 0, 0, 0, 0, 0]];
let builder = BoardBuilder::from_u64_bits(bits);
// Equivalent:
// let builder = BoardBuilder::from(bits);
let board = builder.build()?;
assert_eq!(board, Board::new());

pub fn from_u16_bits(positions: [[u16; 6]; 2]) -> Self

Creates BoardBuilder by indicating positions of doves by one-hot values of u16.

This method is similar to the from_u64_bits method. This method ensures that all doves are included in the 4x4 region, in the cost of conversion from u16 to u64.

Each of elements of position indicates the position of each dove. The below shows which value represents the position of what kinds of dove.

positions = [
    ['B', 'A', 'Y', 'M', 'T', 'H'],
    ['b', 'a', 'y', 'm', 't', 'h']
]

Each position is expressed by a one-hot value, i.e., the value in binary that contains only one “1” bit. The diagram below shows what value should be used.

+------+------+------+------+
| 1<<0 | 1<<1 | 1<<2 | 1<<3 |
+------+------+------+------+
| 1<<4 | 1<<5 | 1<<6 | 1<<7 |
+------+------+------+------+
| 1<<8 | 1<<9 | 1<<10| 1<<11|
+------+------+------+------+
| 1<<12| 1<<13| 1<<14| 1<<15|
+------+------+------+------+

If the dove is not on the board, set 0.

Note that it does NOT panic even if some element of position is not one-hot. Instead, the build method will return Err without any treatment.

Examples

use tokyodoves::{Board, BoardBuilder};

let bits = [[1 << 4, 0, 0, 0, 0, 0], [1, 0, 0, 0, 0, 0]];
let builder = BoardBuilder::from_u16_bits(bits);
// Equivalent:
// let builder = BoardBuilder::from(bits);
let board = builder.build()?;
assert_eq!(board, Board::new());

pub fn try_from_4x4_matrix( matrix: [[Option<(Color, Dove)>; 4]; 4] ) -> Result<Self, Error>

Creates BoardBuilder from 4x4 matrix of doves, i.e., [[Option<(Color, Dove)>; 4]; 4].

Errors

It returns Err if the same dove with the same color is included in the matrix.

Examples

use tokyodoves::{Board, BoardBuilder, Color, Dove};

let matrix = [
    [Some((Color::Green, Dove::B)), None, None, None],
    [Some((Color::Red, Dove::B)), None, None, None],
    [None, None, None, None],
    [None, None, None, None],
];
let builder = BoardBuilder::try_from_4x4_matrix(matrix)?;
// Equivalent:
// let builder = BoardBuilder::try_from(matrix)?;
let board = builder.build()?;
assert_eq!(board, Board::new());

pub fn from_u64(hash: u64) -> Self

Creates BoardBuilder from u64 expression of Board.

See the documentation of the method to_u64 on Board for the definition of u64 expression.

use tokyodoves::{Board, BoardBuilder};

let hash = 864761497199312896u64; // Board at the begining
let builder = BoardBuilder::from_u64(hash);
// Equivalent:
// let builder = BoardBuilder::from(hash);
let board = builder.build()?;
assert_eq!(board, Board::new());

pub fn put_dove( &mut self, pos_v: usize, pos_h: usize, color: Color, dove: Dove ) -> &mut Self

Puts dove of the player in color on the specified position.

A position is specified by two arguments pos_v and pos_h. The following diagram shows how the square is identified by two values.

  h 0   1   2   3
v +---+---+---+---+
0 |   |   |   |   |
  +---+---+---+---+
1 |   |   | * |   |
  +---+---+---+---+
2 |   |   |   |   |
  +---+---+---+---+
3 |   |   |   |   |
  +---+---+---+---+

For example, the square * is specified by pos_v=1 and pos_h=2.

If both values of pos_v and pos_h are from 0 to 3, color’s dove is put on that position. If the dove has already exist on the board, it moves to the specified position. If either of pos_v or pos_h is greater than 3, nothing is changed.

This method ignores rules of the game, i.e., for example, you can put a dove on an isolated position by this method. The build method, however, will return Err if the board to be built is illegal.

Examples

use std::str::FromStr;
use tokyodoves::{Board, BoardBuilder, Color, Dove};

let mut builder = BoardBuilder::new();
builder.put_dove(2, 1, Color::Red, Dove::A);
// +---+---+---+---+    +---+---+---+---+
// | b |   |   |   |    | b |   |   |   |
// +---+---+---+---+    +---+---+---+---+
// | B |   |   |   |    | B |   |   |   |
// +---+---+---+---+ => +---+---+---+---+
// |   |   |   |   |    |   | A |   |   |
// +---+---+---+---+    +---+---+---+---+
// |   |   |   |   |    |   |   |   |   |
// +---+---+---+---+    +---+---+---+---+
let board = builder.build()?;
let ans = BoardBuilder::from_str("b;B; A")?.build()?;
assert_eq!(board, ans);

pub fn remove_dove(&mut self, color: Color, dove: Dove) -> &mut Self

Removes dove of the player in color.

This method ignores rules of the game, i.e., for example, you can remove a boss by this method. The build method, however, will return Err if the board to be built is illegal.

Examples

use std::str::FromStr;
use tokyodoves::{Board, BoardBuilder, Color, Dove};

let mut builder = BoardBuilder::from_str("bT;B")?;
builder.remove_dove(Color::Red, Dove::T);
let board = builder.build()?;
assert_eq!(board, Board::new());

pub fn trim_outside_4x4(&mut self) -> &mut Self

Removes doves outside 4x4 field.

Examples

use std::str::FromStr;
use tokyodoves::{Board, BoardBuilder};

let bits = [[1 << 8, 1 << 4, 0, 0, 0, 0], [1, 0, 0, 0, 0, 0]];
let mut builder = BoardBuilder::from_u64_bits(bits);
// The above builder corresponds to the below:
// +---+---+---+---+
// | b |   |   |   | A
// +---+---+---+---+
// | B |   |   |   |
// +---+---+---+---+
// |   |   |   |   |
// +---+---+---+---+
// |   |   |   |   |
// +---+---+---+---+
// "A" is outside of the 4x4 field.
assert!(builder.build().is_err());
builder.trim_outside_4x4(); // "A" is trimmed (removed)
let board = builder.build()?;
assert_eq!(board, Board::new());

pub fn build_unchecked(&self) -> Board

Builds Board based on settings the builder knows without checking.

It skips all checks the build method does. Note that the resulting board may be strange state, for example, some dove is out of 4x4 region, some dove is isolated or some boss is not on the field. This method is more suitable than the build method when the validity of the builder is guaranteed by other means and you want to make the calculation time as short as possible.

Examples

use tokyodoves::{Board, BoardBuilder};

let builder = BoardBuilder::new();
assert_eq!(builder.build_unchecked(), Board::new());

pub fn build(&self) -> Result<Board, Error>

Builds Board based on settings the builder knows.

It checks the following points:

• All positions are single bit or zero
• Both bosses are on the field
• Multiple doves are not in one position
• All doves are in 4x4 region
• No dove is isolated from others

Errors

It returns Err if one of the checks above fails.

Examples

use tokyodoves::{Board, BoardBuilder};

let builder = BoardBuilder::new();
assert!(matches!(builder.build(), Ok(board) if board == Board::new()));

Trait Implementations

impl Clone for BoardBuilder

fn clone(&self) -> BoardBuilder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BoardBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BoardBuilder

fn default() -> Self

Returns the “default value” for a type.

impl From<[[u16; 6]; 2]> for BoardBuilder

fn from(bits: [[u16; 6]; 2]) -> Self

See the documentation of the from_u16_bits method.

impl From<[[u64; 6]; 2]> for BoardBuilder

fn from(bits: [[u64; 6]; 2]) -> Self

See the documentation of the from_u64_bits method.

impl From<u64> for BoardBuilder

fn from(hash: u64) -> Self

See the documentation of the from_u64 method.

impl FromStr for BoardBuilder

fn from_str(s: &str) -> Result<Self, Self::Err>

Creates BoardBuilder from a string expression.

It requires use std::str::FromStr to be called.

Errors

It returns Err if the same dove in the same color is included in the matrix.

Examples

The initial board

+---+---+---+---+
| b |   |   |   |
+---+---+---+---+
| B |   |   |   |
+---+---+---+---+
|   |   |   |   |
+---+---+---+---+
|   |   |   |   |
+---+---+---+---+

can be expressed, for example, as the following.

• "b ;B ; ; "
• "b---;B---;----;----"
• "b-.*;B~/^;_0@z;(=!?"
• "b;B"

The rules of the string expression:

• Use one character for each dove. See the table in the documentation of crate::color_dove_to_char to identify what character is suitable
• Use “;” to separate each row.
• Use some character except those represent some dove or “;” to express vacant square. (For readability, “ “ or “-” would be most suitable although this method accepts other characters.)
• You can omit the vacant squares between doves and “;” and extra rows.

Doves outside the 4x4 region are simply ignored.

use std::str::FromStr;
use tokyodoves::{Board, BoardBuilder};

let board_strs = [
    "b   ;B   ;    ;    ",
    "b---;B---;----;----",
    "b-.*;B~/^;_0@z;(=!?",
    "b;B",
    "b---;B---T;----;----", // "T" will be ignored because it is outside the 4x4 region
];
for board_str in board_strs {
    let board = BoardBuilder::from_str(board_str)?.build()?;
    assert_eq!(board, Board::new());
}

type Err = Error

The associated error which can be returned from parsing.

impl TryFrom<[[Option<(Color, Dove)>; 4]; 4]> for BoardBuilder

fn try_from( matrix: [[Option<(Color, Dove)>; 4]; 4] ) -> Result<Self, Self::Error>

See the documentation of the try_from_4x4_matrix method.

type Error = Error

The type returned in the event of a conversion error.

impl Copy for BoardBuilder