# open_ttt_lib
[![Crates.io](https://img.shields.io/crates/v/open_ttt_lib.svg)](https://crates.io/crates/open_ttt_lib)
[![Documentation](https://docs.rs/open_ttt_lib/badge.svg)](https://docs.rs/open_ttt_lib)
[![License](https://img.shields.io/crates/l/open_ttt_lib.svg)](https://github.com/j-richey/open_ttt_lib/blob/main/LICENSE.txt)
[![Build Status](https://travis-ci.com/j-richey/open_ttt_lib.svg?branch=main)](https://travis-ci.com/j-richey/open_ttt_lib)
[![Coverage Status](https://coveralls.io/repos/github/j-richey/open_ttt_lib/badge.svg?branch=main)](https://coveralls.io/github/j-richey/open_ttt_lib?branch=main)
[![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/)
Open source Rust library containing common Tic Tac Toe functionality.
## Overview
Tic Tac Toe is a game of strategy where two players, X and O, take turns placing their mark in a 3 x 3 gird.
The first player to get three marks in a row, column, or diagonal wins the game.
The game can also end in a draw, known as a *cat's game*.
This library contains logic to enforce the rules of Tic Tac Toe, manage the game's state,
and provides artificial intelligence algorithms for single player games.
## Usage
Add this to your `Cargo.toml`:
```toml
[dependencies]
open_ttt_lib = "0.2.2"
```
See the library's [documentation](https://docs.rs/open_ttt_lib/) for complete
details on the library's API.
## Examples
Below is a short example of using this library.
```rust
use open_ttt_lib::{ai, board, game};
fn main() -> Result<(), Box<game::Error>> {
// Create a game struct to manage the game.
let mut game = game::Game::new();
// Pick a position to place a mark. Positions are zero based.
// An error result is returned if the position is outside the bounds
// of the board, the position is already owned, or the game is over.
let position = board::Position { row: 0, column: 2 };
game.do_move(position)?;
// do_move() updates the game state. The state indicates the player
// who gets to place to next mark or, if the game is over, the
// outcome of the game.
match game.state() {
game::State::PlayerXMove => println!("X's turn."),
game::State::PlayerOMove => println!("O's turn."),
game::State::PlayerXWin(_) => println!("Game Over: X wins!"),
game::State::PlayerOWin(_) => println!("Game Over: O wins!"),
game::State::CatsGame => println!("Game Over: cat's game."),
};
// Have an AI opponent pick a move.
let opponent = ai::Opponent::new(ai::Difficulty::Medium);
if let Some(ai_position) = opponent.get_move(&game) {
game.do_move(ai_position)?;
};
Ok(())
}
```
The `examples` directory contains additional examples.
To run the examples, clone this repository then use `cargo run --example`. E.g:
```text
git clone https://github.com/j-richey/open_ttt_lib.git
cd open_ttt_lib
cargo run --example single_player
```
## Benchmarks
This library includes benchmarks that you can use to evaluate if the library
fits in with your performance goals. Use `cargo bench` to run the benchmark
suite:
```text
git clone https://github.com/j-richey/open_ttt_lib.git
cd open_ttt_lib
cargo bench
```
## Reporting Issues and Feature Requests
Please report issues and feel free to request new features using this project's
[GitHub issue tracker](https://github.com/j-richey/open_ttt_lib/issues).
## Changes
All notable changes are documented in the [CHANGELOG.md](https://github.com/j-richey/open_ttt_lib/blob/main/CHANGELOG.md).
## Contributing
Contributions are welcome! See [CONTRIBUTING.md](https://github.com/j-richey/open_ttt_lib/blob/main/CONTRIBUTING.md)
for details on how to contribute to this project.
## License
The library is licensed under the [MIT license](https://github.com/j-richey/open_ttt_lib/blob/main/LICENSE.txt).